member-console/status/MAINTAINING.md

Maintaining status/

Conventions for keeping status/ accurate and useful for contributors.

File responsibilities

File	What it tracks	Lifecycle
README.md	Thin index — where we are, current focus, links out. Deliberately short; no known-issues list (that's issues.md)	Updated at milestone boundaries and when focus shifts
strategy.md	Design alignment philosophy, migration approach	Rarely changes — update only when strategy shifts
fedwiki-service.md	The FedWiki Service tiers (the consumer roadmap) mapped to what the console implements	Updated as tiers land
milestones.md	Milestone definitions and future capabilities	Updated when milestones open, close, or are planned
issues.md	Bugs, improvements, design feedback (grouped by theme)	Updated as items are discovered or resolved
archive/	Resolved issues + completed-milestone detail moved out of active files	issues-resolved.md, milestones-completed.md — appended when items close
log/	Per-session development journals	Append-only — one file per notable session
explorations/<topic>-<yyyy-mm>/	Investigation records that fed a decision: research, drafts, comparisons, critiques, walk evidence; each directory has a README.md index saying what each file was and what superseded it	Frozen once the decision lands. The decision itself never lives here (see "Where things live")

When to update what

Starting a new milestone

1. Add the milestone to milestones.md with status and description.
2. Update README.md "Current focus" to reflect the new work.

Completing a milestone

1. Mark the milestone closed in milestones.md (condense it to the Completed table; move per-phase detail to archive/milestones-completed.md).
2. Update README.md "Where we are" and "Current focus".
3. Move any resolved items from issues.md to archive/issues-resolved.md.

Discovering a bug or improvement

1. Add it to issues.md with appropriate labels. (Known issues live here — keep them out of README.md.)

Fixing a bug

1. Mark the item resolved and move it to archive/issues-resolved.md (note the resolving change).

Writing a dev log

1. Create log/YYYY-MM-DD.md (add a suffix if multiple entries per day, e.g., 2026-03-26-entitlement-sets.md).
2. No index file needed — the directory listing is the index.

Where things live

Decide a file's home by what it is, before writing it. Nothing else goes at the top level of status/ or docs/.

Kind	Home	Examples
A convention: how the console does something, written for a reader who needs the rule, not the history	docs/ (with front matter; indexed in docs/README.md)	docs/identifiers.md, docs/operator-ux-conventions.md
The as-built shape of a domain model	docs/models/ (one card per model)	docs/models/resource-pools.md
A normative model rule or decision	membcons-db, mirrored into design/ by sync; never edited here	Doc 45, the Entity Key Contract
A change: proposal, design, specs, tasks	openspec/changes/<name>/, archived into openspec/changes/archive/ in the landing commit	2026-08-29-entity-keys
An investigation record: research, drafts, comparisons, critiques, captured evidence, walkthroughs	status/explorations/<topic>-<yyyy-mm>/ with a README.md index; frozen when the decision lands	explorations/identifiers-2026-08/
A known problem or a request to upstream	one entry in issues.md: title, labels, a short description, pointers; never an essay
Where a milestone stands	milestones.md
What happened in a session	log/YYYY-MM-DD.md

Corollaries:

• Code, migrations, and main specs cite docs/ and design/, never status/.
• When a decision lands, three things happen in the same commit: the convention page in docs/ is written or updated and citations point at it; the dossier moves under explorations/ with its index; the issue entry shrinks to issue shape with a pointer to the dossier.
• A file that argues for a decision is a dossier even if it is well written. A file that states the decision for a reader who was not there is a convention. Do not keep one file doing both jobs.
• Archives are frozen: paths inside openspec/changes/archive/ and status/archive/ are not rewritten when files move.

Labels

Labels in issues.md are freeform tags that will map to Gitea labels when issues are migrated. Current conventions:

Label	Meaning
bug	Something is broken
security	Security-related
operations	Deployment, infrastructure, runtime
dx	Developer experience
frontend	UI/UX work
auth	Authentication/authorization
fedwiki	FedWiki integration
testing	Test coverage
refactor	Code cleanup
design-feedback	Feedback to upstream research repo (design/)
infrastructure	Container, build, CI

Principles

• README.md is the entry point. If a contributor reads one file, it should be this one.
• issues.md is structured for migration. Each item should map cleanly to a Gitea issue (title, labels, description).
• milestones.md mirrors Gitea milestones. Title, description, status — not detailed breakdowns. Detailed artifacts live in openspec/changes/archive/.
• strategy.md is stable. It changes when the approach changes, not when work happens.
• Closed items move to archive/, not accumulate. Don't let resolved issues or completed milestones clutter active tracking — move them to archive/. The per-change artifacts in openspec/changes/archive/ preserve the full history.