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 the forge)	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
the forge tracker	Every issue, filed through the issue forms; agents read and write it through the Gitea MCP or API, never through a file in this repository	Continuously
design-feedback.md	Asks of the upstream design repository, kept until it has a tracker	As asks arise or are answered upstream
archive/	Completed-milestone detail moved out of active files, and the issues resolved before the tracker existed	milestones-completed.md — appended when a milestone closes; issues-resolved.yaml — frozen, one record per pre-forge issue, schema enforced by internal/lint (TestResolvedIssuesArchiveSchema)
log/	Per-session development journals	Append-only — one file per notable session
explorations/<topic>-<yyyy-mm>/	Local lab notebook for one decision: research, drafts, model runs, captures. Ignored by git	Harvested when the decision lands (see "Where things live"). Tracked files never cite a path under it

When to update what

Starting a new milestone

1. Create it on the forge with a plain goal name and a description that states what done looks like and its phases; file its first issues.
2. Update README.md "Current focus" to reflect the new work.

Landing a change

1. Harvest the notebook (the harvest skill, status/explorations/<topic>-<yyyy-mm>/): a general finding becomes or updates a docs/ page in its own words; the reasoning goes into the change's design.md; a problem becomes an issues.md entry; a reusable harness moves to a tracked home. The notebook keeps the rest.
2. Archive the change into openspec/changes/archive/ in the landing commit.
3. make lint is green: notebook-citation refuses any tracked path under status/explorations/ outside the frozen archives.

Completing a milestone

1. Close it on the forge; add a summary row and any phase record worth keeping to archive/milestones-completed.md.
2. Update README.md "Where we are" and "Current focus".
3. Close resolved issues on the forge with the reason in the last comment; archive/issues-resolved.yaml holds the history from before the tracker and is not appended to.

Discovering a bug or improvement

1. File it on the forge through the form for its kind; an agent files it through the Gitea MCP or API with the same fields. The writing rule is in CONTRIBUTING.md. (Known issues live on the forge — keep them out of README.md.)

Fixing a bug

1. Close the issue on the forge with the resolving change named in the last comment; the closed issue is its own archive record.

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>/, a local notebook git ignores; what it teaches is harvested when the decision lands
A known problem	one forge issue: a standalone title, the form's fields, one kind, its areas; never an essay
A request to upstream	one entry in design-feedback.md until the design repository has a tracker
Where a milestone stands	the forge tracker (its milestone and the issues in it)
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, the notebook is harvested in the same commit: a general finding becomes or updates a docs/ page in its own words, the decision's reasoning goes into the change's design.md, a problem becomes a forge issue, a reusable harness moves to a tracked home. The notebook itself stays local; no tracked file cites a path under status/explorations/, because another clone does not have it.
• A file that argues for a decision is a notebook page 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

The label set lives on the forge. Three scoped facets: kind/ (one per issue: bug, enhancement, debt, design, docs; defined by what closes the issue), area/ (every part of the console the fix lands in; not exclusive), priority/ (only on issues in the active milestone; an issue without one is unranked, not low). Free labels: security, privacy, accessibility, good-first-issue, upstream, and the closing reasons duplicate, invalid, wontfix. A label is renamed or retired on the forge; retire by archiving, never deleting, so the issues that carry it stay filterable.

Principles

• README.md is the entry point. If a contributor reads one file, it should be this one.
• An issue stands alone. Its title reads without its labels, its body follows its kind's form, and it names no milestone code, decision number, change name, model, date-as-narrative, production count or deployment; a reader who has never opened the repository can act on it.
• Milestones live on the forge. A milestone is a goal with a plain name, a description that says what done looks like, and the issues in it; 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.