instar 1.3.192 → 1.3.194

package/upgrades/side-effects/autonomous-operation-judgment-and-approval-as-data.md

@@ -0,0 +1,98 @@
+# Side-Effects Review — Autonomous Operation: Stop Reason Is the Work + Constitutional Traceability (Stage 1)
+
+**Version / slug:** `autonomous-operation-judgment-and-approval-as-data`
+**Date:** `2026-06-01`
+**Author:** `echo`
+**Second-pass reviewer:** `independent lessons-aware convergence review (2 passes → converged)`
+**Spec:** `docs/specs/AUTONOMOUS-OPERATION-JUDGMENT-AND-APPROVAL-AS-DATA-SPEC.md` (approved: true)
+
+## Summary of the change
+
+Stage 1 of the autonomy-governance spec. Ships TWO constitutional standards + their
+real enforcement; Approval-as-Data (Part B / ApprovalLedger) is Phase 2 and is NOT
+in this change.
+
+1. **P13 "The Stop Reason Is the Work"** (constitution: `STANDARDS-REGISTRY.md`
+   Substrate article + `INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md` P13). An autonomous
+   stop for "I need a judgment call" or "this needs real engineering" is a work item,
+   not an endpoint. PRIMARY enforcement: `CompletionEvaluator.evaluateStopRationale`
+   (a fail-open LLM guard) exposed at `POST /autonomous/evaluate-stop` and consulted
+   by `autonomous-stop-hook.sh` at both stop-approve points before permitting a stop.
+   SECONDARY backstop: `B18_AUTONOMY_STOP` in `MessagingToneGate` (sibling to
+   B15/B16/B17, precedence `B15 > B16 > B17 > B18`).
+2. **Constitutional Traceability "No Unconstitutional Work"** (constitution:
+   `STANDARDS-REGISTRY.md` Building article). Every spec must trace to a constitutional
+   standard with an indisputable fit. Commit-time STRUCTURAL gate (`instar-dev-precommit.js`
+   Step 7.6): a staged spec's `parent-principle` must resolve to a real registry
+   article. Review-time QUALITATIVE gate: `StandardsConformanceReviewer.judgeFit` →
+   `fit`/`weak`/`none`, returned by `POST /spec/conformance-check` as `report.fit`.
+
+Behavior is **build+test only**: nothing is activated in production; no session-pool
+stage, lease, or config is flipped.
+
+## Decision-point inventory
+
+- `evaluateStopRationale` STOP_OK vs STOP_BLOCKED (LLM judgment; fail-OPEN to allow on
+  error/ambiguity — a secondary guard must never trap a genuine completion).
+- `judgeFit` fit/weak/none (structural parent-resolution → `none` block; LLM qualitative
+  → fit/weak/none; fail-OPEN to `fit` when degraded).
+- B18 block/pass (LLM; favors false-negatives).
+
+## 1. Over-block risk
+The completion evaluator could trap a legitimately-finished run; B18 could hold a
+genuine completion message. Both favor false-negatives (permit when uncertain). The
+evaluator only re-injects when the stop *classifies* as judgment/engineering AND no
+artifact/derived-standard/operator-residual is shown. Tested: STOP_OK/empty/error →
+stopAllowed:true.
+
+## 2. Under-block risk
+A silent stop emitting no message evades B18 — which is exactly why the PRIMARY surface
+is the completion evaluator (the stop-hook), not the message gate. The conformance gate
+could pass a hand-wave parent — mitigated by judging fit with a full-context reviewer,
+not a string match.
+
+## 3. Level-of-abstraction fit
+Enforcement sits at the stop decision (the structural Stop-hook event) and the commit
+boundary (pre-commit), not buried in prompt prose — the strongest available surfaces.
+
+## 4. Signal vs Authority
+Arithmetic/structural checks (parent-resolution string match) are signals/preconditions;
+the LLM conformance reviewer is the authority for the qualitative fit. No brittle
+deterministic check acquires blocking authority over the *qualitative* judgment.
+
+## 5. External surfaces
+Adds `POST /autonomous/evaluate-stop` (thin wrapper over the evaluator; 503 when absent)
+and a `fit` field on `POST /spec/conformance-check`. No new outbound external calls.
+Both routes classified INTERNAL/build-time.
+
+## 6. Interactions with existing primitives
+B18 de-conflicted from B15 via citation precedence `B15 > B16 > B17 > B18`. The
+completion-evaluator P13 guard EXTENDS (does not replace) the existing
+`/autonomous/evaluate-completion` flow — it only adds a check before an *approve*. The
+conformance fit composes with the existing trace/approved/eli16 ship-gate checks.
+`judgeFit` reuses the existing reviewer + registry parser. The new Constitutional
+Traceability article was placed in the **Building** family (the registry parser
+`STANDARDS_FAMILY_RE` only recognizes Root/Substrate/Building/Shipping/Interaction — a
+Fractal placement would not have parsed; caught by unit test).
+
+## 7. Rollback cost
+All additive + default-safe. B18 disable = remove from `VALID_RULES` (fail-open). The
+stop-hook P13 guard fails-open (server down / 503 / missing field → permit). The
+conformance fit fails-open to `fit` when degraded. Step 7.6 fails-open if the registry
+is unreadable. No production state is changed by this commit.
+
+## Migration parity
+- P13 + Constitutional Traceability registry/principles text reach existing agents via
+  the normal dist update (pure docs); the conformance gate + completion evaluator are
+  shipped code.
+- The `autonomous-stop-hook.sh` change reaches existing agents via
+  `PostUpdateMigrator` (`upgrade()` marker bumped to `p13_stop_allowed`,
+  customization-safe, idempotent).
+
+## Tests
+105 green across 3 tiers: unit (`CompletionEvaluator`, `standards-conformance-gate`,
+`messaging-tone-gate-b18`), integration (`standards-conformance-gate` fit,
+`autonomous-evaluate-stop`), e2e (`standards-conformance-gate-lifecycle` fit-alive).
+`tsc --noEmit` clean. B15/B16/MessagingToneGate regression-green. Test-writing caught
+two real bugs (the Fractal-family parse exclusion above; the B18 response-format
+enumeration omission at MessagingToneGate response-format line).

