Files

T

cgalo5758 a5a4b9c591 Gate archives on notebook citations and add the harvest skill

A notebook's lessons survive only if they are written into a tracked
home before the decision lands, so landing a change now has three
pieces. The contract: a "Landing a change" section in MAINTAINING.md and
a fifth item in the UI definition of done. The labor: a harvest skill
that inventories the notebook, names each file's kind and routes
findings to the owning docs page, reasoning to the change's design.md,
problems to issues.md and reusable tools to a tracked home. The gate:
scripts/notebook-citations.sh, a git grep over what git would commit for
the notebook's directory shape, which make lint runs after the program's
own lint, and scripts/archive-gate.sh, which refuses an mv into the
archive or an openspec archive while the check reports hits.

The gate is one script that any harness calls with the command it is
about to run; Claude Code reaches it through a PreToolUse hook and
opencode through a plugin. Both checks live in scripts/ rather than the
lint subcommand because they are repository hygiene, not part of the
shipped program. The generated openspec-archive-change skill is not
edited; the post-archive reminder carries the harvest step instead.

2026-09-19 19:47:15 -05:00

6.2 KiB

Raw Blame History

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

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

Landing a change

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.
Archive the change into openspec/changes/archive/ in the landing commit.
make lint is green: notebook-citation refuses any tracked path under status/explorations/ outside the frozen archives.

Completing a milestone

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

Discovering a bug or improvement

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

Fixing a bug

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

Writing a dev log

Create log/YYYY-MM-DD.md (add a suffix if multiple entries per day, e.g., 2026-03-26-entitlement-sets.md).
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 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, 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 an issues.md entry, 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

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.

6.2 KiB Raw Blame History