@davesheffer/hunch 1.7.0 → 1.7.1

package/README.md

@@ -99,6 +99,205 @@ hunch check --staged --strict
 hunch conform --strict
 ```
 
+### Hunch Constitution — experimental Gate G1 + evidence bootstrap
+
+Hunch can now lift one structured architectural decision into versioned Policy IR, prove its
+deterministic behavior with a clean baseline plus a mutation, and require an explicit human event
+before it becomes enforceable:
+
+```bash
+hunch constitution bootstrap --public-only --since 90d --max-candidates 3
+hunch constitution ingest --public-only --since 90d
+hunch constitution ingest --public-only --instructions --from pr-export.json
+hunch constitution delta dec_fix_or_revert --public-only
+hunch constitution bootstrap --history --public-only --since 90d --max-candidates 3
+hunch policy compile dec_service_boundary --through OrderService
+hunch policy corpus pol_… --import corpus.json
+hunch policy plan pol_… --history 20 --mutations 3
+hunch policy prove pol_…
+hunch policy history pol_…
+hunch policy history pol_… --commit <full-sha> --classify true_positive_actionable --actor github:your-name --reason "Confirmed historical violation"
+hunch policy shadow pol_… --record
+hunch policy shadow pol_…
+hunch policy card pol_…
+hunch policy relations pol_…
+hunch policy accept pol_… --blocking --actor github:your-name
+hunch policy evaluate pol_… --json
+hunch policy evaluate pol_… --working --json
+hunch policy evaluate pol_… --staged --json
+```
+
+Private G2 dogfood stays evidence-only until a separate human signoff. An exact private plan selects
+at least ten P3+ policies and seven category-specific runbooks; drills write no evidence by
+themselves, rehearsals bind the resulting hashes, and historical shadow backfill commits only after
+the complete policy/commit matrix has produced no unknown or error result:
+
+```bash
+hunch constitution g2 --plan private-g2-plan.json
+hunch constitution g2 --drill all
+hunch constitution g2 --rehearse rb_g2_evaluator_error_01 --result passed \
+  --actor human:owner --evidence sha1:… --notes "Exact recovery drill passed."
+hunch constitution g2 --backfill 20
+hunch constitution g2 --queue 20
+hunch constitution g2 --strict
+```
+
+Backfill uses distinct real first-parent commits, excludes commits predating an executable policy's
+fixing commit, and deduplicates by exact policy/proof/repository/graph identity. A failed preflight
+writes nothing. Neither a ready packet nor a passed drill activates, warns, blocks, or claims G2;
+the strongest machine result is `eligible_for_human_g2_signoff`.
+
+The model-free bootstrap considers only current, accepted, human-confirmed decisions carrying
+exactly one structured `conformance` predicate. It normalizes auditable evidence and keeps a bounded
+queue of at most three unreviewed candidates. Re-running is idempotent, private evidence inherits
+private storage, and every candidate starts with `authority: null`—bootstrap can never activate or
+block on its own.
+
+The opt-in history path reads the exact blobs for a human-confirmed fix/revert commit and its first
+parent—without checking out code or running hooks. It also admits an architectural replacement
+when a human-confirmed decision carries an explicit `retired.deps` entry that exactly matches a
+removed external package. It enumerates only assertions the current graph can bind exactly and
+whose symbol/call/package identifiers the human judgment explicitly names. One
+supported meaning may become a compiled candidate; zero, multiple, missing,
+or ambiguous meanings are stored as `uncompilable`, never silently approximated. `constitution
+delta` previews that evidence and candidate set without writing policy state.
+
+The external-import slice is deliberately narrow: removing a human-named static ESM package
+specifier can compile into a file-scoped `not-reaches(..., external:<package>)` boundary. Package
+subpaths canonicalize to their package root, the anchor must exist before and after the change, and
+an explicitly retired dependency filters unrelated call/symbol facts from the same replacement
+commit. Exact relative JS/TS imports across two derived components can also compile to direct
+`reaches`/`not-reaches` policies over `depends_on` edges when both component meanings are explicitly
+human-grounded. Same-component imports, ambiguous/missing targets, import-map aliases, `require()`,
+dynamic `import()`, runtime loading, and positive external-package requirements remain visibly
+unsupported.
+
+Local correction, incident, and test-failure records can be normalized with `constitution ingest`.
+The adapter stores references and hashes, inherits private storage, and creates no policy authority.
+Add `--instructions` to hash committed AGENTS/CLAUDE/Copilot/Cursor/Windsurf instructions and ADRs
+from immutable Git blobs. Add `--from` for one or more strict local review, conversation, or PR
+export JSON files. Raw prose is never copied into EvidenceEvents; only bounded metadata, references,
+and content hashes persist. Mixed batches validate before the first write, public-only mode refuses
+private/secret items, and unsupported meaning stays explicitly `uncompilable` instead of being
+approximated into a policy.
+
+```json
+{
+  "version": 1,
+  "source": "pr_export",
+  "items": [{
+    "id": "pr-431-review-7",
+    "kind": "review",
+    "occurred_at": "2026-07-10T10:10:00Z",
+    "actor": "maintainer:alice",
+    "commit": "abc1234",
+    "files": ["src/orders.ts"],
+    "text": "Use OrderService; do not call persistence here.",
+    "data_class": "private",
+    "maintainer_confirmed": true
+  }]
+}
+```
+
+`policy plan` then writes a content-addressed ProofPlan before execution: exact source/current commits,
+known-good/known-bad corpus, deterministic mutation operators, expectations, and resource budgets.
+`policy corpus --import` accepts bounded labeled `known_bad`/`known_good` Git refs, resolves them
+once to full immutable commit SHAs, stores the manifest in the policy's public/private home, and
+hash-binds it into every resulting plan. A commit cannot be labeled both good and bad, and stale
+policy-bound corpora must be re-imported after semantic policy changes. A `known_good` fixture may
+also carry an explicit human attestation—`{ "actor": "github:your-name", "reason": "…" }`—to
+document why that accepted variant belongs in the corpus. Attested fixtures are replayed once as
+named corpus evidence and excluded from accepted-history sampling; the attestation cannot waive a
+policy result or create authority.
+`policy relations` is a read-only view of those explicit exception-parent links. It shows the
+selected policy, its parent if any, linked narrower exceptions, and a visible missing-parent marker
+for a manually damaged record. When the broad parent is planned, proved, or evaluated, every linked
+exception descendant is instead hash-bound into one canonical composition. The deepest applicable
+explicit scope selects the result; equal-scope ambiguity, missing bindings, or unsupported component
+path precision stays unknown/error rather than falling through to the broad rule.
+`policy consolidation` is also read-only. When a compiler-produced advisory scope suggestion exists,
+it groups only matching narrow policies with the same assertion/data class and syntactically contained
+scopes, then requires three independent decision references with no exception, active-policy,
+conflict, or counterexample signal before marking the packet reviewable. It never merges or widens a
+policy.
+`policy history` inspects every violated accepted-history receipt and its current human disposition.
+Disposition records are strict, content-addressed, stored in the policy's public/private home, and
+bound to the exact policy hash, proof, plan, commit, and replay receipt. Corrections append a new
+record with `--supersedes`; prior judgments remain auditable. Only `true_positive_actionable` clears
+the history-evidence gate. False positives, insufficient-parser unknowns, and accepted exceptions
+remain blockers until the policy/evaluator or combined exception semantics are repaired and
+re-proved. A disposition never activates policy: blocking still requires a separate explicit human
+`policy accept`, and a later corrected disposition is rechecked on every gate evaluation.
+`policy shadow --record` appends one content-addressed evaluation for the exact current graph and
+deduplicates retries of the same receipt. Violations use a separate append-only human disposition
+chain, while `policy shadow` reports raw recent-window counts, confirmed and lower-bound precision,
+unknown/error rate, mutation sensitivity, thresholds, and P4-review eligibility. Shadow records
+never warn, block, change proof class, or activate policy; the MCP shadow tool is read-only.
+Planning runs no replay, test, model, or activation; `policy prove` binds its receipt to that plan.
+Proof execution checks out each unique immutable commit into a disposable worktree with hooks,
+user-global Git configuration, private-overlay discovery, and provider selection disabled. It
+indexes cold snapshots through a bounded four-worker pool (hard maximum eight), reuses
+content-validated data-class-separated graph caches, records canonical current/known-good/
+known-bad/accepted-history receipts, then removes every checkout and transient graph. Scheduling
+and cache statistics never enter proof hashes. Project code, builds, and tests are never executed.
+Timeouts, worker failures, unresolved refs, unknowns, and errors remain explicit.
+
+Level-1 evaluators include `must-pass-through` (every statically discovered path from A to C must
+contain B), exact external-package boundaries, and component/component-id selectors over static
+`depends_on` edges. CLI, MCP (`hunch_policy_evaluate`), and strict CI share the exact canonical
+receipt. Direct `reaches`/`not-reaches` contradictions are stored as conflict evidence without
+minting a second policy or changing authority. Candidate records retain the exact alternatives,
+unsupported facts, incumbent, and conflict IDs for proof-card review. Equivalent evidence enriches
+the incumbent idempotently without changing its assertion, scope, proof, lifecycle, or authority.
+Three independently grounded component-policy sources may add an advisory common-path scope
+suggestion, while same-named behavior outside a narrow symbol scope is surfaced as a counterexample.
+Suggestions and counterexamples are review evidence only: the compiled scope is never widened
+automatically.
+
+Executable-behavior policies keep their proof and history replay bound to immutable commits and
+exact dependency snapshots. For advisory delivery, `policy evaluate --staged`, `--working`, the MCP
+workspace option, and the pre-commit `check` path materialize the selected pending snapshot in a
+disposable checkout before running the same hash-pinned test. The receipt binds the base commit,
+snapshot hash, and changed paths; untracked regular files are included, repository hooks and global
+Git configuration remain disabled, and dependency-manifest changes return an explicit error rather
+than using stale dependencies. Advisory violations warn but never block, and `--public-only` never
+loads private policies.
+An intentional narrow opposite can be linked explicitly with `hunch policy exception <child>
+--parent <parent> --actor human:<identity> --reason "…"`. The relationship requires identical
+bindings/relation, opposite `reaches` semantics, matching data class/home, and a strictly contained
+scope. Linking invalidates the child's prior proof and authority and returns it to non-blocking
+`compiled` state. The broad parent remains the enforcement unit: its plan, proof, replay and mutation
+receipts bind the full exception tree, and any later exception change retracts blocking eligibility
+until a fresh composite proof is generated. Proof never activates the parent; a separate human
+`policy accept` remains mandatory.
+Models do not participate in evaluation or activation. Plan-bound proofs cover the committed current
+baseline, known-good/known-bad fixtures, bounded accepted history, and a canonical mutation
+manifest. The primary mutation is applied to an immutable disposable source checkout, must remain
+parseable, and persists its exact Git diff plus resulting graph diff. Comment/string parser and
+same-name ambiguity controls remain separate; any failed required receipt prevents blocking review.
+Optional project build/test status is reported separately and is never required for evaluator
+sensitivity. Historical hits are
+not called false positives until classified, and unclassified hits or replay errors prevent
+blocking approval. Shadow evidence and broader compiler inference remain follow-on work and are
+reported as limitations in the proof artifact.
+
+`policy card` (also `hunch_policy_card` over MCP) renders the same deterministic review surface for
+every client: exact assertion and scope, raw evidence vector, unclassified hits, unknown/errors,
+blocking readiness, current authority, limitations, and next actions. It never averages evidence
+into a confidence score and never grants authority.
+
+The versioned 20-case EXP-03 compiler bank is recomputed with:
+
+```bash
+hunch constitution scorecard
+```
+
+The scorecard reports the raw numerator/denominator, the absolute difference from the preregistered
+70% threshold, a Wilson 95% interval, per-outcome counts, and silent semantic substitutions. One
+unsupported-to-assertion substitution fails the gate even when the aggregate rate remains above the
+threshold. This curated scorecard measures deterministic compiler classification, not real-user
+authoring speed or acceptance; those human-review arms remain a separate EXP-03 study.
+
 ## Private when the reasoning is sensitive
 
 Open-source the code without open-sourcing the reasoning.
@@ -133,6 +332,21 @@ Hunch can answer with the actual context: this boundary exists because of the N+
 service layer was the chosen repair, and the direct import violates a confirmed constraint. That is
 the missing layer between fast code generation and durable engineering judgment.
 
+## Certify a release candidate
+
+```bash
+npm run gate:release
+```
+
+The same fail-closed runner gates pull requests, main, and npm publication. It binds the package
+version and optional release tag to HEAD; runs typecheck, the full suite, core and VS Code builds,
+a fresh public repository index plus strict architectural conformance, a clean-installed tarball replay/privacy rehearsal, and the
+production dependency audit; then writes a content-addressed receipt under
+`.hunch-cache/release/`. A failed prerequisite stops later commands, a tag/version/commit mismatch
+refuses before execution, and publication remains unreachable unless the exact tagged checkout is
+clean and every gate passes. The receipt includes the prior-version rollback command; it never
+activates, promotes, warns, or blocks a Constitution policy.
+
 ## Learn more
 
 - [Full documentation](https://hunch-pi.vercel.app/docs)

package/bench/constitution-exp03-v1.json

@@ -0,0 +1,70 @@
+{
+  "version": 1,
+  "experiment": "EXP-03",
+  "threshold": 0.7,
+  "preregistered_metric": "intended supported assertion or honest non-minting classification",
+  "cases": [
+    {
+      "id": "exp03_added_call",
+      "family": "direct review correction",
+      "evidence": "Human names charge and verifySession; the fix adds the exact call.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "reaches", "subject": { "selector": "symbol:src/payments/charge.ts:charge" }, "relation": { "edges": ["calls"], "transitive": false, "max_depth": 1 }, "object": { "selector": "symbol:src/auth/session.ts:verifySession" } }, "scope": { "repos": [], "paths": ["src/payments/charge.ts"], "components": ["cmp_payments"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "reaches", "subject": { "selector": "symbol:src/payments/charge.ts:charge" }, "relation": { "edges": ["calls"], "transitive": false, "max_depth": 1 }, "object": { "selector": "symbol:src/auth/session.ts:verifySession" } }, "scope": { "repos": [], "paths": ["src/payments/charge.ts"], "components": ["cmp_payments"] } }
+    },
+    {
+      "id": "exp03_removed_call",
+      "family": "revert",
+      "evidence": "Human names run and dangerous; revert removes the exact call.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "not-reaches", "subject": { "selector": "symbol:src/runtime/worker.ts:run" }, "relation": { "edges": ["calls"], "transitive": false, "max_depth": 1 }, "object": { "selector": "symbol:src/runtime/worker.ts:dangerous" } }, "scope": { "repos": [], "paths": ["src/runtime/worker.ts"], "components": ["cmp_runtime"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "not-reaches", "subject": { "selector": "symbol:src/runtime/worker.ts:run" }, "relation": { "edges": ["calls"], "transitive": false, "max_depth": 1 }, "object": { "selector": "symbol:src/runtime/worker.ts:dangerous" } }, "scope": { "repos": [], "paths": ["src/runtime/worker.ts"], "components": ["cmp_runtime"] } }
+    },
+    {
+      "id": "exp03_added_symbol",
+      "family": "incident fix",
+      "evidence": "Human judgment explicitly names the introduced guard symbol.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "exists", "subject": { "selector": "symbol:src/security/guard.ts:verifyOrigin" } }, "scope": { "repos": [], "paths": ["src/security/guard.ts"], "components": ["cmp_security"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "exists", "subject": { "selector": "symbol:src/security/guard.ts:verifyOrigin" } }, "scope": { "repos": [], "paths": ["src/security/guard.ts"], "components": ["cmp_security"] } }
+    },
+    {
+      "id": "exp03_external_retirement",
+      "family": "architectural dependency retirement",
+      "evidence": "Decision.retired.deps names axios and the stable file anchor remains.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "not-reaches", "subject": { "selector": "symbol:src/services/orders.ts:fetchOrders" }, "relation": { "edges": ["imports"], "transitive": false, "max_depth": 1 }, "object": { "selector": "external:axios" } }, "scope": { "repos": [], "paths": ["src/services/orders.ts"], "components": ["cmp_services"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "not-reaches", "subject": { "selector": "symbol:src/services/orders.ts:fetchOrders" }, "relation": { "edges": ["imports"], "transitive": false, "max_depth": 1 }, "object": { "selector": "external:axios" } }, "scope": { "repos": [], "paths": ["src/services/orders.ts"], "components": ["cmp_services"] } }
+    },
+    {
+      "id": "exp03_removed_relative_component",
+      "family": "component boundary removal",
+      "evidence": "Human names Api and Db; the relative import and component bindings are exact.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "not-reaches", "subject": { "selector": "component-id:cmp_api" }, "relation": { "edges": ["depends_on"], "transitive": false, "max_depth": 1 }, "object": { "selector": "component-id:cmp_db" } }, "scope": { "repos": [], "paths": ["src/api/orders.ts"], "components": ["cmp_api", "cmp_db"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "not-reaches", "subject": { "selector": "component-id:cmp_api" }, "relation": { "edges": ["depends_on"], "transitive": false, "max_depth": 1 }, "object": { "selector": "component-id:cmp_db" } }, "scope": { "repos": [], "paths": ["src/api/orders.ts"], "components": ["cmp_api", "cmp_db"] }, "uncertainty": ["Unrelated call facts were rejected as structural coincidence."] }
+    },
+    {
+      "id": "exp03_added_relative_component",
+      "family": "component dependency restoration",
+      "evidence": "Human names Api and Services; the current depends_on edge is exact.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "reaches", "subject": { "selector": "component-id:cmp_api" }, "relation": { "edges": ["depends_on"], "transitive": false, "max_depth": 1 }, "object": { "selector": "component-id:cmp_services" } }, "scope": { "repos": [], "paths": ["src/api/orders.ts"], "components": ["cmp_api", "cmp_services"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "reaches", "subject": { "selector": "component-id:cmp_api" }, "relation": { "edges": ["depends_on"], "transitive": false, "max_depth": 1 }, "object": { "selector": "component-id:cmp_services" } }, "scope": { "repos": [], "paths": ["src/api/orders.ts"], "components": ["cmp_api", "cmp_services"] } }
+    },
+    { "id": "exp03_ambiguous_two_calls", "family": "ambiguous before-after", "evidence": "One call is removed and another added; the human text does not select one meaning.", "expected": { "outcome": "uncompilable", "uncertainty": ["two exact alternatives"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["removed-call alternative", "added-call alternative"], "reason": "Hunch refused to choose between two exact supported candidates." } },
+    { "id": "exp03_duplicate_target", "family": "ambiguous symbol", "evidence": "The removed callee name resolves to two current symbols.", "expected": { "outcome": "uncompilable", "uncertainty": ["ambiguous target"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["removed-call target is ambiguous"], "reason": "No exact binding exists." } },
+    { "id": "exp03_human_unnamed", "family": "structural coincidence", "evidence": "The diff is exact but the human judgment names neither endpoint.", "expected": { "outcome": "uncompilable", "uncertainty": ["human grounding absent"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["structural coincidence not explicitly named"], "reason": "No exact supported structural assertion." } },
+    { "id": "exp03_removed_symbol", "family": "retired symbol", "evidence": "The historical symbol has no enforceable current binding.", "expected": { "outcome": "uncompilable", "uncertainty": ["missing current binding"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["removed symbol has no enforceable current binding"] } },
+    { "id": "exp03_moved_symbol", "family": "rename and move", "evidence": "A move requires repair semantics and cannot be recast as exists.", "expected": { "outcome": "uncompilable", "uncertainty": ["repair semantics required"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["moved symbol needs repair semantics"] } },
+    { "id": "exp03_positive_external", "family": "positive package requirement", "evidence": "Adding an external import does not prove that the package must remain required.", "expected": { "outcome": "uncompilable", "uncertainty": ["positive requirement unsupported"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["positive package requirement evaluator absent"] } },
+    { "id": "exp03_same_component_relative", "family": "internal relative import", "evidence": "Both files belong to one component; no component edge represents the file relation.", "expected": { "outcome": "uncompilable", "uncertainty": ["internal edge unsupported"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["component evaluator cannot represent an internal file edge"] } },
+    { "id": "exp03_import_map", "family": "import-map boundary", "evidence": "A # alias has no exact local target without project-specific resolution.", "expected": { "outcome": "uncompilable", "uncertainty": ["import map unsupported"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["relative target missing and external package refused"] } },
+    { "id": "exp03_missing_relative_target", "family": "missing binding", "evidence": "The relative target no longer exists in the current graph.", "expected": { "outcome": "uncompilable", "uncertainty": ["missing target"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["relative import target is missing"] } },
+    { "id": "exp03_direct_conflict", "family": "contradictory decision", "evidence": "A new not-reaches candidate directly opposes an incumbent reaches policy over the same scope.", "expected": { "outcome": "conflicted", "conflicts": ["pol_aaaaaaaaaa"] }, "actual": { "outcome": "conflicted", "conflicts": ["pol_aaaaaaaaaa"], "reason": "No policy minted and no authority changed." } },
+    { "id": "exp03_equivalent_incumbent", "family": "existing equivalent", "evidence": "Assertion, scope, and data class exactly match an incumbent.", "expected": { "outcome": "covered", "incumbent": "pol_bbbbbbbbbb" }, "actual": { "outcome": "covered", "incumbent": "pol_bbbbbbbbbb", "reason": "Incumbent lifecycle preserved and evidence linked." } },
+    {
+      "id": "exp03_private_exact",
+      "family": "private evidence",
+      "evidence": "A private human-confirmed fix yields the same exact assertion in the private home.",
+      "expected": { "outcome": "assertion", "assertion": { "kind": "reaches", "subject": { "selector": "symbol:src/payments/charge.ts:charge" }, "relation": { "edges": ["calls"], "transitive": false, "max_depth": 1 }, "object": { "selector": "symbol:src/auth/session.ts:verifySession" } }, "scope": { "repos": [], "paths": ["src/payments/charge.ts"], "components": ["cmp_payments"] } },
+      "actual": { "outcome": "assertion", "assertion": { "kind": "reaches", "subject": { "selector": "symbol:src/payments/charge.ts:charge" }, "relation": { "edges": ["calls"], "transitive": false, "max_depth": 1 }, "object": { "selector": "symbol:src/auth/session.ts:verifySession" } }, "scope": { "repos": [], "paths": ["src/payments/charge.ts"], "components": ["cmp_payments"] } }
+    },
+    { "id": "exp03_prose_only_instruction", "family": "prose-only judgment", "evidence": "The instruction contains no supported structured predicate or attributable delta.", "expected": { "outcome": "uncompilable", "uncertainty": ["no deterministic evaluator"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["normalized instruction is evidence-only"] } },
+    { "id": "exp03_multi_family_delta", "family": "mixed large fix", "evidence": "The fix yields exact call, symbol, and import candidates with no human-selected meaning.", "expected": { "outcome": "uncompilable", "uncertainty": ["multiple meanings"] }, "actual": { "outcome": "uncompilable", "uncertainty": ["call alternative", "symbol alternative", "import alternative"] } }
+  ]
+}