@ecoma-io/archkeep 0.13.0

package/src/intent/intent-manifest.json

@@ -0,0 +1,347 @@
+{
+  "version": 2,
+  "generatedAt": "v1.0.0-hardening",
+  "description": "Machine-readable manifest declaring every v1.0 intent and the evidence that supports it. A contract is 'proven' only when at least one evidence entry is an executable proof (behavioral-test, e2e-test, or architecture-test). Source-evidence and documentation support the claim but cannot prove it alone.",
+  "evidenceTaxonomy": {
+    "behavioral-test": "A unit or integration test that imports and calls the code, asserting on runtime behavior (not source text). Proves the intent is regression-protected.",
+    "e2e-test": "A CLI subprocess test that exercises the real binary against a consumer workspace. Proves the intent holds end-to-end.",
+    "architecture-test": "A test that walks the codebase structure (imports, specifiers, declarations) to verify an architectural constraint. Proves the intent is mechanically enforced.",
+    "static-analysis": "An automated static analysis tool (ESLint, Semgrep, etc.) enforces the property. Proves the intent is mechanically checked, but the check scope is limited to what the tool's rules cover.",
+    "source-evidence": "The implementation source contains the property the intent declares. Supports the claim but does not prove it is regression-protected — the property could disappear in a refactor.",
+    "documentation": "A document describes the property the intent declares. Supports understanding but proves neither implementation nor protection."
+  },
+  "contracts": [
+    {
+      "id": "A",
+      "name": "Provider independence",
+      "intent": "Core (rules, analysis, report) must not import provider-specific code (nx, moon, native).",
+      "evidence": [
+        {
+          "type": "architecture-test",
+          "path": "src/conformance/boundary.test.mjs",
+          "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/context.mjs",
+          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "B",
+      "name": "Empty result is never silently successful",
+      "intent": "An empty diagnostic list must mean 'no violation', and nothing else. Every path that cannot reach a verdict must say so.",
+      "evidence": [
+        {
+          "type": "behavioral-test",
+          "path": "src/report/json.test.mjs",
+          "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/lsp/diagnose.mjs",
+          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places"
+        },
+        {
+          "type": "source-evidence",
+          "path": "cli.mjs",
+          "assertion": "Exit codes 0/1/3 distinguish clean/findings/cannot-look"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "C",
+      "name": "Workspace resolution ≠ source analysis",
+      "intent": "Graph edges (from provider) and source analysis (from analyzers) answer different questions. Neither replaces the other. The analysis layer never judges, filters, or omits imports based on policy.",
+      "evidence": [
+        {
+          "type": "behavioral-test",
+          "path": "src/intent/intent.test.mjs",
+          "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes; analysis source contains no judging vocabulary"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/analysis/contract.md",
+          "assertion": "Analysis record is a superset of a graph edge — 5 of 15 violations decided on raw specifier"
+        },
+        {
+          "type": "source-evidence",
+          "path": "AGENTS.md",
+          "assertion": "src/graph/ is a lossy view of analysis, on purpose; src/analysis/ never judges"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "D",
+      "name": "Architecture snapshot identity",
+      "intent": "Two runs over an unchanged tree (and unchanged archkeep version) produce byte-identical JSON. Internal fields are stripped. Schema is versioned.",
+      "evidence": [
+        {
+          "type": "e2e-test",
+          "path": "e2e/determinism.e2e.mjs",
+          "assertion": "Graph, check, impact run twice — byte-identical JSON output"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/graph.mjs",
+          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/graph.mjs",
+          "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "E",
+      "name": "Snapshot compatibility",
+      "intent": "diff refuses a baseline with unknown schemaVersion. A consumer that reads a schemaVersion it does not recognise should refuse to parse.",
+      "evidence": [
+        {
+          "type": "e2e-test",
+          "path": "e2e/diff.e2e.mjs",
+          "assertion": "Invalid baseline schemaVersion exits 3; incompatible version exits 3"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/diff.mjs",
+          "assertion": "parseBaseline validates schemaVersion; refuses unknown versions"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "F",
+      "name": "Diff semantics — structural ≠ policy-mismatch ≠ rule-impact",
+      "intent": "Graph change ≠ policy mismatch ≠ rule impact. Diff separates structural changes, policy-mismatch warnings, and rule-impact analysis (depConstraints only). Refuses incomplete baseline/head.",
+      "evidence": [
+        {
+          "type": "e2e-test",
+          "path": "e2e/diff.e2e.mjs",
+          "assertion": "Self-baseline exits 0; added/removed edges reported; policy mismatch warned; rule-impact with config"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/diff.mjs",
+          "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "G",
+      "name": "Impact determinism",
+      "intent": "Given the same graph and project name, impact always returns the same set. BFS, sorted, no localeCompare.",
+      "evidence": [
+        {
+          "type": "e2e-test",
+          "path": "e2e/determinism.e2e.mjs",
+          "assertion": "Impact --format json produces identical output on two runs"
+        },
+        {
+          "type": "behavioral-test",
+          "path": "src/commands/impact.test.mjs",
+          "assertion": "Sorts results using plain string comparison (never localeCompare)"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "H",
+      "name": "Context — effective architecture contract",
+      "intent": "context shows the constraint table as it applies to a project's tags, not raw metadata. Per-edge verdicts cover depConstraints only (3 of 15 violation types) — this narrowing is disclosed.",
+      "evidence": [
+        {
+          "type": "behavioral-test",
+          "path": "src/commands/context-command.test.mjs",
+          "assertion": "Returns tags, matched constraints, per-edge violations; coverage.notes warns about depConstraints-only scope"
+        },
+        {
+          "type": "e2e-test",
+          "path": "e2e/context.e2e.mjs",
+          "assertion": "Native consumer: tags, constraints, coverage.notes verified; Moon consumer: context E2E"
+        },
+        {
+          "type": "documentation",
+          "path": "../../docs/concepts/agentic-development.md",
+          "assertion": "Section 'What context and impact do not check' warns agents about the semantic gap"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "I",
+      "name": "Explain — rule, reason, evidence",
+      "intent": "explain runs full evaluate() and returns ALL violations at the site (not just first). Unresolvable sites are explicit, not silent drops.",
+      "evidence": [
+        {
+          "type": "behavioral-test",
+          "path": "src/commands/explain.test.mjs",
+          "assertion": "Returns all violations at a site; unresolvable site returns unresolvable:true with reason"
+        },
+        {
+          "type": "e2e-test",
+          "path": "e2e/explain.e2e.mjs",
+          "assertion": "Native and Moon consumers: specifier, sourceProject, targetProject, violations verified"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "J",
+      "name": "Check is enforcement authority",
+      "intent": "context/impact/diff/explain must not create different verdicts than check would. The depConstraints-only narrowing in context/impact/diff is disclosed. Where these commands evaluate, their verdicts must agree with check.",
+      "evidence": [
+        {
+          "type": "behavioral-test",
+          "path": "src/intent/intent.test.mjs",
+          "assertion": "depConstraints verdicts from judgeEdge agree with evaluate; explain includes the same violations as evaluate at a given site; diff warns in coverage.notes when ruleImpact is computed"
+        },
+        {
+          "type": "behavioral-test",
+          "path": "src/commands/context-command.test.mjs",
+          "assertion": "Test verifies coverage.notes contains depConstraints warning"
+        },
+        {
+          "type": "e2e-test",
+          "path": "e2e/context.e2e.mjs",
+          "assertion": "E2E verifies coverage.notes in JSON envelope"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/context-command.mjs",
+          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/impact.mjs",
+          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/diff.mjs",
+          "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)"
+        },
+        {
+          "type": "documentation",
+          "path": "../../docs/concepts/agentic-development.md",
+          "assertion": "Section warns agents: violations:[] means allowed by constraint table, not free of all boundary violations"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "K",
+      "name": "Determinism",
+      "intent": "No localeCompare, Date.now, Math.random in production code. Sorts use plain string comparison. Two runs over same tree (and same archkeep version) produce identical output.",
+      "evidence": [
+        {
+          "type": "e2e-test",
+          "path": "e2e/determinism.e2e.mjs",
+          "assertion": "Graph, check, impact: two runs produce byte-identical JSON"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/commands/graph.mjs",
+          "assertion": "Plain string comparison throughout; never localeCompare"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "L",
+      "name": "Provider parity",
+      "intent": "Same semantics on Nx/Moon/Native: same violation types, same options, same constraint table, same message ids. Partial workspaceLayout rejected.",
+      "evidence": [
+        {
+          "type": "e2e-test",
+          "path": "e2e/parity.e2e.mjs",
+          "assertion": "Nx vs Native: project names, edge source/target/type, violation rule IDs, envelope structure"
+        },
+        {
+          "type": "e2e-test",
+          "path": "e2e/moon.e2e.mjs",
+          "assertion": "Moon: check, graph, diff, impact, explain, context verified against Moon provider (conditional on moon CLI availability)"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/providers/moon.mjs",
+          "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native"
+        },
+        {
+          "type": "behavioral-test",
+          "path": "src/providers/moon.test.mjs",
+          "assertion": "Partial layout (apps-only, libs-only) returns undefined workspaceLayout"
+        }
+      ],
+      "status": "proven"
+    },
+    {
+      "id": "M",
+      "name": "Drift — observed vs declared intent",
+      "intent": "drift compares the observed project graph against the canonical architecture-intent.json through the single judgeIntent. It is descriptive (never exits 1); check folds it in by presence and exits 1 on drift findings. Every path that cannot reach a drift verdict (malformed/absent intent, incomplete coverage, incomplete graph) says so loudly instead of returning empty.",
+      "evidence": [
+        {
+          "type": "behavioral-test",
+          "path": "src/commands/drift.test.mjs",
+          "assertion": "driftCommand returns status ok with observed facts and findings; refuses incomplete coverage, absent intent, and unregistered-plugin incomplete graph; buildObserved counts implicit edges separately"
+        },
+        {
+          "type": "behavioral-test",
+          "path": "src/report/drift-text.test.mjs",
+          "assertion": "formatDriftReport states comparison facts even when clean (no-drift is a claim about coverage); groups findings by rule in taxonomy order; byte-identical determinism"
+        },
+        {
+          "type": "e2e-test",
+          "path": "e2e/drift.e2e.mjs",
+          "assertion": "Through the installed CLI: drift exits 0 on a matching tree and names fingerprint/rows; reports dependencyForbidden and projectMissing; JSON envelope carries findings; malformed intent exits 3 for both drift and check"
+        }
+      ],
+      "status": "proven"
+    }
+  ],
+  "bugsFixed": [
+    {
+      "id": "moon-partial-workspace-layout",
+      "description": "Moon provider returned partial workspaceLayout (e.g., {appsDir:'apps'} with no libsDir), which silently disabled isAbsoluteImportIntoAnotherProject for the missing axis via 'undefined/' string comparison. Fixed: inferWorkspaceLayout returns null for partial layouts, forcing the DEFAULT_WORKSPACE_LAYOUT fallback.",
+      "evidence": {
+        "source": "src/providers/moon.mjs",
+        "test": "src/providers/moon.test.mjs",
+        "contract": "L"
+      }
+    },
+    {
+      "id": "context-impact-semantic-gap-undisclosed",
+      "description": "context and impact commands used judgeEdge (depConstraints-only) without disclosing to agents that 11 of 15 violation types were not checked. An agent seeing violations:[] could believe an edge was clean when check would still flag it. Fixed: coverage.notes warns about the narrowing; agentic-development.md documents the gap.",
+      "evidence": {
+        "source": ["src/commands/context-command.mjs", "src/commands/impact.mjs"],
+        "docs": "../../docs/concepts/agentic-development.md",
+        "test": [
+          "src/commands/context-command.test.mjs",
+          "src/commands/impact.test.mjs",
+          "e2e/context.e2e.mjs",
+          "e2e/impact.e2e.mjs"
+        ],
+        "contract": "J"
+      }
+    },
+    {
+      "id": "policy-fingerprint-non-canonical",
+      "description": "computePolicyFingerprint used raw JSON.stringify without sorting object keys, so two semantically identical policy objects constructed in different key order could produce different fingerprints. diff would then report a spurious policy change. Fixed: canonicalize JSON by sorting keys at every depth before hashing.",
+      "evidence": {
+        "source": "src/commands/graph.mjs",
+        "test": "src/commands/graph.test.mjs",
+        "intentTest": "src/intent/intent.test.mjs",
+        "contract": "D"
+      }
+    }
+  ],
+  "todoAffectingV1": 0,
+  "unprovenIntents": 0
+}