instar 1.3.897 → 1.3.899

package/src/data/provenanceCoverage.ts

@@ -115,6 +115,12 @@ export interface ProvenanceCoverageEntry {
   /** REQUIRED (≥40 chars, ratchet-enforced) for pending/exempt entries — a real
    * argument, never a lazy "n/a". Optional color for wired entries. */
   readonly reason?: string;
+  /** A wired point normally has at least one RULE_REGISTRY row. This explicit
+   * posture is the only honest exception: measurement-only means provenance is
+   * intentionally collected before an outcome rule exists; exempt means an
+   * outcome is structurally unavailable. Both require gradingReason. */
+  readonly gradingPosture?: 'measurement-only' | 'exempt';
+  readonly gradingReason?: string;
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -215,6 +221,9 @@ export const PROVENANCE_COVERAGE: ReadonlyArray<ProvenanceCoverageEntry> = [
     contentClass: 'content-bearing',
     reason:
       'The outbound tone/leak authority (spec §5.6 named high-volume point). Enrolled at budget:500/day, identity-only content — never the message body.',
+    gradingPosture: 'measurement-only',
+    gradingReason:
+      'Phase B will define a reviewed evidence rule and owner; Tier 1 records measurements without pretending they are outcome grades.',
   },
   {
     decisionPoint: DP_CORRECTION_CLASS_REVIEW,
@@ -224,6 +233,9 @@ export const PROVENANCE_COVERAGE: ReadonlyArray<ProvenanceCoverageEntry> = [
     contentClass: 'content-bearing',
     reason:
       'Each durable correction receives one bounded standards/process proposal; identity-only context supports outcome grading without archiving correction text.',
+    gradingPosture: 'measurement-only',
+    gradingReason:
+      'Phase B will define a reviewed evidence rule and owner; Tier 1 records measurements without pretending they are outcome grades.',
   },
   {
     decisionPoint: DP_COMPLETION_CLAIM_VERIFY,
@@ -233,6 +245,9 @@ export const PROVENANCE_COVERAGE: ReadonlyArray<ProvenanceCoverageEntry> = [
     contentClass: 'content-bearing',
     reason:
       'Completion-language turns receive clause arbitration before optional suppression authority; identity-only context preserves auditability without transcript content.',
+    gradingPosture: 'measurement-only',
+    gradingReason:
+      'Phase B will define a reviewed evidence rule and owner; Tier 1 records measurements without pretending they are outcome grades.',
   },
   {
     decisionPoint: DP_FEEDBACK_READINESS,
@@ -242,6 +257,9 @@ export const PROVENANCE_COVERAGE: ReadonlyArray<ProvenanceCoverageEntry> = [
     contentClass: 'content-bearing',
     reason:
       'A bounded frontier-model judgment authorizes cluster-to-work readiness; provenance stores packet identity and enumerated outcomes, never feedback text or model output.',
+    gradingPosture: 'measurement-only',
+    gradingReason:
+      'Phase B will define a reviewed evidence rule and owner; Tier 1 records measurements without pretending they are outcome grades.',
   },
 
   // ── Pending (the ACT-1193 uniform-provenance retrofit backlog — §5.6: "Not
@@ -764,6 +782,8 @@ export type EvidenceStrength = (typeof EVIDENCE_STRENGTHS)[number];
 
 export interface EvidenceRule {
   readonly ruleId: string;
+  /** Census decision point whose outcomes this rule grades. */
+  readonly decisionPoint: string;
   readonly rung: EvidenceRung;
   readonly evidenceStrength: EvidenceStrength;
   /** The ONLY component whose gradedBy.component the annotate chokepoint
@@ -785,6 +805,7 @@ export const RULE_REGISTRY: Readonly<Record<string, EvidenceRule>> = {
   // Positive-evidence grading runs in the sentinel's scan ticks + grade-on-supersede.
   'hog-respawn-wrong-v1': {
     ruleId: 'hog-respawn-wrong-v1',
+    decisionPoint: DP_EXTERNAL_HOG_KILL_LEAVE,
     rung: 'deterministic-ground-truth',
     evidenceStrength: 'deterministic-proof',
     owningComponent: 'ExternalHogSentinel',
@@ -796,6 +817,7 @@ export const RULE_REGISTRY: Readonly<Record<string, EvidenceRule>> = {
   // close grading runs in the grading job reading the durable hog store.
   'hog-sustained-right-v1': {
     ruleId: 'hog-sustained-right-v1',
+    decisionPoint: DP_EXTERNAL_HOG_KILL_LEAVE,
     rung: 'deterministic-ground-truth',
     evidenceStrength: 'negative-evidence',
     owningComponent: 'DecisionGrading',
@@ -808,6 +830,7 @@ export const RULE_REGISTRY: Readonly<Record<string, EvidenceRule>> = {
   // sentinel's scan ticks + grade-on-supersede.
   'hog-leave-recurrence-v1': {
     ruleId: 'hog-leave-recurrence-v1',
+    decisionPoint: DP_EXTERNAL_HOG_KILL_LEAVE,
     rung: 'recurrence',
     evidenceStrength: 'recurrence-proxy',
     owningComponent: 'ExternalHogSentinel',
@@ -819,6 +842,7 @@ export const RULE_REGISTRY: Readonly<Record<string, EvidenceRule>> = {
   // wiring binds gradedBy.component to this owner).
   'completion-realcheck-v1': {
     ruleId: 'completion-realcheck-v1',
+    decisionPoint: DP_COMPLETION_EVALUATE,
     rung: 'deterministic-ground-truth',
     evidenceStrength: 'deterministic-proof',
     owningComponent: 'AutonomousRealCheck',
@@ -828,18 +852,68 @@ export const RULE_REGISTRY: Readonly<Record<string, EvidenceRule>> = {
   // as a self-report-rung annotation (never overrides an independent grader).
   'hog-enacted-disposition-v1': {
     ruleId: 'hog-enacted-disposition-v1',
+    decisionPoint: DP_EXTERNAL_HOG_KILL_LEAVE,
     rung: 'self-report',
     evidenceStrength: 'self-report',
     owningComponent: 'ExternalHogSentinel',
   },
   'completion-enacted-disposition-v1': {
     ruleId: 'completion-enacted-disposition-v1',
+    decisionPoint: DP_COMPLETION_STOP_RATIONALE,
     rung: 'self-report',
     evidenceStrength: 'self-report',
     owningComponent: 'CompletionChokepoint',
   },
 };
 
+/** Loud class contradiction: a wired provenance point that cannot produce an
+ * outcome grade and has not explicitly declared measurement-only/exempt. */
+export function findWiredWithoutGraders(
+  coverage: ReadonlyArray<ProvenanceCoverageEntry> = PROVENANCE_COVERAGE,
+  registry: Readonly<Record<string, EvidenceRule>> = RULE_REGISTRY,
+): string[] {
+  const graded = new Set(Object.values(registry).map((rule) => rule.decisionPoint));
+  return coverage
+    .filter((entry) => {
+      if (entry.status !== 'wired' || graded.has(entry.decisionPoint)) return false;
+      const explicit = entry.gradingPosture === 'measurement-only' || entry.gradingPosture === 'exempt';
+      return !explicit || (entry.gradingReason ?? '').trim().length < 40;
+    })
+    .map((entry) => entry.decisionPoint)
+    .sort();
+}
+
+/** Full declaration-consistency audit used by the developer-process ratchet.
+ * Runtime reads surface the primary wired-but-no-grader subset; CI refuses all
+ * mutually contradictory source shapes. */
+export function findGradingContradictions(
+  coverage: ReadonlyArray<ProvenanceCoverageEntry> = PROVENANCE_COVERAGE,
+  registry: Readonly<Record<string, EvidenceRule>> = RULE_REGISTRY,
+): string[] {
+  const findings: string[] = [];
+  const counts = new Map<string, number>();
+  for (const entry of coverage) counts.set(entry.decisionPoint, (counts.get(entry.decisionPoint) ?? 0) + 1);
+  for (const [decisionPoint, count] of counts) {
+    if (count > 1) findings.push(`duplicate-census:${decisionPoint}`);
+  }
+  const byPoint = new Map(coverage.map((entry) => [entry.decisionPoint, entry]));
+  const graded = new Set<string>();
+  for (const rule of Object.values(registry)) {
+    graded.add(rule.decisionPoint);
+    const entry = byPoint.get(rule.decisionPoint);
+    if (!entry || entry.status !== 'wired') findings.push(`rule-target-not-wired:${rule.ruleId}:${rule.decisionPoint}`);
+  }
+  for (const entry of coverage) {
+    if (entry.status !== 'wired') continue;
+    const hasRule = graded.has(entry.decisionPoint);
+    const explicit = entry.gradingPosture === 'measurement-only' || entry.gradingPosture === 'exempt';
+    const validReason = (entry.gradingReason ?? '').trim().length >= 40;
+    if (hasRule && explicit) findings.push(`grader-and-${entry.gradingPosture}:${entry.decisionPoint}`);
+    if (!hasRule && (!explicit || !validReason)) findings.push(`wired-but-no-grader:${entry.decisionPoint}`);
+  }
+  return [...new Set(findings)].sort();
+}
+
 // ───────────────────────────────────────────────────────────────────────────
 // Lookup helpers (imported by the settlement seam, the annotate chokepoint,
 // the grading endpoint, and the read surface).

package/src/scaffold/templates/jobs/instar/llm-decision-grading.md

@@ -1,12 +1,12 @@
 ---
 name: LLM-Decision Grading Pass
-description: "Hourly deterministic grading pass over the LLM-decision quality substrate. Runs POST /decision-quality/grade-pass: the endpoint walks NEW outcome evidence since the durable per-decision-point cursor (keyset (ts, correlation_id) — same-ms bursts cannot skip rows), applies the registered deterministic evidence rules, and upserts right/wrong/unknown grades idempotently (re-runs converge, never multiply; bounded per pass by provenance.quality.maxDecisionsPerPass). ZERO LLM spend in the pass itself — the grading ladder in this build is deterministic-only (FD11; the LLM evidence-interpreter rung ships NO code, ACT-1198). Ships enabled:false (cost-bearing job class); the operator read surface is GET /decision-quality. NEVER messages the user (FD5 — the meter is observe-only; grading produces rows, not messages). Runs per machine over that machine's local rows (the ratified machine-local data posture). Tier-1 supervised (this haiku job wraps the deterministic endpoint and sanity-checks the response shape). Spec docs/specs/llm-decision-quality-meter.md §5.5."
+description: "Hourly deterministic grading pass over the LLM-decision quality substrate. Runs POST /decision-quality/grade-pass: the endpoint walks NEW outcome evidence since the durable per-decision-point cursor (keyset (ts, correlation_id) — same-ms bursts cannot skip rows), applies the registered deterministic evidence rules, and upserts right/wrong/unknown grades idempotently (re-runs converge, never multiply; bounded per pass by provenance.quality.maxDecisionsPerPass). ZERO LLM spend in the pass itself — the grading ladder in this build is deterministic-only. Ships enabled:true under the newer operator-directed goal-4 Tier-1 activation, superseding the original scaffold-dark default; the operator read surface is GET /decision-quality. NEVER messages the user (the meter is observe-only; grading produces rows, not messages). Runs per machine over that machine's local rows. Tier-1 supervised (this haiku job wraps the deterministic endpoint and sanity-checks the response shape). Substrate: docs/specs/llm-decision-quality-meter.md §5.5."
 schedule: "0 * * * *"
 priority: low
 expectedDurationMinutes: 2
 model: haiku
 supervision: tier1
-enabled: false
+enabled: true
 tags:
   - cat:observability
   - decision-quality

package/upgrades/1.3.898.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Strengthened the existing Maturation Path standard around the fixed test-agent → development-agent → fleet ladder.
+- Added a WARN-only structural check for `## Maturation plan`; convergence still succeeds while missing or partial plans emit `MATURATION_PLAN_WARN`.
+- Added durable, customization-safe update delivery for existing agent installations.
+
+## What to Tell Your User
+
+New staged-feature specs now make their graduation plan visible during review. This first increment warns without blocking so the format can mature safely before enforcement becomes hard.
+
+## Summary of New Capabilities
+
+- Detect missing or incomplete three-rung maturation plans during spec convergence.
+- Preserve customized installed tooling while safely updating recognized stock files.
+
+## Evidence
+
+- 44 targeted tests pass across the new parser, convergence wiring, migration failures, existing decision-point parsing, and standards enforcement audit.
+- Full TypeScript and repository lint pass.

package/upgrades/1.3.899.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- The provenance census now fails CI when a `wired` decision point has neither a registered evidence rule nor an explicit, reasoned measurement-only/exempt posture.
+- `GET /decision-quality` reports the new `wiredButNoGrader` contradiction list.
+- Autonomous run-end payloads carry real-check pass/fail/not-configured evidence into the existing outcome-annotation chokepoint.
+- The existing hourly `llm-decision-grading` scaffold job now ships enabled.
+- Existing deployed stock autonomous stop hooks are upgraded through the normal marker-based migration; customized hooks remain untouched.
+
+## What to Tell Your User
+
+Instar’s decision-quality meter now receives real autonomous completion evidence and runs its existing grading cadence automatically. The meter remains observe-only and does not block decisions or send messages.
+
+## Summary of New Capabilities
+
+- Loud detection of wired decision points that cannot actually be graded.
+- Real autonomous completion pass/fail evidence on the existing quality read surface.
+- Enabled bounded hourly grading cadence.
+
+## Evidence
+
+- Unit: census class ratchet, negative synthetic enrollment, realcheck adapter, hook payload, job template, and stop-hook migration.
+- Integration/E2E: a real AgentServer run registers a run, records a completion decision, posts run-end with a passing real check, and observes a non-zero right-grade count through `GET /decision-quality`.
+- Build, lint, integration, E2E-alive, and repository suite evidence is recorded in the PR.

package/upgrades/side-effects/decision-quality-grading.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Decision-quality grading operationalization
+
+**Version / slug:** `decision-quality-grading`
+**Date:** `2026-07-21`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `decision_quality_review`
+
+## Summary of the change
+
+Extends the existing decision-quality census, rule registry, realcheck annotator, outcome chokepoint, run-end route, autonomous stop hook, and built-in grading job. It adds no second grading engine. The developer-process invariant refuses a malformed enrollment in CI; runtime grading remains observe-only.
+
+## Decision-point inventory
+
+- `provenance census enrollment` — modify — a wired point must have a registered grader or explicit measurement-only/exempt posture.
+- `/autonomous/:topic/run-end` — pass-through — carries server-bounded realcheck evidence into the existing annotator; it does not decide whether a run may stop.
+- `llm-decision-grading` cadence — modify — enables the existing bounded deterministic pass.
+
+## 1. Over-block
+
+The only new block is a developer-process ratchet. A legitimate new wired point would be blocked if its author omits both its real evidence rule and its explicit measurement-only/exempt posture. That is the intended malformed state. Runtime decisions and run shutdown are never blocked by grading.
+
+## 2. Under-block
+
+An explicitly measurement-only point remains ungraded by design, and a dishonest explanation can still pass the length floor. Review owns the semantic quality of that declaration. The runtime contradiction list catches structural drift, not fabricated evidence semantics.
+
+## 3. Level-of-abstraction fit
+
+The invariant lives beside `PROVENANCE_COVERAGE` and `RULE_REGISTRY`, the two sources whose contradiction it detects. Outcome evidence uses `AutonomousRealCheckAnnotator` and `annotateDecisionOutcome`; no parallel store, registry, adapter, or grading loop was added.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — runtime grading is an observe-only signal and has no block/allow surface.
+
+The CI ratchet is a deterministic structural invariant over source declarations, not a semantic judgment about user or agent intent. The run-end annotation failure direction is named and non-blocking.
+
+## 4b. Judgment-point check
+
+No static heuristic was added at a competing-signals decision point. Pass/fail comes from the already-authoritative deterministic real check; this change only transports and records that outcome.
+
+## 5. Interactions
+
+- Shadowing: the annotation runs before terminal marking but catches every failure, so it cannot shadow run lifecycle.
+- Double-fire: the run record persists the first accepted realcheck outcome per correlation id. Same-outcome replay is named duplicate; opposite replay is named conflict and cannot overwrite the grade. Evidence time derives from the persisted correlation timestamp, so identical replay is byte-stable.
+- Races: before annotation, the route durably reserves the first outcome for the correlation. Reservation failure skips grading with `observation-persist-error` and cannot block terminal marking. A successful grade whose receipt-finalization write fails stays opposite-replay-safe via the reservation and is safely retried by same-outcome delivery.
+- Feedback loops: grades are read-only observations and do not change model routing or gate decisions.
+
+## 6. External surfaces
+
+`GET /decision-quality` gains `censusDebt.wiredButNoGrader`; the run-end response gains `realcheckAnnotation`. The built-in grading job is enabled on fresh scaffold installs. No operator action, outbound message, URL, or external service is added.
+
+The original converged meter spec required the cost-bearing Haiku wrapper to ship `enabled:false`. The newer operator goal-4 instruction explicitly requires enabling this scaffold under the Tier-1 lane. This artifact records that authority/posture change rather than claiming the older text already authorized it. Existing operator-edited installed jobs retain their current enabled state because the built-in-job migrator preserves explicit state; fresh scaffolds receive `enabled:true`.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Machine-local by design, proxied-on-read through the existing `GET /decision-quality?scope=pool` composition. Decisions and their realcheck evidence are written on the machine that ran the autonomous session. The job is `perMachineIndependent`; it emits no user-facing notice, creates no topic-keyed durable state of its own, and generates no URLs.
+
+## 8. Rollback cost
+
+Revert and ship a patch. The schema is unchanged. Existing grade rows remain valid and idempotent; disabling the scaffold job stops future cadence without state repair. The stop-hook migration replaces only stock-recognized copies and preserves customized hooks.
+
+## Conclusion
+
+The change closes the operational gap while preserving the existing authority boundaries and data model. Phase B owns reviewed rules and owners for the four explicitly measurement-only points: messaging tone, correction class review, completion claim verification, and feedback readiness. <!-- tracked: goal-4-phase-b -->
+
+## Second-pass review
+
+**Reviewer:** `decision_quality_review`
+**Independent read of the artifact:** concur
+
+Concur with the review. The reservation-first state machine preserves terminal lifecycle under write failure, blocks conflicting replay, permits safe same-outcome retry, and keeps grading observe-only. The review’s final non-blocking hardening note was also applied: only a `met:true` observation may reserve an outcome.
+
+## Evidence pointers
+
+- `tests/unit/provenance-coverage-ratchet.test.ts`
+- `tests/unit/autonomous-stop-hook-realcheck.test.ts`
+- `tests/e2e/decision-quality-alive.test.ts`
+
+## Class-Closure Declaration (display-only mirror)
+
+This change enables an existing self-triggered hourly job. `defectClass: unbounded-self-action`; `closure: guard`; `guardEvidence`: the hourly cron is one trigger per period and `runDecisionGradingPass` is bounded by the configured per-pass maximum, uses durable cursors, and is idempotent. The existing job-template ratchet pins the cadence and endpoint-only body; the controller performs no recursive dispatch, retry loop, notification, or LLM call. The general forcing guard is `tests/unit/self-action-convergence.test.ts`; no new autonomous emitter was introduced for registry enrollment.

package/upgrades/side-effects/feature-maturation-plan-visibility.md

@@ -0,0 +1,84 @@
+# Side-Effects Review — Feature maturation plan visibility
+
+**Version / slug:** `feature-maturation-plan-visibility`
+**Date:** `2026-07-21`
+**Author:** `Instar-codey`
+**Second-pass reviewer:** `maturation_second_pass`
+
+## Summary of the change
+
+This strengthens the existing Maturation Path registry article, adds a pure Markdown structure detector, emits a WARN-only diagnostic from the existing convergence tag writer, and delivers both files through PostUpdateMigrator with hash-based customization detection and durable replacement.
+
+## Decision-point inventory
+
+- `findMaturationPlanGaps` — add — pure structural signal with no blocking authority.
+- convergence tag writer — modify — reports the signal but retains exit status and stamping behavior.
+- migration stock/custom classification — add — deterministic closed-world content-hash invariant protecting user customizations.
+
+## 1. Over-block
+
+No runtime block exists. A valid non-canonical plan can warn, but v1 still stamps convergence. The canonical accepted form is documented and tested.
+
+## 2. Under-block
+
+A syntactically complete but poor plan is not rejected. This is intentional: structural parsing is a cheap signal; the lessons-aware reviewer holds semantic authority.
+
+## 3. Level-of-abstraction fit
+
+The validator sits beside the existing `findDecisionPointGaps` convergence seam. The standard is updated in place. Runtime graduation remains owned by FeatureRolloutReconciler and InitiativeTracker; no parallel engine exists.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+
+The Markdown parser only reports missing deterministic structure. It cannot veto convergence or judge plan quality.
+
+## 4b. Judgment-point check
+
+No new heuristic at a competing-signals decision point. Stock-file hash membership and structural field presence are closed-world invariants. Semantic maturation quality remains a reviewer judgment.
+
+## 5. Interactions
+
+- **Shadowing:** the warning runs after existing open-question and decision-point hard gates, and before tag writing. It cannot shadow either gate.
+- **Double-fire:** one invocation emits at most one stable warning line.
+- **Races:** migration writes use unique sibling temps, exclusive create, file and directory sync, and same-filesystem rename.
+- **Feedback loops:** none in v1; no scheduler or initiative cadence is added.
+
+## 6. External surfaces
+
+Developers may see a new stderr warning during spec convergence. No messages, routes, external APIs, persistent runtime records, or operator actions are added.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Unified: the detector, tag writer, and standard are git/package artifacts delivered identically to each machine. V1 emits no notice, durable rollout state, or URL. Existing customized targets remain local by user choice and are reported untouched.
+
+## 8. Rollback cost
+
+Revert and ship a patch. The warning creates no data. Installed stock files retain durable pre-migration backups; customized files are never modified.
+
+## Conclusion
+
+The change is bounded to warning visibility, extends the correct existing owners, and preserves semantic authority. The main risks—parser false positives and migration corruption—are non-blocking or covered by adversarial and injected-failure tests.
+
+## Second-pass review (if required)
+
+**Reviewer:** maturation_second_pass
+**Independent read of the artifact:** concur
+
+Concur with the review — the implementation now preserves WARN-only signal authority, exact gate classification, customization-safe durable migration parity, and the v1-only boundary with all 26 targeted tests passing.
+
+## Evidence pointers
+
+- `tests/unit/feature-maturation-plan-gate.test.ts`
+- `tests/unit/write-convergence-tag-maturation-plan.test.ts`
+- `tests/unit/PostUpdateMigrator-feature-maturation.test.ts`
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect — not applicable. This is a new WARN-stage guard, not a defect repair or self-triggered controller.