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
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

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.

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.