instar 1.3.1219 → 1.3.1221

package/upgrades/side-effects/file-path-advisory-default.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — File-path feedback advisory by default
+
+**Version / slug:** `file-path-advisory-default`
+**Date:** `2026-09-04`
+**Author:** `echo`
+**Second-pass reviewer:** `Codex /root/rule2_side_effects_review`
+
+## Summary of the change
+
+`MessagingToneGate` changes `B2_FILE_PATH` from blocking to advisory for every install, independent of the broader fleet-dark advisory-migration flag. `PostUpdateMigrator` replaces the prior CLAUDE.md advisory section idempotently and mirrors it into Codex/Gemini shadows. The Telegram route describes evidence recording honestly when the recorder is unavailable. Focused tests cover runtime disposition and override, fresh-install awareness, migration replacement, idempotency, shadow parity, and positioning.
+
+## Decision-point inventory
+
+- `MessagingToneGate.RULE_DISPOSITIONS.B2_FILE_PATH` — modified — a contextual file-path judgment no longer has terminal blocking authority.
+- `PostUpdateMigrator.migrateClaudeMd` — modified — existing installed awareness text is replaced or added idempotently.
+- `PostUpdateMigrator.migrateFrameworkShadowCapabilities` — modified — the replacement section is copied into Codex/Gemini shadows after CLAUDE.md migration.
+- `POST /telegram/reply` advisory instructions — modified — recording claims depend on a live decision reference and recorder.
+
+## 1. Over-block
+
+The change removes the known over-block: a legitimate path needed to open, edit, or locate an artifact can no longer be an absolute wall. The first advisory response still withholds the send until the agent revises or supplies a reasoned override; that bounded nudge is intentional and preserves the opportunity to improve confusing prose.
+
+## 2. Under-block
+
+An agent can override a genuinely confusing raw path with a poor reason. That is accepted because file-path clarity is a contextual writing judgment, not a safety invariant. Credential exposure remains independently non-overridable, and paths do not bypass that guard.
+
+## 3. Level-of-abstraction fit
+
+This is at the existing authority layer: the LLM tone gate may still detect and cite `B2_FILE_PATH`, while the disposition map controls whether that contextual judgment is a wall or a nudge. No parallel detector or new decision path is introduced.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change removes brittle terminal authority from an existing smart-gate verdict.
+
+The change does not create a detector. It changes the disposition of the existing contextual verdict so a path-shaped observation cannot itself become terminal authority. The author retains final authority through the existing reasoned advisory override seam. Hard credential invariants remain separate.
+
+## 4b. Judgment-point check
+
+No new static heuristic is added at a competing-signals decision point. The static disposition is a floor preventing a contextual prose judgment from becoming an absolute blocker; the existing LLM authority still decides whether to issue the nudge.
+
+## 5. Interactions
+
+- **Shadowing:** Credential checks still execute independently and remain non-overridable; the B2 disposition cannot shadow them. The framework-shadow copier runs after CLAUDE.md migration and now searches for the replacement marker, preventing the migrated section from disappearing on Codex/Gemini.
+- **Double-fire:** The existing advisory protocol is reused, so no second sender or parallel retry path exists.
+- **Races:** The runtime map is immutable and process-local; migration is content-sniffed and idempotent.
+- **Feedback loops:** Where decision recording is available, compliance and dissent continue feeding the existing quality meter. Where unavailable, B2 still remains overridable, avoiding a false hard wall.
+
+## 6. External surfaces
+
+Agents on fresh and upgraded installs see revised guidance in CLAUDE.md and framework shadows. Telegram and other tone-gated outbound callers receive the existing advisory protocol; the explanation now says when decision-quality evidence cannot be recorded. No new operator action, database, URL, or external-service dependency is introduced.
+
+## 6b. Operator-surface quality
+
+No dashboard or operator form surface — not applicable.
+
+## 7. Multi-machine posture
+
+**Replicated:** the behavior ships in source and the awareness text is applied by the normal update migration to CLAUDE.md plus existing Codex/Gemini shadows on each machine. It emits no independent notice, holds no durable per-machine state, and generates no URLs. Topic transfer cannot strand an override because the decision is per-send and the base disposition is identical on every updated machine.
+
+## 8. Rollback cost
+
+A hot-fix can revert the disposition and awareness migration in a later patch. No data migration or agent-state cleanup is required; an update would rewrite the owned awareness section again. During rollback propagation, machines could temporarily differ in whether B2 is a wall, which is visible and bounded to message composition.
+
+## Conclusion
+
+The change is narrower than the broad advisory-migration program and directly implements the operator's September 3 decision. It removes inappropriate blocking authority without weakening credential safety. Focused tests pass; full-suite verification must be repeated after rebasing onto current main.
+
+## Second-pass review
+
+**Reviewer:** `Codex /root/rule2_side_effects_review`
+**Independent read of the artifact:** `concur`. The first pass identified framework-shadow marker drift, an unproven no-recorder override path, misleading recording claims, and incomplete authority/inventory wording. The corrected diff resolves all concerns; the reviewer independently verified the relevant code and the combined 193-test focused evidence.
+
+## Evidence pointers
+
+- Focused suite: 5 files, 193 tests passed on 2026-09-04 after the independent-review corrections.
+- Prior stale-base full suite: 50,956 passed, two failures; both require current-main reconciliation before release.
+
+## Class-Closure Declaration
+
+`defectClass: brittle-keyword-authority`, `closure: guard`, `guardEvidence: {enforcementType: ratchet, citation: tests/unit/tone-gate-advisory-migration.test.ts, howCaught: the test asserts B2_FILE_PATH is advisory even when the broader migration and decision-quality recording are unavailable, so a future return to a hard wall fails the suite}`.

