tool(B-0171): map agentic-organization OpenSpec artifacts

docs/backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md

@@ -10,19 +10,28 @@ 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
 ---
 
 # OpenSpec catch-up — restore OpenSpec as canonical source-of-truth
 
 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.

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");
+  });
 });

tools/openspec/inventory.ts

@@ -96,6 +96,20 @@ const CAPABILITY_MODULE_MAP: Record<string, string[]> = {
 // 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<string, string[]> = {
+  "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",