instar 1.3.708 → 1.3.709

package/dist/data/llmBenchCoverage.d.ts

@@ -0,0 +1,34 @@
+/**
+ * LLM Benchmark Coverage Map — INSTAR-Bench v2 ratchet #2.
+ *
+ * Every LLM-driven component (a key of COMPONENT_CATEGORY in
+ * src/core/componentCategories.ts) must map to exactly one of:
+ *   - { task: '<bench-task-id>' } — covered by an INSTAR-Bench v2 task
+ *     (task definitions live in the bench harness:
+ *     research/llm-pathway-bench/instar-bench-v2/tasks/ on the benching
+ *     agent; the id here is the durable contract),
+ *   - { pending: '<wave>' } — authoring queued; the pending set is PINNED
+ *     shrink-only in tests/unit/llm-bench-coverage-ratchet.test.ts (you can
+ *     graduate an entry to covered, you cannot add one without editing the
+ *     pinned test — a visible, reviewed act),
+ *   - { exempt: '<argued reason>' } — a real argument why benching this
+ *     component is not meaningful (also pinned shrink-only).
+ *
+ * WHY (operator directive 2026-07-02, topic 29723 + INSTAR-BENCH-V2-SPEC §6):
+ * adding an LLM callsite without benchmark coverage must fail the build —
+ * an unbenched decision-maker is an unmeasured one, and routing defaults are
+ * benchmark-derived. Structure > Willpower.
+ *
+ * Companion ratchet: the wiring test (componentCategories-evaluate-coverage)
+ * keeps COMPONENT_CATEGORY exhaustive over .evaluate() callsites; THIS map +
+ * its test keep bench coverage exhaustive over COMPONENT_CATEGORY.
+ */
+export type BenchCoverage = {
+    task: string;
+} | {
+    pending: 'wave-2' | 'wave-3';
+} | {
+    exempt: string;
+};
+export declare const LLM_BENCH_COVERAGE: Readonly<Record<string, BenchCoverage>>;
+//# sourceMappingURL=llmBenchCoverage.d.ts.map

package/dist/data/llmBenchCoverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmBenchCoverage.d.ts","sourceRoot":"","sources":["../../src/data/llmBenchCoverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,GAChC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvB,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAiEtE,CAAC"}

package/dist/data/llmBenchCoverage.js

