instar 1.2.67 → 1.2.69

package/upgrades/1.2.69.md

@@ -0,0 +1,73 @@
+# Upgrade Guide — the review gate now reads the constitution
+
+<!-- bump: minor -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+
+## What Changed
+
+**The constitution stops being a doc nobody checks.**
+
+The living constitution (`docs/STANDARDS-REGISTRY.md`) has been on main for a
+while, but nothing actually *read* it when a new spec was written — the
+"check this against the standards" step was a prompt the reviewer had to remember,
+and on some hosts the tool that runs it isn't even installed. So a spec could
+break a standard and slip through: the North Star draft quietly violated **No
+Manual Work**, the review missed it, and only Justin caught it. The rulebook
+existed with no inspector — the exact "shipped but asleep" trap the rulebook was
+written to fight, turned on itself.
+
+This builds the inspector:
+
+- **A registry parser** reads the constitution into structured articles, with a
+  **canary** so a formatting change can't silently hide half the rulebook (it
+  asserts a sane article count and that anchor articles parse).
+- **A conformance reviewer** checks a draft spec against every article and returns
+  a rule-by-rule report ("this part might break No-Manual-Work, here's why"). It
+  runs on the subscription LLM path (never a raw API client), is degrade-safe (a
+  down provider yields an empty report, never blocks spec work), and is
+  prompt-injection-hardened (the spec is treated as untrusted data).
+- **It SIGNALS, never blocks.** The report advises; the human + the existing
+  approval gate decide. Blocking authority is a deliberate later step, gated on
+  measured precision.
+- **Observability**: `GET /spec/conformance-metrics` shows runs and which standards
+  get flagged most — the heat map of where our drafts drift, which itself feeds
+  evolution.
+
+Default-on (`specReview.conformance.enabled`); 503-stubs cleanly where the
+constitution isn't present.
+
+**Evidence**: 20 new tests across all three tiers (10 unit, 6 integration, 4 e2e)
+— 117 related (discoverability/config/route) tests green; `tsc` + lint clean
+(including the no-raw-LLM-HTTP guard). The Tier-3 e2e reproduces the motivating
+incident in miniature: a spec whose design requires manual work is fed to the gate
+and flagged against **No Manual Work**, while a conforming spec is not (no false
+positive). The parser is verified against the real on-disk constitution (22
+articles, canary green).
+
+Spec: `docs/specs/standards-conformance-gate.md` (approved; Claude-authored +
+manual review — full multi-model convergence tooling absent on host, caveat
+ratified explicitly). ELI16: `docs/specs/standards-conformance-gate.eli16.md`.
+Side-effects: `upgrades/side-effects/standards-conformance-gate.md`.
+
+## What to Tell Your User
+
+- **The rulebook now checks the work**: "When I write a new plan, a checker now
+  reads our actual standards and flags anything that might break one — so a plan
+  can't quietly violate a rule and slip past. It advises; we still decide."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Spec standards-conformance check | `POST /spec/conformance-check` (`{markdown}` or `{specPath}`) → rule-by-rule report |
+| Conformance observability | `GET /spec/conformance-metrics` → runs + per-standard flag counts |
+| Constitution parser + canary | `StandardsRegistryParser` (drift-guarded) |
+
+## Evidence
+
+Not a bug fix — a new capability. Verified end-to-end (not unit-mocked) by the
+Tier-3 e2e that reproduces the motivating incident: a manual-work-requiring spec
+is flagged against No Manual Work, a conforming spec is not. The registry parser
+is exercised against the real on-disk constitution (22 articles parsed, canary
+green). Signal-only by construction (no `block` path exists). 137 tests green
+across the feature + related suites; `tsc` + lint clean.

package/upgrades/side-effects/standards-conformance-gate.md

