docs: docs-strategy-2026 — Phase A + Plays 1a, 3a, 6, 7, 8 (safe-parallel)#184
Closed
jukka-matti wants to merge 17 commits into
Closed
docs: docs-strategy-2026 — Phase A + Plays 1a, 3a, 6, 7, 8 (safe-parallel)#184jukka-matti wants to merge 17 commits into
jukka-matti wants to merge 17 commits into
Conversation
Phase A of the docs-strategy-2026 plan (~3h warm-up). Executes the top 4 consolidation moves from audit Agent 2 (see plan ~/.claude/plans/i-was-wondering-that-effervescent-boole.md §7.2 + §8): - decision-log.md "Wedge pivot" entry: ~2500 → ~280 words (~88% reduction). Cite ADR-082 §Decision for the V1 surface table and §Pricing rationale. Preserves preconditions + canonical pointers + brainstorm-transcript ref. - 01-vision/methodology.md frontmatter: reframe "canonical lives at vision spec" → "paired companions". Vision spec §2 = product-decision SoT; methodology.md = teaching-context SoT. Reconciliation continuous via the docs-strategy-2026 Steward loop, not a one-shot edit. - OVERVIEW.md §The journey model: ~200 → ~70 words; preserves FRAME→SCOUT→INVESTIGATE→IMPROVE spine + Four Lenses + Investigation Wall; cross-links USER-JOURNEYS + methodology for detail. - 01-vision/positioning.md: add cross-link to business-bible §Strategic Hypotheses H1–H10 (the strategic framing that underpins it). - CLAUDE.md: new "Strategic context" bullet in §Where to look surfacing business-bible H1–H10, positioning, methodology. Zero-infra warm-up before Play 1 (folder restructure) — validates the addendum-thread pattern at human scale + the worktree execution flow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…R-083) Create three foundation docs that the rest of Play 1 rests on: - 2026-05-16-docs-strategy-memo.md: 1-page CTO memo (§8 of plan) - 2026-05-16-docs-strategy-design.md: full strategy spec (§§1-7, 10) - adr-083-eight-purpose-doc-taxonomy.md: ADR for the schema change ADR-083 captures the 8-purpose × 4-tier two-axis schema, STATUS alias map (22→4), AUDIENCE alias map (14→3), CATEGORY→topic-tags replacement, and the migration approach for Play 1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…pic, 3 AUDIENCE) + add purpose/tier + drift fields Per ADR-083: two-axis schema (8 purposes × 4 tiers) replaces the over-engineered 22-STATUS × 18-CATEGORY × 14-AUDIENCE triplet. scripts/docs-frontmatter-schema.mjs: - Add PURPOSE enum (8 values) and TIER enum (4 values) - Collapse STATUS from 22 → 4 canonical values - Export STATUS_ALIAS_MAP (11 old→new mappings) for transitional validation - Export AUDIENCE_ALIAS_MAP (14 old→new mappings) - Remove CATEGORY enum; topic tags are now free-form - Collapse AUDIENCE from 14 → 3 canonical values (human/agent/both) - Add new optional fields: purpose, tier, last-verified, verified-against-commit, supersedes, related - Update classify() for new folder paths (Play 1 prep) scripts/check-doc-frontmatter.mjs: - Warn (not fail) on aliased STATUS/AUDIENCE values - Hard-fail on unknown PURPOSE/TIER when present - Add --report mode: counts docs missing purpose + tier scripts/docs-frontmatter-fix.mjs: - Apply STATUS_ALIAS_MAP and AUDIENCE_ALIAS_MAP - Handle inline array audience form (audience: [analyst, engineer]) - Backfill purpose + tier via path heuristics (all 521 docs covered) Applied to all 521 docs: 0 hard violations, 0 transitional warnings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ge-router + store-state-glossary) New docs at docs/agent-context/ (TEMP location; will move to docs/living/agent-context/ in Play 1b): - onboarding-quick-start.md: 5-minute agent orientation covering wedge V1 direction, hard invariants, where-to-look table, and common pitfalls (Math.random, hex colors, --no-verify, root-cause language) - package-router.md: 20-row routing table mapping work areas → primary CLAUDE.md + related CLAUDEs + ADRs + rules/invariants + suggested skills - store-state-glossary.md: full glossary of all 7 stores × 3 layers (Document/Annotation/View) per ADR-078 + F4, with top fields, persistence details, and hard rules per store All 3 docs use the new two-axis schema (purpose, tier, audience, topic, last-verified) introduced in the docs-strategy-2026 plan. Verified against packages/stores/src/*.ts at commit 5ee58dc. pnpm docs:check passes (527 docs validated, no issues). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-router + store-state-glossary) Closes the 4%-of-living agent-context gap identified in plan §7.1. Three skills for fresh subagent dispatch orientation (Play 3 Tier 1): - agent-context-quickstart: loads docs/agent-context/onboarding-quick-start.md; description triggers on any "start of session", "new subagent", or "need context" phrasing; covers wedge V1 direction, hard invariants, where-to-look, and common pitfalls - package-router: routes work areas (canvas, stats, charts, stores, i18n, azure, pwa, ui, hooks, coscout, response-paths, capability/yamazumi/defect/performance/process-flow modes, projects tab, investigation wall, evidence map, sample data) to primary CLAUDE.md + related CLAUDEs + ADRs + rules; description triggers on "which package", "where to look", "which CLAUDE.md" - store-state-glossary: covers all 7 stores × 3 layers per ADR-078 + F4; description triggers on "which store", "what state lives", "store state" phrasing; links to full doc and packages/stores/CLAUDE.md All 3 skills follow the SKILL.md spec (name ≤64 chars, description with what+when, body ≤200 lines). Skills use force-add to override .claude/.gitignore — standard pattern for project-scoped skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ath references Renames 6 constraint files (stats, testing, charts, coscout-prompts, i18n, azure-storage) from .claude/rules/ to .claude/invariants/ to clarify their purpose as policy-level invariants (not procedure routers). Updates all active references in CLAUDE.md, package-router.md, and two implementation docs to the new path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Creates .claude/INVARIANTS.md as the single entry-point for all VariScout cross-cutting non-negotiables. Organises invariants into three tiers — hard (lint/test-enforced), soft (convention + reviewer), and topic-scoped (load on demand) — with canonical home and enforcement mechanism cited for each. Identifies two open enforcement gaps (Math.random and Tailwind @source) for follow-up in investigations.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…log enforcement gaps Links root CLAUDE.md §Invariants and onboarding-quick-start.md §Hard Invariants to the new .claude/INVARIANTS.md index instead of restating the full invariant list. Updates agent-context-quickstart skill to explicitly load INVARIANTS.md in its How to Use procedure. Logs two open enforcement gaps (Math.random ban, Tailwind @source check) to docs/investigations.md as candidates for Play 7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ailwind architecture doc Adds scripts/docs/gen-arch.mjs that walks package.json files (dep graph), tsconfig.json paths (sub-path export map), and apps/*/src/index.css (@source directives) to emit docs/05-technical/architecture-generated.md. Wired as pnpm docs:gen-arch in root package.json. Pre-push hook regenerates and fails if checked-in version is stale, surfacing drift immediately. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…k from technical index Adds docs/05-technical/architecture-generated.md (initial committed version). Updates docs/05-technical/index.md to add inbound link so the doc is not an orphan (required by pnpm docs:check orphan check). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…60/068/069 + prompt rule Creates docs/01-vision/coscout-ax-design.md as the single canonical AX-design surface for CoScout: persona, voice, tier-gated behaviors (table), five-pillar knowledge architecture, three-boundary safety, prompt engineering link, tool-calling, voice input, eval discipline, mode-aware methodology coaching, and related artifacts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…onical AX-design - ADR-060, ADR-068, ADR-069: add related: [coscout-ax-design] to frontmatter + brief "See canonical AX design" note near each ADR title - .claude/invariants/coscout-prompts.md: add related: [coscout-ax-design] + see-also note at bottom - docs/agent-context/package-router.md: update CoScout row to point at coscout-ax-design.md as canonical entry point (was packages/core/CLAUDE.md) - .claude/INVARIANTS.md: update CoScout-prompts topic-scoped row to reference coscout-ax-design.md as the first-load for CoScout work Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The Play 7 gen-arch script outputs compact markdown tables; lint-staged prettier reformatted them on commit, causing the pre-push staleness check (`git diff --exit-code` after regeneration) to fire on every push. Fix: add `.prettierignore` excluding the generated file so committed content matches the script's output verbatim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…convention doc
Discipline gap surfaced by the 2026-05-17 wedge-amendment incident: a mid-flight
design change to wedge spec was captured as `2026-05-16-improve-tab-amendment-design.md`
(orphan side spec), invisible to a fresh session reading only the canonical wedge spec.
Convention alone didn't prevent it; mechanical enforcement does.
Strategy spec (edited in place, dogfooding the principle):
- §1 Context: note the discipline-drift failure mode + why mechanical enforcement matters
- §2.6 per-purpose table: design row → edit-in-place; remember row → append-only
- §2.7 NEW: Doc Discipline (SSoT by doc type). Design specs edit-in-place; ADRs
amendment-block-at-bottom; decision-log append-only; generated never-hand-edit;
plan files ephemeral. Anti-pattern table + spec lifecycle states + edit-in-place
mechanics + "decision-log as temporal index" framing.
- Play 2b: revised from "addendum threads on all living docs" (wrong-shape — conflated
design specs with ADRs) → "SSoT discipline by doc type" with validator forbidding
`*-amendment-*.md` / `*-revision-*.md` / `*-update-*.md` filenames + lifecycle-state
enforcement. Marked safe-parallel — ships now, no Play 1b dependency.
- §4 migration: shipped/deferred status table reflecting current execution state
- §10 risks: 3 new rows (discipline drift, validator false-positives, body staleness)
Memo: aligned §What we're changing + §plays item 2 + §What we kill; added `last-verified`.
NEW canonical: `docs/agent-context/doc-discipline.md` — focused reference (~150 lines)
loaded by `agent-context-quickstart` skill on session start. Includes:
- Doc-types + update-patterns table (7 types)
- Anti-patterns table with right-pattern column
- Spec lifecycle states (draft → active → delivered → superseded → archived)
- Edit-in-place mechanics for design specs (5-step procedure)
- Decision tree: "I need to change a canonical doc → which pattern?"
- Origin story citing the wedge-amendment incident
agent-context-quickstart SKILL.md: wires doc-discipline.md as step 4 ("If your task
involves editing ANY canonical doc"). Added to Supporting Documents list.
This commit dogfoods the principle: strategy spec edited in place, not as an
`*-amendment-design.md` side file. Plan file at ~/.claude/plans/ updated separately
with a banner pointing to the canonical spec as the SoT going forward.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Routine regen after staleness check (per Play 7 pre-push convention). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Question: should amendment/relevance info be at the top of files? Does wikilink structure preserve that? Answer: YES, top. Frontmatter is for tooling; banner is for readers (humans + agents). Wikilinks preserve graph structure but are passive at read time — banners are active. Industry convention (MDN, Stripe, IETF, Wikipedia, Tailscale): status at top, amendments at bottom (ADRs only). Added to doc-discipline.md §Reader-first banners: - Required/recommended matrix per condition (status: superseded, supersedes:, recent material edit, delivered, ADR with amendments) - 6 concrete banner templates (superseded, recent edit, active build, delivered, ADR amended, archived) - Origin story citing wedge-amendment incident - "Wikilinks don't substitute for banners" explanation - Banner + frontmatter both required (machine vs reader) - Play 2b validator extensions for banner enforcement (4 new rules) Added to strategy spec §2.7: - New subsection "Reader-first banners at the top" pointing to discipline doc - Edit-in-place mechanics step 3 now includes "add status banner" - Play 2b validator scope extended in mechanics section Dogfooded: strategy spec itself now carries a banner at top noting active build via PR #184 + last material edit 2026-05-17. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…log format + classify agent manifests Audit gaps surfaced after yesterday's discipline shipment: 1. "One canonical home per concept" was buried as an anti-pattern; now stated affirmatively as Principle #2 2. Decision-log entry format was informal; now codified with edit-type vocabulary for Play 2c toolbox parsing 3. CLAUDE.md/AGENTS.md/llms.txt weren't classified in the doc-types table Both strategy spec §2.7 and doc-discipline.md updated in parallel: Core principles (in priority order): 1. Doc-type discipline 2. One canonical home per concept (Play 4 enforces) 3. Reader-first banners 4. Decision-log as temporal index Wedge-amendment incident reframed as a simultaneous violation of principles 1+2+3, making clear why all four need mechanical enforcement (Play 2b). Doc types extended in the at-a-glance list: investigations + memory + agent manifests added (was 5 types covered, now 8). Agent manifests get an explicit row in the doc-discipline.md table noting they're the "first read" surface every agent dispatch loads — keep tight, CLAUDE.md size budget enforced. Decision-log entry standard format: - YYYY-MM-DD — <title ≤80c>. <edit-type>: <doc>#<section> [supersedes <prior>]. Why: <one-sentence>. Commit: <sha>. PR: #N. Related: [[<id>]]. With edit-type vocabulary (spec edit / ADR amendment / new ADR / supersession / archived / new spec) for machine-parseable categorization by Play 2c toolbox. Lists what NOT to put in entries (no rationale paragraphs, no restated spec content, no duplicated info — one decision = one entry). Strategy spec banner updated to reflect today's second material edit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
Owner
Author
|
Superseded by #199. Main shipped 21 PRs (wedge V1 + Phase C) while this PR was open, making ~half of #184's content (Phase A wedge-content edits) obsolete. #199 cherry-picks only the still-novel infrastructure onto a fresh branch off latest main + adds alignment fixes (7-tab nav, €120, 3 personas) + the named-future canonical status correction. The thinking work survives in #199's brainstorm transcript at docs/ephemeral/transcripts/. |
jukka-matti
added a commit
that referenced
this pull request
May 17, 2026
… latest main) (#199) * docs: foundational artifacts for docs-strategy-2026 (memo + spec + ADR-083) Create three foundation docs that the rest of Play 1 rests on: - 2026-05-16-docs-strategy-memo.md: 1-page CTO memo (§8 of plan) - 2026-05-16-docs-strategy-design.md: full strategy spec (§§1-7, 10) - adr-083-eight-purpose-doc-taxonomy.md: ADR for the schema change ADR-083 captures the 8-purpose × 4-tier two-axis schema, STATUS alias map (22→4), AUDIENCE alias map (14→3), CATEGORY→topic-tags replacement, and the migration approach for Play 1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(scripts): collapse frontmatter schema (22→4 STATUS, free-form topic, 3 AUDIENCE) + add purpose/tier + drift fields Per ADR-083: two-axis schema (8 purposes × 4 tiers) replaces the over-engineered 22-STATUS × 18-CATEGORY × 14-AUDIENCE triplet. scripts/docs-frontmatter-schema.mjs: - Add PURPOSE enum (8 values) and TIER enum (4 values) - Collapse STATUS from 22 → 4 canonical values - Export STATUS_ALIAS_MAP (11 old→new mappings) for transitional validation - Export AUDIENCE_ALIAS_MAP (14 old→new mappings) - Remove CATEGORY enum; topic tags are now free-form - Collapse AUDIENCE from 14 → 3 canonical values (human/agent/both) - Add new optional fields: purpose, tier, last-verified, verified-against-commit, supersedes, related - Update classify() for new folder paths (Play 1 prep) scripts/check-doc-frontmatter.mjs: - Warn (not fail) on aliased STATUS/AUDIENCE values - Hard-fail on unknown PURPOSE/TIER when present - Add --report mode: counts docs missing purpose + tier scripts/docs-frontmatter-fix.mjs: - Apply STATUS_ALIAS_MAP and AUDIENCE_ALIAS_MAP - Handle inline array audience form (audience: [analyst, engineer]) - Backfill purpose + tier via path heuristics (all 521 docs covered) Applied to all 521 docs: 0 hard violations, 0 transitional warnings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(agent-context): add 3 Tier 1 supporting docs (quickstart + package-router + store-state-glossary) New docs at docs/agent-context/ (TEMP location; will move to docs/living/agent-context/ in Play 1b): - onboarding-quick-start.md: 5-minute agent orientation covering wedge V1 direction, hard invariants, where-to-look table, and common pitfalls (Math.random, hex colors, --no-verify, root-cause language) - package-router.md: 20-row routing table mapping work areas → primary CLAUDE.md + related CLAUDEs + ADRs + rules/invariants + suggested skills - store-state-glossary.md: full glossary of all 7 stores × 3 layers (Document/Annotation/View) per ADR-078 + F4, with top fields, persistence details, and hard rules per store All 3 docs use the new two-axis schema (purpose, tier, audience, topic, last-verified) introduced in the docs-strategy-2026 plan. Verified against packages/stores/src/*.ts at commit 5ee58dc. pnpm docs:check passes (527 docs validated, no issues). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(skills): add 3 Tier 1 agent-context skills (quickstart + package-router + store-state-glossary) Closes the 4%-of-living agent-context gap identified in plan §7.1. Three skills for fresh subagent dispatch orientation (Play 3 Tier 1): - agent-context-quickstart: loads docs/agent-context/onboarding-quick-start.md; description triggers on any "start of session", "new subagent", or "need context" phrasing; covers wedge V1 direction, hard invariants, where-to-look, and common pitfalls - package-router: routes work areas (canvas, stats, charts, stores, i18n, azure, pwa, ui, hooks, coscout, response-paths, capability/yamazumi/defect/performance/process-flow modes, projects tab, investigation wall, evidence map, sample data) to primary CLAUDE.md + related CLAUDEs + ADRs + rules; description triggers on "which package", "where to look", "which CLAUDE.md" - store-state-glossary: covers all 7 stores × 3 layers per ADR-078 + F4; description triggers on "which store", "what state lives", "store state" phrasing; links to full doc and packages/stores/CLAUDE.md All 3 skills follow the SKILL.md spec (name ≤64 chars, description with what+when, body ≤200 lines). Skills use force-add to override .claude/.gitignore — standard pattern for project-scoped skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(.claude): rename .claude/rules/ → .claude/invariants/ + update path references Renames 6 constraint files (stats, testing, charts, coscout-prompts, i18n, azure-storage) from .claude/rules/ to .claude/invariants/ to clarify their purpose as policy-level invariants (not procedure routers). Updates all active references in CLAUDE.md, package-router.md, and two implementation docs to the new path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(.claude): add INVARIANTS.md synthesis index Creates .claude/INVARIANTS.md as the single entry-point for all VariScout cross-cutting non-negotiables. Organises invariants into three tiers — hard (lint/test-enforced), soft (convention + reviewer), and topic-scoped (load on demand) — with canonical home and enforcement mechanism cited for each. Identifies two open enforcement gaps (Math.random and Tailwind @source) for follow-up in investigations.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: replace prose invariant duplication with [[invariant]] links + log enforcement gaps Links root CLAUDE.md §Invariants and onboarding-quick-start.md §Hard Invariants to the new .claude/INVARIANTS.md index instead of restating the full invariant list. Updates agent-context-quickstart skill to explicitly load INVARIANTS.md in its How to Use procedure. Logs two open enforcement gaps (Math.random ban, Tailwind @source check) to docs/investigations.md as candidates for Play 7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(scripts): add docs:gen-arch — auto-generate dependency/exports/Tailwind architecture doc Adds scripts/docs/gen-arch.mjs that walks package.json files (dep graph), tsconfig.json paths (sub-path export map), and apps/*/src/index.css (@source directives) to emit docs/05-technical/architecture-generated.md. Wired as pnpm docs:gen-arch in root package.json. Pre-push hook regenerates and fails if checked-in version is stale, surfacing drift immediately. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(system): add initial auto-generated architecture doc + cross-link from technical index Adds docs/05-technical/architecture-generated.md (initial committed version). Updates docs/05-technical/index.md to add inbound link so the doc is not an orphan (required by pnpm docs:check orphan check). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(design): add canonical CoScout AX-design doc consolidating ADR-060/068/069 + prompt rule Creates docs/01-vision/coscout-ax-design.md as the single canonical AX-design surface for CoScout: persona, voice, tier-gated behaviors (table), five-pillar knowledge architecture, three-boundary safety, prompt engineering link, tool-calling, voice input, eval discipline, mode-aware methodology coaching, and related artifacts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: cross-link constituent CoScout ADRs + invariant + router to canonical AX-design - ADR-060, ADR-068, ADR-069: add related: [coscout-ax-design] to frontmatter + brief "See canonical AX design" note near each ADR title - .claude/invariants/coscout-prompts.md: add related: [coscout-ax-design] + see-also note at bottom - docs/agent-context/package-router.md: update CoScout row to point at coscout-ax-design.md as canonical entry point (was packages/core/CLAUDE.md) - .claude/INVARIANTS.md: update CoScout-prompts topic-scoped row to reference coscout-ax-design.md as the first-load for CoScout work Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(prettier): exclude auto-generated arch doc + regenerate The Play 7 gen-arch script outputs compact markdown tables; lint-staged prettier reformatted them on commit, causing the pre-push staleness check (`git diff --exit-code` after regeneration) to fire on every push. Fix: add `.prettierignore` excluding the generated file so committed content matches the script's output verbatim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(strategy): revise Play 2b to SSoT-by-doc-type discipline + ship convention doc Discipline gap surfaced by the 2026-05-17 wedge-amendment incident: a mid-flight design change to wedge spec was captured as `2026-05-16-improve-tab-amendment-design.md` (orphan side spec), invisible to a fresh session reading only the canonical wedge spec. Convention alone didn't prevent it; mechanical enforcement does. Strategy spec (edited in place, dogfooding the principle): - §1 Context: note the discipline-drift failure mode + why mechanical enforcement matters - §2.6 per-purpose table: design row → edit-in-place; remember row → append-only - §2.7 NEW: Doc Discipline (SSoT by doc type). Design specs edit-in-place; ADRs amendment-block-at-bottom; decision-log append-only; generated never-hand-edit; plan files ephemeral. Anti-pattern table + spec lifecycle states + edit-in-place mechanics + "decision-log as temporal index" framing. - Play 2b: revised from "addendum threads on all living docs" (wrong-shape — conflated design specs with ADRs) → "SSoT discipline by doc type" with validator forbidding `*-amendment-*.md` / `*-revision-*.md` / `*-update-*.md` filenames + lifecycle-state enforcement. Marked safe-parallel — ships now, no Play 1b dependency. - §4 migration: shipped/deferred status table reflecting current execution state - §10 risks: 3 new rows (discipline drift, validator false-positives, body staleness) Memo: aligned §What we're changing + §plays item 2 + §What we kill; added `last-verified`. NEW canonical: `docs/agent-context/doc-discipline.md` — focused reference (~150 lines) loaded by `agent-context-quickstart` skill on session start. Includes: - Doc-types + update-patterns table (7 types) - Anti-patterns table with right-pattern column - Spec lifecycle states (draft → active → delivered → superseded → archived) - Edit-in-place mechanics for design specs (5-step procedure) - Decision tree: "I need to change a canonical doc → which pattern?" - Origin story citing the wedge-amendment incident agent-context-quickstart SKILL.md: wires doc-discipline.md as step 4 ("If your task involves editing ANY canonical doc"). Added to Supporting Documents list. This commit dogfoods the principle: strategy spec edited in place, not as an `*-amendment-design.md` side file. Plan file at ~/.claude/plans/ updated separately with a banner pointing to the canonical spec as the SoT going forward. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: regenerate arch doc Routine regen after staleness check (per Play 7 pre-push convention). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(discipline): add reader-first status banner principle (top of file) Question: should amendment/relevance info be at the top of files? Does wikilink structure preserve that? Answer: YES, top. Frontmatter is for tooling; banner is for readers (humans + agents). Wikilinks preserve graph structure but are passive at read time — banners are active. Industry convention (MDN, Stripe, IETF, Wikipedia, Tailscale): status at top, amendments at bottom (ADRs only). Added to doc-discipline.md §Reader-first banners: - Required/recommended matrix per condition (status: superseded, supersedes:, recent material edit, delivered, ADR with amendments) - 6 concrete banner templates (superseded, recent edit, active build, delivered, ADR amended, archived) - Origin story citing wedge-amendment incident - "Wikilinks don't substitute for banners" explanation - Banner + frontmatter both required (machine vs reader) - Play 2b validator extensions for banner enforcement (4 new rules) Added to strategy spec §2.7: - New subsection "Reader-first banners at the top" pointing to discipline doc - Edit-in-place mechanics step 3 now includes "add status banner" - Play 2b validator scope extended in mechanics section Dogfooded: strategy spec itself now carries a banner at top noting active build via PR #184 + last material edit 2026-05-17. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(discipline): elevate 4 affirmative principles + codify decision-log format + classify agent manifests Audit gaps surfaced after yesterday's discipline shipment: 1. "One canonical home per concept" was buried as an anti-pattern; now stated affirmatively as Principle #2 2. Decision-log entry format was informal; now codified with edit-type vocabulary for Play 2c toolbox parsing 3. CLAUDE.md/AGENTS.md/llms.txt weren't classified in the doc-types table Both strategy spec §2.7 and doc-discipline.md updated in parallel: Core principles (in priority order): 1. Doc-type discipline 2. One canonical home per concept (Play 4 enforces) 3. Reader-first banners 4. Decision-log as temporal index Wedge-amendment incident reframed as a simultaneous violation of principles 1+2+3, making clear why all four need mechanical enforcement (Play 2b). Doc types extended in the at-a-glance list: investigations + memory + agent manifests added (was 5 types covered, now 8). Agent manifests get an explicit row in the doc-discipline.md table noting they're the "first read" surface every agent dispatch loads — keep tight, CLAUDE.md size budget enforced. Decision-log entry standard format: - YYYY-MM-DD — <title ≤80c>. <edit-type>: <doc>#<section> [supersedes <prior>]. Why: <one-sentence>. Commit: <sha>. PR: #N. Related: [[<id>]]. With edit-type vocabulary (spec edit / ADR amendment / new ADR / supersession / archived / new spec) for machine-parseable categorization by Play 2c toolbox. Lists what NOT to put in entries (no rationale paragraphs, no restated spec content, no duplicated info — one decision = one entry). Strategy spec banner updated to reflect today's second material edit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(agent-context): align with current main reality — 7-tab nav, €120, 3 personas, Math.random ESLint enforced Stale-reference fix pass after cherry-picking PR #184's infrastructure onto fresh branch off latest main. Aligns agent-context surface with what shipped today: - `docs/agent-context/onboarding-quick-start.md`: - €99 → €120; 6-tab → 7-tab nav - "Improve = stage inside Projects" → "Improve = top-level verb tab" (per 2026-05-16 Improve-tab amendment); Project stages collapsed to Charter→Approach→Sustainment - Add 3 personas inside Project: Lead (full edit + manages membership) / Member (full edit) / Sponsor (Report-only at V1, signoff out-of-band). Every subagent loading quickstart sees all 3 on first read. - Tier-gating "fully retired" (no more isPaidTier() checks) - VariScout Process named-future now points to `docs/01-vision/variscout-process/` - `.claude/skills/agent-context-quickstart/SKILL.md`: same updates (Key Facts section) - `docs/agent-context/package-router.md`: Projects-tab row updated — "Lead/Member/Sponsor roles" → "3 personas: Lead/Member/Sponsor"; stage list shortened; Improve as top-level noted; €120 pricing - Root `CLAUDE.md`: add "3 personas within each Project (Lead/Member/Sponsor)" to the strategic-direction line (the rest was already current — €120, 7-tab, Improve restored) - `.claude/INVARIANTS.md` §Enforcement Gaps: Math.random ban marked RESOLVED 2026-05-17 via PR #198 (Tier 1 Math.random retirement + ESLint guard shipped) Per user's terminology decision (2026-05-17): use "3 personas" framing consistently in agent-context docs (simpler than wedge spec's "1 persona + 3 ACL roles"). Specialist is the ICP description, not a 4th persona. Open question logged for follow-up: unify wedge spec terminology to match (out of scope for this PR). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(transcripts): promote docs-strategy-2026 brainstorm plan file to repo transcript Per the doc-discipline.md ephemeral-promotion rule: plan files in ~/.claude/plans/ are session-private by default; SELECTIVE promotion to docs/ephemeral/transcripts/ for LANDMARK sessions. The docs-strategy-2026 brainstorm qualifies — it produced the foundational strategy + ADR-083 + the SSoT-by-doc-type discipline. What this preserves in repo: - Full design journey (8 purposes × 4 tiers, audit findings from Agent 1 + Agent 2) - Mid-session pivots (wedge-conflict surfaced → split Play 1 into 1a safe + 1b deferred; original "addendum threads" Play 2b revised to SSoT discipline after the wedge-amendment incident) - §11 post-PR-184 recalibration (cherry-pick recovery plan + Play 1b/2a reorder + 3-personas terminology decision) Frontmatter added: purpose: remember, tier: ephemeral, status: archived, audience: human, topic: [docs-strategy, transcript, brainstorm]. Top banner converted from "plan-file pointing-at-canonical" to "archived transcript pointing-at-canonical" — the file IS now the canonical historical record. Inbound link added from strategy spec (avoids orphan check). Future readers see: spec for "what" (current intent); transcript for "why each decision was made". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(schema): add 'named-future' to STATUS_ALIAS_MAP The user's PR #193 (VariScout Process named-future capture) created 8 docs at `docs/01-vision/variscout-process/` with `status: 'named-future'`. That value was valid in the old 22-value STATUS enum but missing from my collapsed 4-value canonical set. Maps to 'active' since named-future docs ARE actively maintained design artifacts for the future product — not draft (designed) or superseded (replaced). They describe what the named-future product WILL be. Resolves 8 hard-fail check-doc-frontmatter errors blocking push. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(schema): named-future earns its own STATUS value (5 canonical, not 4) User feedback: aliasing 'named-future' to 'active' (commit 3a6928b) overstated the commitment level. VariScout Process docs at docs/01-vision/variscout-process/ are aspirational — contingent on V1 reaching 500+ customers. They're not in active design; they describe what's COMMITTED for a future product line. The 4-value collapse (draft/active/superseded/archived) was overzealous. The 22→4 reduction missed a meaningful distinct lifecycle state. Promoting 'named-future' to a canonical 5th status preserves the semantic intent: - draft: designing; not yet building - active: designed; build underway - **named-future: aspirational/conditional commitment** (not in active design) - superseded: replaced by another spec - archived: historical reference only Changes: - scripts/docs-frontmatter-schema.mjs: add 'named-future' to STATUS enum; remove from STATUS_ALIAS_MAP (no longer aliased) - docs/agent-context/doc-discipline.md: spec-lifecycle table extended; example cites VariScout Process docs; added note on 'delivered' being a soft state signalled by `delivered-by:` frontmatter (not a status: enum value) - docs/superpowers/specs/2026-05-16-docs-strategy-design.md: schema section + collapse summary + migration sequence updated (22→5 not 22→4) - docs/superpowers/specs/2026-05-16-docs-strategy-memo.md: same Resolves 8 hard-fail check-doc-frontmatter errors for variscout-process/ docs WITHOUT semantically mis-labeling them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: regenerate arch doc --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Safe-parallel subset of the docs-strategy-2026 plan (
~/.claude/plans/i-was-wondering-that-effervescent-boole.md). Lands all work that has zero conflict risk with active wedge V1 engineering (PR-WV1-1+ shipping tomainin parallel).Phase A + Plays 1a + 3a + 6 + 7 + 8 delivered. Plays 1b (folder restructure), 2 (Cards & Threads), 4 (consolidation) deferred to a post-wedge-V1 quiet window per the wedge-parallel-conflict analysis in plan §7.3.
What shipped (13 commits, all on this branch)
c0d431e8c8c8b997,2dbb6a1fagent-context-quickstart,package-router,store-state-glossary+ 3 supporting docs atdocs/agent-context/92c96564,3c579ff2.claude/rules/→.claude/invariants/rename +.claude/INVARIANTS.mdsynthesis (15 hard + 10 soft + 6 topic-scoped) + prose-duplication consolidationdb4f6dd7,f8a60ae0,385acc71pnpm docs:gen-archscript (dep graph + sub-path export map + Tailwind @source coverage) + initial generated arch doc + pre-push staleness check272b446c,1376ded2,6e776d9dcoscout-ax-design.mdconsolidating ADR-060/068/069 + coscout-prompts invariant; cross-links from constituentsff0a369d,a7f3b80dWhat's deferred (next session, post-wedge-V1)
git mvtodocs/stable/,docs/living/<purpose>/, etc.) — HIGH merge-conflict risk with active wedge PRs amendingdecision-log.md,investigations.md, ADRs. Wait for wedge V1 to finish shipping, then one focused burst.pnpm docs:*toolbox; ship/docs-stewardloop). Blocked on Play 1b substrate.Foundational artifacts
docs/superpowers/specs/2026-05-16-docs-strategy-memo.md(84 lines) — 1-page CTO memodocs/superpowers/specs/2026-05-16-docs-strategy-design.md(351 lines) — full strategy specdocs/07-decisions/adr-083-eight-purpose-doc-taxonomy.md— ADR for the schema changeMethodology
writing-plansoutput captured in plan file (§§2–10, audit findings in §7).subagent-driven-developmentvia 5 sequential Sonnet implementer dispatches (one per play class), each followed bypnpm docs:check(~3min) verification.2dbb6a1f; split Play 1 into 1a (safe) + 1b (deferred).Verification
pnpm docs:check— 529 docs validated, 0 issues (alias maps handle old STATUS/CATEGORY/AUDIENCE values; warns but doesn't fail)bash scripts/pr-ready-check.sh— green per-commitbash scripts/check-claude-md-size.sh— 7 pre-existing 80%-budget warns, no new file contributespnpm docs:gen-arch— idempotent (script output stable; staleness check in pre-push hook works)--no-verifyDiff stats
546 files changed, +4358 / −972 — bulk is frontmatter backfill (
purpose/tieradded across the corpus) + foundation artifacts (memo + spec + ADR-083) + 3 Tier 1 supporting docs + 3 skills + 6 renamed invariants + INVARIANTS.md + gen-arch script + initial generated arch doc + CoScout AX-design doc.Test plan
scripts/docs-frontmatter-schema.mjs,.claude/INVARIANTS.md,docs/01-vision/coscout-ax-design.md,docs/superpowers/specs/2026-05-16-docs-strategy-{memo,design}.md,scripts/docs/gen-arch.mjspnpm docs:checkpasses locallypnpm docs:gen-archproduces no diff (idempotent).claude/invariants/directory accessible;.claude/INVARIANTS.mdloaded byagent-context-quickstartskillRelated artifacts
~/.claude/plans/i-was-wondering-that-effervescent-boole.md🤖 Generated with Claude Code