@@ -0,0 +1,88 @@
+/**
+ * LLM Benchmark Coverage Map — INSTAR-Bench v2 ratchet #2.
+ *
+ * Every LLM-driven component (a key of COMPONENT_CATEGORY in
+ * src/core/componentCategories.ts) must map to exactly one of:
+ *   - { task: '<bench-task-id>' } — covered by an INSTAR-Bench v2 task
+ *     (task definitions live in the bench harness:
+ *     research/llm-pathway-bench/instar-bench-v2/tasks/ on the benching
+ *     agent; the id here is the durable contract),
+ *   - { pending: '<wave>' } — authoring queued; the pending set is PINNED
+ *     shrink-only in tests/unit/llm-bench-coverage-ratchet.test.ts (you can
+ *     graduate an entry to covered, you cannot add one without editing the
+ *     pinned test — a visible, reviewed act),
+ *   - { exempt: '<argued reason>' } — a real argument why benching this
+ *     component is not meaningful (also pinned shrink-only).
+ *
+ * WHY (operator directive 2026-07-02, topic 29723 + INSTAR-BENCH-V2-SPEC §6):
+ * adding an LLM callsite without benchmark coverage must fail the build —
+ * an unbenched decision-maker is an unmeasured one, and routing defaults are
+ * benchmark-derived. Structure > Willpower.
+ *
+ * Companion ratchet: the wiring test (componentCategories-evaluate-coverage)
+ * keeps COMPONENT_CATEGORY exhaustive over .evaluate() callsites; THIS map +
+ * its test keep bench coverage exhaustive over COMPONENT_CATEGORY.
+ */
+export const LLM_BENCH_COVERAGE = {
+    // ── Covered by the critical set (Wave 1 — authored 2026-07-02) ──
+    MessageSentinel: { task: 'sentinel-classify' },
+    MessagingToneGate: { task: 'tone-gate' },
+    // CompletionEvaluator has TWO judged surfaces; both benched.
+    CompletionEvaluator: { task: 'completion-judge+p13-stop-judge' },
+    ExternalOperationGate: { task: 'external-op-gate' },
+    LLMSanitizer: { task: 'injection-sanitizer' },
+    WarrantsReplyGate: { task: 'warrants-reply' },
+    InputClassifier: { task: 'input-classifier' },
+    Usher: { task: 'usher' },
+    'correction-learning': { task: 'correction-distiller' },
+    CoherenceReviewer: { task: 'gate-triage' },
+    // ── Argued exemptions (pinned; each must carry a real reason) ──
+    InteractivePoolCanaryJudge: {
+        exempt: 'judges a FIXED known-answer canary probe — the canary is its own benchmark; a bench task would re-test the same constant',
+    },
+    // ── Wave 2 (sentinels/gates/extractors still to author) ──
+    InputDetector: { pending: 'wave-2' },
+    InputGuard: { pending: 'wave-2' },
+    SessionActivitySentinel: { pending: 'wave-2' },
+    StallTriageNurse: { pending: 'wave-2' },
+    CommitmentSentinel: { pending: 'wave-2' },
+    PresenceProxy: { pending: 'wave-2' },
+    PromiseBeacon: { pending: 'wave-2' },
+    ProjectDriftChecker: { pending: 'wave-2' },
+    TemporalCoherenceChecker: { pending: 'wave-2' },
+    SessionWatchdog: { pending: 'wave-2' },
+    ResumeQueueDrainer: { pending: 'wave-2' },
+    TopicIntentArcCheck: { pending: 'wave-2' },
+    SlackAdapter: { pending: 'wave-2' },
+    TelegramAdapter: { pending: 'wave-2' },
+    PromptGate: { pending: 'wave-2' },
+    AutoApprover: { pending: 'wave-2' },
+    IntegrationGate: { pending: 'wave-2' },
+    UnjustifiedStopGate: { pending: 'wave-2' },
+    CoherenceGate: { pending: 'wave-2' },
+    OverrideDetector: { pending: 'wave-2' },
+    TaskClassifier: { pending: 'wave-2' },
+    ResumeValidator: { pending: 'wave-2' },
+    SessionSummarySentinel: { pending: 'wave-2' },
+    TopicIntentExtractor: { pending: 'wave-2' },
+    // ── Wave 3 (reflectors + background/job tasks) ──
+    JobReflector: { pending: 'wave-3' },
+    crossModelReviewer: { pending: 'wave-3' },
+    SelfKnowledgeTree: { pending: 'wave-3' },
+    TreeTriage: { pending: 'wave-3' },
+    TopicSummarizer: { pending: 'wave-3' },
+    ContextualEvaluator: { pending: 'wave-3' },
+    RelationshipManager: { pending: 'wave-3' },
+    StandardsConformanceReviewer: { pending: 'wave-3' },
+    DiscoveryEvaluator: { pending: 'wave-3' },
+    PipeSessionSpawner: { pending: 'wave-3' },
+    CartographerSweep: { pending: 'wave-3' },
+    StandardsCoverageEnrichment: { pending: 'wave-3' },
+    PreCompactionFlush: { pending: 'wave-3' },
+    TreeSynthesis: { pending: 'wave-3' },
+    LLMConflictResolver: { pending: 'wave-3' },
+    openConversationBrief: { pending: 'wave-3' },
+    'a2a-checkin': { pending: 'wave-3' },
+    'mentor-stage-b': { pending: 'wave-3' },
+};
+//# sourceMappingURL=llmBenchCoverage.js.map

package/dist/data/llmBenchCoverage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.708",
+  "version": "1.3.709",
   "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-07-02T08:43:26.009Z",
-  "instarVersion": "1.3.708",
+  "generatedAt": "2026-07-02T08:48:48.771Z",
+  "instarVersion": "1.3.709",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/llmBenchCoverage.ts