@@ -0,0 +1,87 @@
+# Side-effects review — standards-conformance gate
+
+**Scope**: Make the living constitution enforceable — a code-backed reviewer that
+reads `docs/STANDARDS-REGISTRY.md` and signals possible standard-violations in a
+draft spec, turning the manual/prompt-driven conformance pass into structure. The
+rung-3 normative slice; directly fixes `[[feedback_spec_review_against_standards]]`
+(the North Star draft violated No-Manual-Work, review missed it, Justin caught it).
+Spec: `docs/specs/standards-conformance-gate.md` (approved; Claude-authored +
+manual review — see honest convergence note).
+
+**Files touched**:
+- `src/core/StandardsRegistryParser.ts` — NEW. Deterministic parse of the
+  constitution into `{family,name,rule,inPractice}[]` (tracks the five standards
+  `##` families so non-article `###` sections — Genesis etc. — are excluded);
+  `runRegistryCanary` (state-detector: ≥15 articles + anchor articles present).
+- `src/core/reviewers/standards-conformance.ts` — NEW. `StandardsConformanceReviewer`:
+  injected `IntelligenceProvider` (subscription path), anti-injection prompt (spec
+  fenced as untrusted data), degrade-safe (no provider/throw/unparseable → empty
+  report), drops hallucinated standards not in the registry, `capable` tier.
+- `src/server/specReviewRoutes.ts` — NEW. `POST /spec/conformance-check` (markdown
+  or specPath, traversal-guarded) → report + registry canary; `GET
+  /spec/conformance-metrics`; file-backed metrics (reloads on restart); 503-stub
+  when disabled. Exports `runConformanceCheck` for the (deferred) CLI.
+- `src/server/AgentServer.ts` — mount the routes; new optional `intelligence` in
+  `AgentServerOptions`.
+- `src/commands/server.ts` — pass `intelligence: sharedIntelligence` to AgentServer.
+- `src/server/CapabilityIndex.ts` — `spec` → `INTERNAL_PREFIXES`.
+- `src/config/ConfigDefaults.ts` + `src/core/types.ts` — `specReview.conformance.enabled`
+  default true (auto init+migration).
+- `docs/specs/06-state-detector-registry.md` — registry-parser row.
+- Tests: unit/integration/e2e for the gate; updated `capabilities-discoverability`
+  to scan `specReviewRoutes.ts` (so the `spec` INTERNAL prefix resolves).
+
+**Under-block**: The gate SIGNALS only — it cannot block anything in v1 (no code
+path grants it authority), so it cannot wrongly stop a spec. The registry canary
+runs on every check; a drifted/partial registry surfaces in the response
+(`registryCanary.ok=false`) rather than silently producing a clean report. The
+traversal guard rejects specPath escaping specsDir.
+
+**Over-block**: None possible — signal-only. A false-positive finding costs one
+advisory line in a report the human reads, never a blocked commit.
+
+**Level-of-abstraction fit**: The constitution stays the single source of truth
+(the parser reads it; nothing duplicates the standards). The reviewer reuses the
+established LLM-reviewer pattern (injected provider, anti-injection, fail-open)
+rather than a bespoke LLM client. The route is a thin surface over parser +
+reviewer. Signal-vs-authority is structural: the reviewer has no `block` path.
+
+**Signal vs authority**: The whole feature is a signal producer. The human
+ratification + the instar-dev `approved:true` gate retain all authority. Promotion
+to a blocking/warn signal in the precommit gate is the tracked `scg-blocking-authority`
+follow-up, gated on measured precision.
+
+**Interactions**:
+- Reads `docs/STANDARDS-REGISTRY.md` from `config.projectDir/docs`. For Echo (repo
+  checkout) it's present; a deployed agent without the repo docs gets a clean 503
+  ("constitution unreadable") — correct (the gate is a build-time tool, inert where
+  there's no constitution).
+- Adds one `capable`-tier LLM call per conformance check (per-spec, rare) through
+  `sharedIntelligence` — degrade-safe, never blocks spec work if the provider is down.
+- New `intelligence` option on AgentServer is additive (optional); existing
+  construction unaffected.
+- File-backed metrics at `stateDir/spec-conformance-metrics.json` (atomic
+  temp+rename); corrupt → fresh.
+
+**External surfaces**:
+- `POST /spec/conformance-check`, `GET /spec/conformance-metrics` (INTERNAL prefix).
+- New config `specReview.conformance.enabled` (default true).
+- New exported `runConformanceCheck` (for the deferred CLI).
+
+**Deferred (tracked)**: `instar spec conformance` CLI (`scg-cli`) — thin wrapper
+over `runConformanceCheck`; the route delivers the capability. Auto-blocking
+authority (`scg-blocking-authority`). Richer markdown parser (`scg-richer-parser`).
+
+**Rollback cost**: Low, strictly additive. Remove the routes + reviewer + parser;
+the constitution returns to being read only by the manual `/spec-converge` pass
+(today's state). No existing runtime path is modified.
+
+**Migration parity**: New server-side code + routes + config default (init +
+`migrateConfig` via ConfigDefaults) + INTERNAL prefix. The parser reads a
+repo-shipped doc (no per-agent state). No hook/template/skill-file change.
+
+**Convergence honesty**: Claude-authored + manual review only; full
+`/spec-converge` + `/crossreview` multi-model tooling absent on host. Ratified by
+Justin with that caveat explicit. CI + the known-violating-spec e2e are the
+strongest current evidence; a fuller multi-model review remains advisable —
+fittingly, this is the tool that would make that conformance pass structural.