instar 1.2.68 → 1.2.69

package/dist/server/specReviewRoutes.js

@@ -0,0 +1,120 @@
+/**
+ * Spec-review HTTP routes — the standards-conformance gate surface.
+ *
+ *   POST /spec/conformance-check   — check a spec against the constitution → report
+ *   GET  /spec/conformance-metrics — observability funnel (runs, per-standard flags)
+ *
+ * Signal-only (spec §4): returns a report; never blocks. Operator/skill-callable;
+ * classified INTERNAL (build-time tool, not an agent-discoverable runtime capability).
+ *
+ * Spec: docs/specs/standards-conformance-gate.md §3, §5.
+ */
+import { Router } from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadStandardsRegistry, parseStandardsRegistry, runRegistryCanary } from '../core/StandardsRegistryParser.js';
+import { StandardsConformanceReviewer } from '../core/reviewers/standards-conformance.js';
+function emptyMetrics() {
+    return { runs: 0, degraded: 0, findings_total: 0, by_standard: {}, last_run_at: null };
+}
+function loadMetrics(file) {
+    try {
+        if (fs.existsSync(file)) {
+            const m = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            return { ...emptyMetrics(), ...m, by_standard: m.by_standard ?? {} };
+        }
+    }
+    catch { /* corrupt → fresh */ }
+    return emptyMetrics();
+}
+function saveMetrics(file, m) {
+    try {
+        const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify(m, null, 2));
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        console.error(`[specReviewRoutes] metrics save failed: ${err}`);
+    }
+}
+export function createSpecReviewRoutes(deps) {
+    const router = Router();
+    const enabled = deps.enabled !== false;
+    const metricsFile = path.join(deps.stateDir, 'spec-conformance-metrics.json');
+    const reviewer = new StandardsConformanceReviewer(deps.intelligence, { model: deps.model });
+    if (!enabled) {
+        router.use('/spec', (_req, res) => res.status(503).json({ error: 'spec conformance gate disabled' }));
+        return router;
+    }
+    /** Resolve a caller-supplied specPath safely within specsDir (block traversal). */
+    function resolveSpecPath(specPath) {
+        const resolved = path.resolve(deps.specsDir, specPath);
+        const base = path.resolve(deps.specsDir);
+        if (resolved !== base && !resolved.startsWith(base + path.sep))
+            return null;
+        return resolved;
+    }
+    router.post('/spec/conformance-check', async (req, res) => {
+        let markdown;
+        if (typeof req.body?.markdown === 'string' && req.body.markdown.trim()) {
+            markdown = req.body.markdown;
+        }
+        else if (typeof req.body?.specPath === 'string' && req.body.specPath.trim()) {
+            const p = resolveSpecPath(req.body.specPath);
+            if (!p)
+                return res.status(400).json({ error: 'specPath escapes specsDir' });
+            if (!fs.existsSync(p))
+                return res.status(404).json({ error: 'spec not found' });
+            try {
+                markdown = fs.readFileSync(p, 'utf-8');
+            }
+            catch (err) {
+                return res.status(500).json({ error: `read failed: ${err.message}` });
+            }
+        }
+        else {
+            return res.status(400).json({ error: 'provide markdown or specPath' });
+        }
+        if (typeof markdown !== 'string' || !markdown.trim()) {
+            return res.status(400).json({ error: 'empty spec content' });
+        }
+        // Load + canary the constitution; a drifted/partial registry must not silently
+        // produce a misleadingly-clean report.
+        let articles;
+        try {
+            articles = loadStandardsRegistry(deps.registryPath);
+        }
+        catch (err) {
+            return res.status(503).json({ error: `constitution unreadable: ${err.message}` });
+        }
+        const canary = runRegistryCanary(articles);
+        const report = await reviewer.review(markdown, articles);
+        // Record metrics (best-effort).
+        try {
+            const m = loadMetrics(metricsFile);
+            m.runs += 1;
+            if (report.degraded)
+                m.degraded += 1;
+            m.findings_total += report.findings.length;
+            for (const f of report.findings)
+                m.by_standard[f.standard] = (m.by_standard[f.standard] ?? 0) + 1;
+            m.last_run_at = report.checkedAt;
+            saveMetrics(metricsFile, m);
+        }
+        catch { /* metering best-effort */ }
+        res.json({ report, registryCanary: canary });
+    });
+    router.get('/spec/conformance-metrics', (_req, res) => {
+        res.json({ metrics: loadMetrics(metricsFile) });
+    });
+    return router;
+}
+/** Exposed for the CLI (no HTTP): run a conformance check on raw markdown. */
+export async function runConformanceCheck(markdown, registryMarkdown, intelligence, model) {
+    const articles = parseStandardsRegistry(registryMarkdown);
+    const canary = runRegistryCanary(articles);
+    const reviewer = new StandardsConformanceReviewer(intelligence, { model });
+    const report = await reviewer.review(markdown, articles);
+    return { report, registryCanary: canary };
+}
+//# sourceMappingURL=specReviewRoutes.js.map

package/dist/server/specReviewRoutes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specReviewRoutes.js","sourceRoot":"","sources":["../../src/server/specReviewRoutes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.68",
+  "version": "1.2.69",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-25T02:41:21.838Z",
-  "instarVersion": "1.2.68",
+  "generatedAt": "2026-05-25T03:15:08.421Z",
+  "instarVersion": "1.2.69",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -1440,7 +1440,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "cbf06f2573314195ce811cdff252431d100f7a524c0339d4bc8c7a10b091ef48",
+      "contentHash": "038365abc27a181166c64817b88b92dd4cd4fdcf33d9444040da91ba9f821f5b",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

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.