@@ -0,0 +1,97 @@
+/**
+ * LLM Benchmark Coverage Map — INSTAR-Bench v2 ratchet #2.
+ *
+ * Every LLM-driven component (a key of COMPONENT_CATEGORY in
+ * src/core/componentCategories.ts) must map to exactly one of:
+ *   - { task: '<bench-task-id>' } — covered by an INSTAR-Bench v2 task
+ *     (task definitions live in the bench harness:
+ *     research/llm-pathway-bench/instar-bench-v2/tasks/ on the benching
+ *     agent; the id here is the durable contract),
+ *   - { pending: '<wave>' } — authoring queued; the pending set is PINNED
+ *     shrink-only in tests/unit/llm-bench-coverage-ratchet.test.ts (you can
+ *     graduate an entry to covered, you cannot add one without editing the
+ *     pinned test — a visible, reviewed act),
+ *   - { exempt: '<argued reason>' } — a real argument why benching this
+ *     component is not meaningful (also pinned shrink-only).
+ *
+ * WHY (operator directive 2026-07-02, topic 29723 + INSTAR-BENCH-V2-SPEC §6):
+ * adding an LLM callsite without benchmark coverage must fail the build —
+ * an unbenched decision-maker is an unmeasured one, and routing defaults are
+ * benchmark-derived. Structure > Willpower.
+ *
+ * Companion ratchet: the wiring test (componentCategories-evaluate-coverage)
+ * keeps COMPONENT_CATEGORY exhaustive over .evaluate() callsites; THIS map +
+ * its test keep bench coverage exhaustive over COMPONENT_CATEGORY.
+ */
+
+export type BenchCoverage =
+  | { task: string }
+  | { pending: 'wave-2' | 'wave-3' }
+  | { exempt: string };
+
+export const LLM_BENCH_COVERAGE: Readonly<Record<string, BenchCoverage>> = {
+  // ── Covered by the critical set (Wave 1 — authored 2026-07-02) ──
+  MessageSentinel: { task: 'sentinel-classify' },
+  MessagingToneGate: { task: 'tone-gate' },
+  // CompletionEvaluator has TWO judged surfaces; both benched.
+  CompletionEvaluator: { task: 'completion-judge+p13-stop-judge' },
+  ExternalOperationGate: { task: 'external-op-gate' },
+  LLMSanitizer: { task: 'injection-sanitizer' },
+  WarrantsReplyGate: { task: 'warrants-reply' },
+  InputClassifier: { task: 'input-classifier' },
+  Usher: { task: 'usher' },
+  'correction-learning': { task: 'correction-distiller' },
+  CoherenceReviewer: { task: 'gate-triage' },
+
+  // ── Argued exemptions (pinned; each must carry a real reason) ──
+  InteractivePoolCanaryJudge: {
+    exempt:
+      'judges a FIXED known-answer canary probe — the canary is its own benchmark; a bench task would re-test the same constant',
+  },
+
+  // ── Wave 2 (sentinels/gates/extractors still to author) ──
+  InputDetector: { pending: 'wave-2' },
+  InputGuard: { pending: 'wave-2' },
+  SessionActivitySentinel: { pending: 'wave-2' },
+  StallTriageNurse: { pending: 'wave-2' },
+  CommitmentSentinel: { pending: 'wave-2' },
+  PresenceProxy: { pending: 'wave-2' },
+  PromiseBeacon: { pending: 'wave-2' },
+  ProjectDriftChecker: { pending: 'wave-2' },
+  TemporalCoherenceChecker: { pending: 'wave-2' },
+  SessionWatchdog: { pending: 'wave-2' },
+  ResumeQueueDrainer: { pending: 'wave-2' },
+  TopicIntentArcCheck: { pending: 'wave-2' },
+  SlackAdapter: { pending: 'wave-2' },
+  TelegramAdapter: { pending: 'wave-2' },
+  PromptGate: { pending: 'wave-2' },
+  AutoApprover: { pending: 'wave-2' },
+  IntegrationGate: { pending: 'wave-2' },
+  UnjustifiedStopGate: { pending: 'wave-2' },
+  CoherenceGate: { pending: 'wave-2' },
+  OverrideDetector: { pending: 'wave-2' },
+  TaskClassifier: { pending: 'wave-2' },
+  ResumeValidator: { pending: 'wave-2' },
+  SessionSummarySentinel: { pending: 'wave-2' },
+  TopicIntentExtractor: { pending: 'wave-2' },
+
+  // ── Wave 3 (reflectors + background/job tasks) ──
+  JobReflector: { pending: 'wave-3' },
+  crossModelReviewer: { pending: 'wave-3' },
+  SelfKnowledgeTree: { pending: 'wave-3' },
+  TreeTriage: { pending: 'wave-3' },
+  TopicSummarizer: { pending: 'wave-3' },
+  ContextualEvaluator: { pending: 'wave-3' },
+  RelationshipManager: { pending: 'wave-3' },
+  StandardsConformanceReviewer: { pending: 'wave-3' },
+  DiscoveryEvaluator: { pending: 'wave-3' },
+  PipeSessionSpawner: { pending: 'wave-3' },
+  CartographerSweep: { pending: 'wave-3' },
+  StandardsCoverageEnrichment: { pending: 'wave-3' },
+  PreCompactionFlush: { pending: 'wave-3' },
+  TreeSynthesis: { pending: 'wave-3' },
+  LLMConflictResolver: { pending: 'wave-3' },
+  openConversationBrief: { pending: 'wave-3' },
+  'a2a-checkin': { pending: 'wave-3' },
+  'mentor-stage-b': { pending: 'wave-3' },
+};

