diff --git a/docs/backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md b/docs/backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md index 20d131bf4e..c39761b98d 100644 --- a/docs/backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md +++ b/docs/backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md @@ -10,7 +10,16 @@ created: 2026-05-03 last_updated: 2026-05-31 depends_on: [] composes_with: [B-0058, B-0169, B-0170, B-0172, B-0173, B-0190] -tags: [openspec, source-of-truth, foundation, architectural-debt, contract-based-development, spec-based-development, p1-foundation] +tags: + [ + openspec, + source-of-truth, + foundation, + architectural-debt, + contract-based-development, + spec-based-development, + p1-foundation, + ] type: friction-reducer --- @@ -18,11 +27,11 @@ type: friction-reducer Aaron 2026-05-03, in the autonomous-loop maintainer channel via the skill-design memo (`feedback_skills_as_carved_sentences_knowledge_in_docs_datavault_2_0_pattern_aaron_2026_05_03.md`), named OpenSpec catch-up as load-bearing architectural debt: -> *"openspec which we are way behind on, that's suppsed to be our source of truth lol, if we were to delete everyting other than it"* +> _"openspec which we are way behind on, that's suppsed to be our source of truth lol, if we were to delete everyting other than it"_ The intended state per `openspec/README.md`: capabilities under `openspec/specs/**` carry behavioral specs that the code is supposed to satisfy. Specs are canonical; code + skills + memos + docs all derive from / serve / reference the specs. -**Current state (2026-05-03):** specs are sparse; most discipline lives outside specs (memos, CLAUDE.md, GOVERNANCE.md). The *"if we deleted everything but OpenSpec, the project would be lost"* test FAILS today. +**Current state (2026-05-03):** specs are sparse; most discipline lives outside specs (memos, CLAUDE.md, GOVERNANCE.md). The _"if we deleted everything but OpenSpec, the project would be lost"_ test FAILS today. This row tracks the catch-up work needed to restore OpenSpec as actual source-of-truth. @@ -31,19 +40,20 @@ This row tracks the catch-up work needed to restore OpenSpec as actual source-of The row's 2026-05-03 baseline is stale. The current mechanized inventory surface is `tools/openspec/inventory.ts`, and the latest focused run reports: -- `openspec/specs/**`: 9 capability specs. +- `openspec/specs/**`: 9 capability specs with `spec.md` files. The + README-only `openspec/specs/retraction-native/` directory remains background + material, not an input to the strict unmapped-spec gate. - `src/Core/*.fs`: 84 scanned modules, 18 covered modules, 64 uncovered modules after exclusions. -- Artifact coverage: 10 mapped Z-set algebra and tick-history artifacts and 0 - missing mapped artifacts. +- Artifact coverage: 22 mapped artifacts across agentic-organization, + Z-set algebra, and tick-history; 0 missing mapped artifacts. - Inventory gate: PASS under the current default gate. -- Remaining inventory flag: `agentic-organization` has a spec but no module or - artifact mapping yet. +- Strict unmapped-spec gate: PASS with `--fail-on-unmapped-specs`. This means the next B-0171 slice is no longer "prove OpenSpec is empty." The -work is now reconciliation: map artifact-backed capabilities, decide which -open child rows are already satisfied by existing specs, and add one bounded -capability mapping or child-row correction per PR. Avoid touching +work is now reconciliation: continue mapping artifact-backed capabilities, +decide which open child rows are already satisfied by existing specs, and add +one bounded capability mapping or child-row correction per PR. Avoid touching `docs/BACKLOG.md` while active backlog-index claims own it. ## Why P1 (foundation) @@ -54,7 +64,7 @@ capability mapping or child-row correction per PR. Avoid touching ## Scope (incremental, not big-bang) -The catch-up is **NOT** a single big-bang spec authoring pass. It's incremental backfilling of the most load-bearing capability surfaces FIRST, then extending coverage. Per Aaron's *"foundation right and deliberate"* guidance, quality > coverage. +The catch-up is **NOT** a single big-bang spec authoring pass. It's incremental backfilling of the most load-bearing capability surfaces FIRST, then extending coverage. Per Aaron's _"foundation right and deliberate"_ guidance, quality > coverage. ### Phase 1 — Inventory + sequencing @@ -75,7 +85,7 @@ Per `openspec/README.md` modified-fork conventions (no archive, no change-histor ### Phase 4 — Validation -The *"if we deleted everything but OpenSpec, the project would be lost"* test is the acceptance criterion. When all 4 phases complete, that test should NOT fail. +The _"if we deleted everything but OpenSpec, the project would be lost"_ test is the acceptance criterion. When all 4 phases complete, that test should NOT fail. ## Why this matters now @@ -87,7 +97,7 @@ The *"if we deleted everything but OpenSpec, the project would be lost"* test is - Adopting upstream OpenSpec workflow as-is (the project uses a modified fork; modifications stay) - Single big-bang spec authoring (incremental per Phase 1-4 above) -- Replacing CLAUDE.md / AGENTS.md / GOVERNANCE.md (OpenSpec is the *contract* layer; those remain the *behavioral guidance* + *governance* layers — they reference the contracts) +- Replacing CLAUDE.md / AGENTS.md / GOVERNANCE.md (OpenSpec is the _contract_ layer; those remain the _behavioral guidance_ + _governance_ layers — they reference the contracts) ## Composes with @@ -108,6 +118,6 @@ This row closes when: 1. The top-10 load-bearing capability surfaces have current OpenSpec specs (Phase 2 complete) 2. CI gate enforces "every load-bearing change references a spec" (Phase 3 complete) 3. CLAUDE.md + AGENTS.md updated to make OpenSpec FIRST-READ (Phase 3 complete) -4. The *"delete everything but OpenSpec"* test passes (Phase 4 complete) +4. The _"delete everything but OpenSpec"_ test passes (Phase 4 complete) -Until done, this row stays open. Per Aaron's *"WONT-DO is 99% deferral, not forever — we will likely do everything eventually"*, the catch-up is on the long arc. +Until done, this row stays open. Per Aaron's _"WONT-DO is 99% deferral, not forever — we will likely do everything eventually"_, the catch-up is on the long arc. diff --git a/tools/openspec/inventory.test.ts b/tools/openspec/inventory.test.ts index 341e25e634..64009c0f47 100644 --- a/tools/openspec/inventory.test.ts +++ b/tools/openspec/inventory.test.ts @@ -398,6 +398,23 @@ describe("mapping table integrity", () => { ]); }); + test("agentic-organization has source, test, and documentation artifact coverage", () => { + expect(CAPABILITY_ARTIFACT_MAP["agentic-organization"]).toEqual([ + "agentic-organization/package.json", + "agentic-organization/packages/domain/src/org-event.ts", + "agentic-organization/packages/domain/src/hat-binding.ts", + "agentic-organization/packages/domain/src/supervisor-communication.ts", + "agentic-organization/packages/application/src/command-contract.ts", + "agentic-organization/packages/application/src/command-handler-registry.ts", + "agentic-organization/packages/application/src/command-pipeline.ts", + "agentic-organization/packages/application/src/ports.ts", + "agentic-organization/packages/application/test/command-pipeline.test.ts", + "agentic-organization/docs/NORTH_STAR_ALIGNMENT_CHECKPOINT.md", + "agentic-organization/docs/ORGANIZATION_RUNTIME_ARCHITECTURE.md", + "agentic-organization/docs/V0_POLICY_AND_RUNTIME_BOUNDARIES.md", + ]); + }); + test("EXCLUDED_MODULES is a Set of strings", () => { expect(EXCLUDED_MODULES).toBeInstanceOf(Set); for (const m of EXCLUDED_MODULES) { @@ -453,4 +470,27 @@ describe("integration: real repo scan", () => { expect(tickHistoryMapping!.missingArtifacts).toEqual([]); expect(report.unmappedSpecs).not.toContain("tick-history"); }); + + test("real agentic-organization spec is artifact-mapped", () => { + const repoRoot = join(import.meta.dir, "..", ".."); + const specs = scanSpecs(join(repoRoot, "openspec", "specs")); + const modules = scanModules(join(repoRoot, "src", "Core")); + const report = buildGapReport(specs, modules, { artifactRoot: repoRoot }); + + const agenticOrgMapping = report.artifactMappings.find((m) => m.capability === "agentic-organization"); + expect(agenticOrgMapping).toBeDefined(); + expect(agenticOrgMapping!.artifacts).toContain("agentic-organization/packages/application/src/command-pipeline.ts"); + expect(agenticOrgMapping!.artifacts).toContain("agentic-organization/docs/ORGANIZATION_RUNTIME_ARCHITECTURE.md"); + expect(agenticOrgMapping!.missingArtifacts).toEqual([]); + expect(report.unmappedSpecs).not.toContain("agentic-organization"); + }); + + test("real README-only capability directories are not strict spec inputs", () => { + const repoRoot = join(import.meta.dir, "..", ".."); + const specs = scanSpecs(join(repoRoot, "openspec", "specs")); + const report = buildGapReport(specs, [], { artifactRoot: repoRoot }); + + expect(specs.map((s) => s.capability)).not.toContain("retraction-native"); + expect(report.unmappedSpecs).not.toContain("retraction-native"); + }); }); diff --git a/tools/openspec/inventory.ts b/tools/openspec/inventory.ts index 14d1eeb913..18678fcd91 100644 --- a/tools/openspec/inventory.ts +++ b/tools/openspec/inventory.ts @@ -96,6 +96,20 @@ const CAPABILITY_MODULE_MAP: Record = { // Keeping this separate prevents tests, proofs, and profile-only evidence from // inflating source-module coverage while still making the mapping explicit. const CAPABILITY_ARTIFACT_MAP: Record = { + "agentic-organization": [ + "agentic-organization/package.json", + "agentic-organization/packages/domain/src/org-event.ts", + "agentic-organization/packages/domain/src/hat-binding.ts", + "agentic-organization/packages/domain/src/supervisor-communication.ts", + "agentic-organization/packages/application/src/command-contract.ts", + "agentic-organization/packages/application/src/command-handler-registry.ts", + "agentic-organization/packages/application/src/command-pipeline.ts", + "agentic-organization/packages/application/src/ports.ts", + "agentic-organization/packages/application/test/command-pipeline.test.ts", + "agentic-organization/docs/NORTH_STAR_ALIGNMENT_CHECKPOINT.md", + "agentic-organization/docs/ORGANIZATION_RUNTIME_ARCHITECTURE.md", + "agentic-organization/docs/V0_POLICY_AND_RUNTIME_BOUNDARIES.md", + ], "z-set-algebra": [ "tests/Tests.FSharp/Algebra/ZSet.Tests.fs", "tests/Tests.FSharp/Algebra/ZSet.Overflow.Tests.fs",