Catalog recommended completion conventions (determinism-promotion path) #47

New Issue

Closed

opened 2026-07-14 18:17:52 +00:00 by jared · 1 comment

jared commented

2026-07-14 18:17:52 +00:00

Owner

Map: #31

Question

Define the catalog of recommended structural completion conventions (archive buckets, status: frontmatter, etc.) that hygiene nudges projects toward, converting subjective served_when classifier judgments into deterministic served_when_path checks — the determinism-promotion path from #43. Decide: which conventions make the catalog, where it lives, and how/when :calibrate (#42) or :check surfaces the nudge.

Map: #31 ## Question Define the catalog of recommended structural completion conventions (archive buckets, `status:` frontmatter, etc.) that hygiene nudges projects toward, converting subjective `served_when` classifier judgments into deterministic `served_when_path` checks — the determinism-promotion path from #43. Decide: which conventions make the catalog, where it lives, and how/when :calibrate (#42) or :check surfaces the nudge.

jared added the

wayfinder:grilling

label 2026-07-14 18:17:52 +00:00

jared referenced this issue

2026-07-14 18:18:26 +00:00

Assemble the spec + ADR set #46

jared self-assigned this 2026-07-14 20:00:22 +00:00

~~jared referenced this issue 2026-07-14 20:09:54 +00:00~~

Wayfinder map: lifecycle-aware doc hygiene (ruthless os-doc-hygiene) #31

jared commented

2026-07-14 20:13:10 +00:00

Author

Owner

RESOLUTION: completion-conventions catalog defined — all three sub-questions decided with the user.

Catalog contents (v1): exactly two conventions.
- archive-bucket — "done" = the file moved into a sibling archive/ dir (docs/plans/x.md → docs/plans/archive/x.md). Graduates a rule to served_when_path: <dir>/archive/{name}. Precedent: openspec changes.
- status-frontmatter — "done" = a status: shipped|done frontmatter key; file stays put; scanner reads frontmatter.
Successor-artifact checks ("served when a downstream doc mentions it") stay in the fog until a calibration pass demands one. A two-entry catalog that gets adopted beats a taxonomy.
Where it lives: plugins/os-doc-hygiene/conventions.json, global-only. Machine-readable so the deterministic pipeline can emit nudges without an LLM. Each entry: name, what it proves, the served_when_path / frontmatter template a rule graduates to, and a one-line human pitch. No per-project override — the catalog only recommends; adoption lands in the project's own rulebook.
Nudge surfacing: both skills, split by capability.
- :check names promotion candidates in every report ("this rule forces confirms because X is a judgment call — adopt archive-bucket and it goes silent"). Deterministic, recurring — confirm-fatigue stays visible as the incentive (#43 item 7).
- :calibrate may go further and DRAFT the adoption — the graduated rule plus the file moves — for human approval. It proposes, never applies unasked, per #42's model-proposes/human-disposes constraint.

Handed to #46: conventions.json is a new plugin artifact the spec must define; the :check report gains a promotion-candidates section; fold under the determinism-promotion ADR already flagged by #43.

RESOLUTION: completion-conventions catalog defined — all three sub-questions decided with the user. 1. **Catalog contents (v1): exactly two conventions.** - **archive-bucket** — "done" = the file moved into a sibling archive/ dir (docs/plans/x.md → docs/plans/archive/x.md). Graduates a rule to `served_when_path: <dir>/archive/{name}`. Precedent: openspec changes. - **status-frontmatter** — "done" = a `status: shipped|done` frontmatter key; file stays put; scanner reads frontmatter. Successor-artifact checks ("served when a downstream doc mentions it") stay in the fog until a calibration pass demands one. A two-entry catalog that gets adopted beats a taxonomy. 2. **Where it lives: `plugins/os-doc-hygiene/conventions.json`, global-only.** Machine-readable so the deterministic pipeline can emit nudges without an LLM. Each entry: name, what it proves, the served_when_path / frontmatter template a rule graduates to, and a one-line human pitch. No per-project override — the catalog only recommends; adoption lands in the project's own rulebook. 3. **Nudge surfacing: both skills, split by capability.** - `:check` names promotion candidates in every report ("this rule forces confirms because X is a judgment call — adopt archive-bucket and it goes silent"). Deterministic, recurring — confirm-fatigue stays visible as the incentive (#43 item 7). - `:calibrate` may go further and DRAFT the adoption — the graduated rule plus the file moves — for human approval. It proposes, never applies unasked, per #42's model-proposes/human-disposes constraint. **Handed to #46:** conventions.json is a new plugin artifact the spec must define; the :check report gains a promotion-candidates section; fold under the determinism-promotion ADR already flagged by #43.

jared closed this issue

2026-07-14 20:13:10 +00:00

jared referenced this issue

2026-07-14 20:29:38 +00:00

Assemble the spec + ADR set #46

jared referenced this issue

2026-07-14 20:30:52 +00:00

Wayfinder map: lifecycle-aware doc hygiene (ruthless os-doc-hygiene) #31