package/upgrades/side-effects/tiered-dev-awareness-stepCD.md

@@ -0,0 +1,84 @@
+# Side-Effects Review — Tiered-dev awareness + migration parity (Steps C + D)
+
+**Slug:** `tiered-dev-awareness-stepCD`
+**Date:** 2026-06-01
+**Author:** echo
+**Spec:** `docs/specs/tiered-dev-awareness-stepCD-spec.md`
+**Project:** Steps C + D (final) of the Tiered Development Process
+
+## Summary of the change
+
+Makes the instar-*developing* agent **aware** of the tier system shipped in Step A (#666) —
+the gate's size+risk tier SIGNAL, the agent's tier DECLARATION in the trace, the Tier-1
+light path (ELI16 + side-effects, no converged spec), the Tier-1 auto-merge policy, and the
+`belowFloor` decision audit — and records the **migration-parity** analysis closing the
+project. Documentation-only; no runtime code, no gate/classifier/trace-writer change.
+
+**Files changed (in-scope):**
+- `skills/instar-dev/SKILL.md` — adds one focused **"Tiered development (tier signal → you
+  decide → audited)"** section before "What this skill explicitly does NOT do". It states:
+  the gate prints `suggestedTier` (size + risk floor, from `scripts/lib/classify-tier.mjs`)
+  but the agent declares the tier (`write-trace.mjs --tier <1|2|3> --tier-reasoning ...`,
+  `--eli16-path`/`--side-effects-path` for Tier-1); Tier-1 requirement set (ELI16 +
+  side-effects, no pre-approved converged spec) vs Tier-2+ (the full chain); no-declared-tier
+  → Tier-2 (back-compat); the Tier-1 auto-merge policy (clean Tier-1 on green CI + operator
+  spot-check); the audit (`.instar/instar-dev-decisions.jsonl`, the loud `belowFloor`
+  override). Cross-links **The Body and the Mind**. 9 added lines (Tier-1 by the very
+  classifier it documents).
+
+**Files changed (not in-scope for the commit gate):**
+- `docs/STANDARDS-REGISTRY.md` — adds a concise **Tiered Development** standard in the
+  **Building — engineering discipline** family (house format: Rule / Derives from / In
+  practice / Earned from / Traces to the goal / Applied through), framed as deriving from
+  **The Body and the Mind** (the gate informs, the agent decides, the decision is audited;
+  formality scales with size AND risk).
+- `docs/specs/tiered-dev-awareness-stepCD-spec.md` + `.eli16.md` — the design record.
+- `upgrades/next/tiered-dev-awareness-stepCD.md` — the release fragment.
+
+## The seven side-effects questions
+
+1. **Over-block** — N/A. No filter, gate, or block is added or changed. This is prose.
+2. **Under-block** — N/A. No detection logic. The Step-A audit's honest blind spot
+   (heuristic-evasion is not flagged) is unchanged and already documented in the Step-A spec.
+3. **Level-of-abstraction fit** — Correct layer. Awareness for the *developing* agent
+   belongs in its skill (`/instar-dev`) and the constitution it is governed by, not in the
+   end-agent CLAUDE.md template (a customer bot never runs the instar-dev gate). Confirmed
+   against code (see Migration parity).
+4. **Signal vs authority compliance** — Compliant, and the documented system *is* the
+   canonical instance: the gate informs (signal), the agent decides (authority), the
+   decision is audited. The docs add no authority of their own.
+5. **Interactions** — None. The SKILL.md section sits beside the existing phases; it does
+   not change any phase or the gate's behavior. The constitution entry derives from an
+   existing standard (The Body and the Mind) whose "Applied through" already names the
+   tier-classifier, so the cross-link is consistent both directions — no contradiction.
+6. **External surfaces** — None visible to end users, other agents, or other systems. No
+   runtime, no API, no timing or conversation-state dependency. Dev-facing docs only.
+7. **Rollback cost** — Trivial. Revert two documentation edits + the artifacts. No deployed
+   state to repair, no migration to unwind.
+
+## Migration parity
+
+**None needed — verified against code.** This is dev-tooling, not an agent-installed file.
+
+- **`package.json` `files[]`** ships only `.claude/skills/{setup-wizard,secret-setup,autonomous,build}`.
+  The top-level `skills/` directory (home of `skills/instar-dev/SKILL.md`) is **not** in
+  `files[]`, so it is never published to npm or landed in an end-agent home.
+- **`installBuiltinSkills()`** (`src/commands/init.ts`) installs a fixed end-agent allowlist
+  (`evolve`, `learn`, `gaps`, `commit-action`, `feedback`, `triage-findings`, `reflect`,
+  `coherence-audit`, `degradation-digest`, `state-integrity-check`, `memory-hygiene`,
+  `guardian-pulse`, `session-continuity-check`, `git-sync`, `rollback-from-artifact`).
+  `instar-dev` and `spec-converge` are **not** in it.
+- **`generateClaudeMd()`** (`src/scaffold/templates.ts`) is **untouched** and the tiered
+  process is absent from it today. The Agent-Awareness Standard it serves governs *end-agent*
+  capabilities; the instar-dev commit gate is not one, so it correctly stays out.
+
+Therefore **no `PostUpdateMigrator` / `migrateClaudeMd` change is required** — every changed
+file is dev-repo-only (skill, constitution doc, spec) or a release artifact, and no
+agent-installed file is touched. (Mirrors Step B's `/spec-converge` migration-parity
+conclusion.)
+
+## Tests / lint
+
+`npx tsc --noEmit` exit 0 (no TS changed); `npm run lint` green. No runtime behavior changed,
+so no new unit/integration/E2E tests — the SKILL.md section was verified for accuracy against
+the live gate (`scripts/instar-dev-precommit.js` Steps 3.5/4.5/4.6 + `classify-tier.mjs`).