package/upgrades/side-effects/stage-b-evidence-code-binding.md

@@ -0,0 +1,93 @@
+# Side-Effects Review — Stage-B evidence binds to the certified code, not the version number
+
+**Version / slug:** `stage-b-evidence-code-binding`
+**Date:** `2026-09-03`
+**Author:** `Echo`
+**Second-pass reviewer:** `Codex independent reviewer (see below)`
+
+## Summary of the change
+
+The Stage-B publish gate's evidence binding compared the signed canary artifact's `packageVersion` to the current build, which can pass exactly once; publishing froze fleet-wide one release after the gate shipped, and the runtime fleet-activation path carried the same binding, so Stage B would have stayed silently dark on every later release. The change (spec `docs/specs/stage-b-evidence-code-binding.md`, conformance-checked; operator-approved direction, topic 52075, 2026-09-03) binds evidence to the certified code instead: a reviewed manifest (`src/data/stageBCertifiedSet.ts`) partitions the certified roots' transitive relative-import closure into certified (fingerprinted) and excluded-with-written-reason, fail-closed for new members; `verifyShippedStageBEvidence` (`src/core/StageBActivationGate.ts`) verifies shape, signature, thresholds, the REAL behavioral-config binding, and the canonical-digest linkage to that manifest; `scripts/stage-b-certified-fingerprint.mjs` checks source drift at publish (`scripts/verify-codex-stage-b-release-evidence.mjs`) and pre-push (`.husky/pre-push`), and its `--write` refuses to re-stamp old evidence onto changed code.
+
+## Decision-point inventory
+
+- Stage-B publish gate (`verify-codex-stage-b-release-evidence.mjs` + `verifyBundledStageBReleaseEvidence`) — modify — binding predicate corrected from version equality to certified-code fingerprint + canonical digest linkage; blocking authority and fail direction unchanged.
+- Runtime fleet activation (`resolveStageBProductionActivation`, shipped branch) — modify — same corrected binding; machine-LOCAL candidate path untouched.
+- Pre-push hook — add (signal-to-developer) — surfaces drift at push time; publish remains the enforcing gate.
+
+---
+
+## 1. Over-block
+
+A certified-source edit now blocks publishing until a fresh canary — intended, and narrower than today (today EVERYTHING is blocked). A tsc or dependency change does not block (fingerprint covers source bytes, not build output). A stale exclusion (file leaves the closure) fails the check until the manifest is tidied — deliberate, keeps the partition true. If the manifest and evidence ever disagree (digest mismatch), publishing blocks with a named message — the safe direction for a release gate.
+
+## 2. Under-block
+
+A behavior change inside an EXCLUDED closure member (the shared types module, safe executors, tone gate, and 30 others, each with a written reason) does not force a canary — accepted, enumerated in the manifest, and stated in the spec's honest limits. A hand-rolled npm publish that bypasses lifecycle scripts bypasses this gate exactly as it bypasses today's — unchanged exposure, out of scope. The fingerprint has no adversarial value: everything is editable in one PR, same as the verifier it amends; review of the diff remains the defense at that layer.
+
+## 3. Level-of-abstraction fit
+
+The binding is a deterministic invariant at the release-gate layer, exactly where the broken one lived; no new layer, no judgment added. The closure computation and partition live in one tool used by both the publish gate and pre-push, not re-implemented per consumer.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Yes — but the blocking logic is an exact-match deterministic check on an irreversible-release class action (ship/don't-ship), the ruled shape for structure deciding alone. No LLM, no heuristic; the predicate is byte equality against a reviewed manifest. The pre-push arm is a SIGNAL to the developer (publish is the authority).
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point: "did the certified bytes change?" is enumerable and exact.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the fingerprint check runs AFTER the evidence verification inside the publish verifier; a failure of either blocks. The pre-push arm runs before the smoke tier and only when a built gate module exists (fresh clones without dist skip it; publish still enforces).
+- **Double-fire:** none; one tool, two invocation points, both idempotent reads.
+- **Races:** none; all reads of committed files.
+- **Feedback loops:** none.
+- **Migrator/init call sites:** `verifyBundledStageBReleaseEvidence` keeps its signature (version parameter documented unused), so `PostUpdateMigrator` and `init` behave identically except the verdict is now correct on later releases — which flips `releaseEvidenceValid` from a wrong `false` to a true verdict and lets the existing migration set pending activation as designed.
+- **Test override seam:** the documented `shippedEvidence` injection keeps every shape/signature/threshold/config check; the manifest digest linkage applies only to the package-bundled path (every production caller).
+
+---
+
+## 6. External surfaces
+
+- Install base: the next release publishes; fleet machines activate Stage B via the existing migration (pending-activation on restart) instead of staying silently dark — the shipped feature finally behaves as its own release notes said.
+- External systems: none. Persistent state: none new (a src/data module compiled into dist). Timing: none. Operator surface: none.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Replicated by the package**: the manifest and evidence ship in the npm package, identical on every machine; verification is pure and local. No user-facing notices, no durable per-machine state, no URLs.
+
+## 8. Rollback cost
+
+Revert and ship a patch — but note the revert RESTORES the release freeze (the reverted gate rejects every version except 1.3.1219), so a rollback of this change must itself be published by temporarily bypassing the gate or re-binding; recorded here so nobody reverts casually. No data migration, no agent state repair.
+
+## Conclusion
+
+The review moved the design three times: the digest became canonical (order-stable) instead of JSON.stringify; the runtime fleet path was discovered to carry the same freeze and fixed identically; the coverage cut became an enumerated fail-closed partition instead of a silent five-file list, with the rebind tool structurally refusing old-evidence re-stamping. Residue accepted and recorded: excluded utilities can change certified behavior without forcing a canary (per-file reasons in the manifest); publish-path bypass exposure unchanged from today. Clear to ship after the independent second pass and the full test gate.
+
+## Second-pass review (if required)
+
+**Reviewer:** Codex independent reviewer (GPT-5.6, read-only, spec + implemented diff)
+**Independent read of the artifact:** concern → concur over five bounded rounds. Round 1 (spec): eight findings — the --write rebind hole, same-PR mutability, five-file under-coverage, gate-exclusion soundness, the runtime path's identical version freeze, tautological config binding, publish-path TOCTOU, JSON.stringify digest instability — all folded into the design (fail-closed enumerated partition, canonical digest, runtime fix, real config binding, honest-limits section). Round 2 (implemented diff): three findings — silent pre-push skip, single-quote-only import matcher, unpinned override seam — all fixed; widening the matcher surfaced 47 further closure members through dynamic imports, each now excluded with a written reason. Rounds 3–5 tightened the seam pin to any token mention with an exact-path exemption; final verdict: concur.
+
+## Evidence pointers
+
+- `tests/unit/stage-b-evidence-code-binding.test.ts` (19 tests)
+- `tests/unit/StageBActivationGate.test.ts`, `StageBStartupReadiness.test.ts`, `MentorStageBForensics.test.ts`, `codex-stage-b-publish-gate.test.ts` (all green)
+- Live: `node scripts/verify-codex-stage-b-release-evidence.mjs` passes on this tree; `verifyBundledStageBReleaseEvidence("9.9.9999")` returns null.
+
+## Class-Closure Declaration (display-only mirror)
+
+`defectClass: symbol-for-state-verification`ish — the registry id is resolved at commit time; if no existing class fits ("a gate verified a proxy symbol that diverged from the state it stood for"), this ships `closure: guard` citing `tests/unit/stage-b-evidence-code-binding.test.ts` (the version-independence and drift tests fail on any reintroduction of a version-bound or manifest-less path). No self-triggered controller is added or modified — the gate blocks a human-invoked publish; nothing fires on its own.