instar 1.3.10 → 1.3.12

package/upgrades/side-effects/feedback-factory-transitions.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — feedback-factory lifecycle state machine (Phase 1, increment 3)
+
+**Slug:** `feedback-factory-transitions`
+**Date:** `2026-05-26`
+**Author:** Echo
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The pure lifecycle decision logic — `V2_STATES`/`V2_TRANSITIONS`/`TRANSITION_GATES` constants, `can_transition` (:1045, scar a's evidence gate + the state machine + chronic circuit-breaker), and `detect_cycling` (:1139). The DB-coupled drivers (`cmd_transition`, the version-anchored half of `can_transition_to_verified`) are later increments.
+
+## Summary of the change
+
+Byte-exact port of the above from `the-portal/.claude/scripts/feedback-processor.py` to `src/feedback-factory/processor/transitions.ts`. Pure functions, no I/O. **Not wired into any route/job yet** — no behavioral change. Adds the transitions parity harness + Tier-1 unit tests.
+
+This is the heart of scar (a): the evidence gate (terminal transitions to `wontfix`/`closed`/`chronic_escalated` require ≥20-char justification — unified with the `clusters.ts` API hard gate) and the chronic circuit-breaker (auto-block `chronic` at `recurrenceCount ≥ 3`, forcing `chronic_escalated`).
+
+## Equivalence verification
+
+- **33/33 cases match the reference Python** — both the `allowed` decision AND the exact `reason` string (the reasons interpolate Python's `sorted(set)` list-repr; the port reproduces it via `pyListRepr` so even the diagnostic text is byte-identical), plus all `detect_cycling` results.
+- The check ORDER is preserved exactly (invalid target → unknown current → illegal transition → evidence gate → hard gate → chronic breaker), so the first-failing reason matches the reference for every case.
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure deterministic functions, no I/O, no global state, not imported by any runtime path. Cannot affect existing behavior. The constants are exported read-only.
+2. **Level-of-abstraction fit** — Processor-logic layer, alongside the fingerprint + similarity ports. Correct home. The state machine is data (constants) + a pure validator — no DB coupling, which is why it ports cleanly now (the DB-coupled verification driver waits for the data layer).
+3. **Signal vs Authority** — `can_transition` is the structural evidence gate (scar a): it *enforces* that terminal transitions carry evidence, mirroring the `clusters.ts` API hard gate. This is legitimate authority that already exists in the reference (not new authority introduced by the port). The processor still never force-closes; it validates.
+4. **Interactions** — None. New isolated module; nothing imports it yet. Parity scripts are LOCAL-only (external reference path via `PORTAL_PROCESSOR`).
+5. **Rollback cost** — Trivial: delete the module + tests + scripts.
+6. **Migration parity** — N/A. New internal library code; touches no agent-installed file.
+7. **Failure modes** — (a) Port diverges from reference → caught by the parity harness (33/33, decisions+reasons+cycling) + unit assertions in CI. (b) A new lifecycle state added to the reference but not the port → the "every transition target is a known state" unit test + future parity runs catch drift; Dawn's review is the human backstop. (c) Reason-string repr divergence → parity asserts reasons byte-for-byte.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/transitions.test.ts` — state legality, terminal states, evidence gate (both sides of 20 chars), dispatch hard gate, chronic circuit-breaker (recurrence 2 vs 3), cycling detection, constants integrity. 12 tests.
+- Parity (local gate, evidence): `scripts/feedback-factory/transitions-parity.mjs` → **33/33** decisions + reasons + cycling identical to the reference Python.
+- No integration/E2E this increment: not yet wired to a route/job; those tiers attach with the clustering/transition driver. Reasoned decision, documented.

package/upgrades/side-effects/mentor-playbook-observability.md

@@ -0,0 +1,62 @@
+# Side-Effects Review — Playbook promotion (non-Echo gate) + observability (§19.5)
+
+**Spec:** `docs/specs/FRAMEWORK-ONBOARDING-MENTOR-SPEC.md` (converged 5 iters, approved by Justin)
+**Change:** Two additions to the FrameworkIssueLedger (§19.1) + two read-only-ish routes:
+`promotePlaybook()` (none→candidate→extracted→superseded, with a **non-Echo attestation gate** on
+candidate→extracted, §13.6) and `observability()` (bucket-distribution + leak/probable-loop/extracted
+counts, §15). New routes `POST /framework-issues/:id/promote` and `GET /framework-issues/observability`.
+**Files:** `src/monitoring/FrameworkIssueLedger.ts`, `src/server/routes.ts`,
+`src/server/CapabilityIndex.ts`, `tests/unit/FrameworkIssueLedger.test.ts`,
+`tests/integration/framework-issues-routes.test.ts`, `upgrades/NEXT.md`.
+
+## Principle check (Phase 1)
+
+Does this involve a decision point that gates info flow / blocks actions / constrains behavior?
+**Yes — and it's a structural authority boundary, the good kind.** `promotePlaybook` enforces that
+the proposing agent (Echo) cannot promote its own lesson into the reusable playbook — candidate→
+extracted requires a non-Echo attestation. This is a *gate on the agent itself*, not authority over
+the user's world; it can only refuse a promotion (signal/anti-gaming), never block another component.
+`observability` is pure read-only telemetry.
+
+## The seven questions
+
+1. **Over-block.** `promotePlaybook` refuses candidate→extracted by Echo (or an empty attester) —
+   intentional (§13.6). Other transitions (none→candidate, →superseded) are unrestricted. No
+   legitimate promotion by a non-Echo actor is blocked.
+2. **Under-block.** The attester is a free-string compared case-insensitively against `echo`. A
+   determined Echo could pass a different literal — but the route is operator/human-driven and the
+   recorded `promoted_by` makes any promotion auditable (a spoofed attester is visible). The gate is
+   the structural deterrent + the audit trail is the backstop; matches the `difficultyAttestedBy`
+   pattern from §7.3.
+3. **Level-of-abstraction fit.** Both methods live on the ledger that owns the data; the routes are
+   thin pass-throughs. `observability` reuses indexed columns (bucket, playbook_status, signature).
+   Correct layer.
+4. **Signal vs authority.** Compliant. `observability` is signal. `promotePlaybook`'s only authority
+   is to *refuse* a self-promotion (an anti-gaming guard on the proposer) — it never gates messaging,
+   sessions, or other components. Promotion to `extracted` is reserved for a non-Echo actor (§13.6).
+5. **Interactions.** Adds a `promoted_by` column via an idempotent `ALTER TABLE … ADD COLUMN`
+   (duplicate-column errors swallowed in init) so ledgers created by §19.1/§19.2 (v1.3.5–1.3.9)
+   migrate forward on first boot. No interaction with the capture funnel or Stage-A paths.
+6. **External surfaces.** Two routes behind Bearer auth, added to the existing `frameworkIssues`
+   CapabilityIndex entry (no new prefix → no discoverability gap). No template/config change.
+7. **Rollback cost.** Low. Revert removes the routes/methods; the `promoted_by` column is harmless if
+   left. No data migration beyond the additive column.
+
+## Phase 5 — second-pass
+
+**Not required.** The promotion gate is a single pure attestation check (`promotedBy != echo`),
+unit-tested on both sides (Echo refused; non-Echo allowed + recorded); `observability` is read-only.
+No session lifecycle, no spawning, no blocking of another component, nothing named
+sentinel/guard/watchdog. The decision-bearing live loop (§19.4) already carried its dedicated
+second-pass.
+
+## Testing
+
+- Tier 1 (unit, +6): promotePlaybook none→candidate by any actor; **candidate→extracted REFUSED for
+  Echo / empty attester**; allowed + `promoted_by` recorded for a non-Echo actor; invalid-status
+  guard; unknown-issue null; observability bucket-distribution + leak/extracted counts.
+- Tier 2 (integration, +5): observability 503/200; promote rejects Echo (400), allows non-Echo (200),
+  404 unknown.
+- route-completeness + capabilities-discoverability gates pass (new catch uses `instanceof`; new
+  routes fall under the classified `/framework-issues` prefix).
+- Affected push-config suite green vs canonical main; route docs-coverage 56% ≥ 55% floor.