package/upgrades/1.3.709.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+INSTAR-Bench v2 ratchet #2 (spec §6; operator directive 2026-07-02, topic
+29723): a new coverage ledger (`src/data/llmBenchCoverage.ts`) maps every LLM
+component in `COMPONENT_CATEGORY` to its benchmark status — covered by a
+named bench task (the 10 Wave-1 critical gates/sentinels), pending (42,
+pinned shrink-only), or exempt (1, argued). A CI test
+(`llm-bench-coverage-ratchet.test.ts`) fails the build when a new LLM
+component ships without a coverage decision, when the pending/exempt sets
+GROW (graduating shrinks them; adding requires editing the pinned baseline in
+the test — a visible, reviewed act), when an exemption's argument is lazy, or
+when a Wave-1 critical component slides back to uncovered.
+
+Together with the existing attribution ratchet + category-map wiring test,
+the chain is closed: every LLM callsite must be attributed → categorized/
+routed deliberately → benchmark-covered. No runtime surface; build-time only.
+
+## What to Tell Your User
+
+Nothing proactively — no behavior changes. If asked: every one of my internal
+AI helpers is now tracked against a benchmark coverage ledger, so any new
+helper added to my infrastructure must ship with quality measurements (or a
+written argument why not) before the build goes green. It keeps my model
+choices grounded in measured results instead of guesses.
+
+## Summary of New Capabilities
+
+None user-facing. New build-time guarantee: `src/data/llmBenchCoverage.ts`
+(the coverage ledger) + `llm-bench-coverage-ratchet.test.ts` (the CI ratchet).
+The ledger is importable by future tooling (e.g. the bench runner's coverage
+report) but nothing at runtime consumes it yet.
+
+## Evidence
+
+6 new tests green (completeness, no-dangling, shrink-only pins ×2, argued
+exemptions, Wave-1 regression pin); `tsc --noEmit` clean; full unit suite
+green at push.

package/upgrades/llm-bench-coverage-ratchet.eli16.md

@@ -0,0 +1,11 @@
+# New AI decision-makers now have to bring a test report card
+
+Instar has about fifty little AI helpers inside it — one classifies your messages, one reviews outgoing replies, one judges whether an autonomous work session really finished, and so on. We just started benchmarking these helpers properly: for each one, a battery of hard test cases that tells us which AI model does that specific job well, fast, and cheap. Those measurements are what our model-routing choices will be based on going forward.
+
+But a benchmark only stays trustworthy if it stays complete. The failure mode is silent: someone adds a NEW AI helper next month, nobody writes test cases for it, and suddenly there's an unmeasured decision-maker running in production whose model was picked by vibes. Six months later there are ten of those and the benchmark is a museum piece.
+
+This change makes that impossible — not by policy, by build failure. There's now a coverage ledger listing every AI helper and its benchmark status: covered (with the name of its test battery), queued for authoring (an explicitly pinned to-do list), or exempt (with a written argument why testing it makes no sense — and "n/a" is literally rejected as too short). A test in the build system cross-checks that ledger against the master list of AI helpers. Add a new helper without deciding its benchmark story, and the build goes red with instructions telling you exactly what to do.
+
+The teeth are in the details: the "queued" list can only shrink. You can graduate an entry to covered, but adding a new name to the queue requires editing the pinned list inside the test itself — a change any reviewer will see and question. Same for exemptions. So the lazy path (quietly park it in the queue forever) is exactly as visible as the honest path (write the test cases). Ten of the most critical helpers — the message classifier, the outbound-message gate, the completion judge, the injection screener, and their peers — are additionally pinned as "may never slide back": once covered, always covered.
+
+This is the second ratchet of its kind. The first (already live) forces every new AI call site to register in the routing map so we know which provider runs it. Together they close the loop: every AI decision-maker in instar must be routed deliberately AND measured before it ships. Nothing changes at runtime — this is purely a build-time guarantee, and it costs nothing unless someone tries to skip the homework.

package/upgrades/side-effects/llm-bench-coverage-ratchet.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — LLM benchmark-coverage ratchet (INSTAR-Bench v2 §6, ratchet #2)
+
+**Version / slug:** `llm-bench-coverage-ratchet`
+**Date:** `2026-07-02`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `not required` (build-time test + data map only; zero runtime surface)
+
+## Summary of the change
+
+Adds `src/data/llmBenchCoverage.ts` — a coverage ledger mapping every LLM component (every key of `COMPONENT_CATEGORY`) to its INSTAR-Bench v2 status: `{task}` covered (10 Wave-1 critical components), `{pending}` queued (42, pinned), or `{exempt}` argued (1) — and `tests/unit/llm-bench-coverage-ratchet.test.ts`, which fails CI when a new LLM component ships without a coverage decision, when the pending/exempt sets grow (shrink-only pins), when an exemption's argument is lazy (<40 chars), or when a Wave-1 critical component slides back to uncovered. Operator directive 2026-07-02 (topic 29723) + INSTAR-BENCH-V2-SPEC §6. No runtime code is touched.
+
+## Decision-point inventory
+
+None at runtime. The only "decision" is a CI pass/fail on repository content — a build-time ratchet identical in class to the existing `llm-attribution-ratchet`.
+
+## 1. Over-block
+The ratchet can block a COMMIT (not a message/action): a developer adding an LLM component who genuinely cannot author bench cases yet must add the component to the pending baseline inside the test — a deliberate, visible act. That is the intended cost, not an over-block; there is no path it rejects that it shouldn't (an argued exemption is always available).
+
+## 2. Under-block
+Honest limits: (a) the ratchet keys off `COMPONENT_CATEGORY` — an LLM callsite that dodges the category map would also dodge this map, but the companion evaluate-coverage wiring test + attribution lint close that hole upstream; (b) it cannot verify the bench task file CONTENT (those live in the bench harness on the benching agent) — the task id is a contract, and a wrong/empty id would surface at the next bench run, not in CI. Accepted for v1 of the ratchet; noted in the map docblock.
+
+## 3. Level-of-abstraction fit
+Right layer: repository data + unit test, the established ratchet pattern (`llm-attribution-ratchet`, `WIRING_EXCLUSIONS` pins). Extends the existing chain (callsite → category map → THIS → bench coverage) rather than inventing a parallel mechanism.
+
+## 4. Signal vs authority compliance
+Compliant. No runtime authority; a CI test is deterministic, cheap, and its "block" is a build failure with instructions. (docs/signal-vs-authority.md concerns runtime decision points; none added.)
+
+## 5. Interactions
+Complements `llm-attribution-ratchet` (attribution presence), `componentCategories` wiring test (map exhaustiveness), and the LLM Routing Registry doc. No double-fire: each guards a different link of the chain. No runtime interaction possible.
+
+## 6. External surfaces
+None. Not user-visible; no API, no message, no config.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+Not applicable — repository content evaluated in CI; identical on every machine by construction (git).
+
+## 8. Rollback cost
+Delete the test + map (one revert). No state, no migration, no fleet impact — the ratchet only ever constrained future commits.
+
+## Test evidence
+`llm-bench-coverage-ratchet.test.ts`: 6 tests — completeness over COMPONENT_CATEGORY, no dangling entries, pending pinned shrink-only, exemptions pinned + argued, non-empty task ids, Wave-1 regression pin. All green; `tsc --noEmit` clean.