instar 1.3.896 → 1.3.898

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.

package/upgrades/side-effects/mutual-ssh-autobootstrap.md

@@ -0,0 +1,137 @@
+# Side-Effects Review — Mutual SSH Autobootstrap
+
+**Version / slug:** `mutual-ssh-autobootstrap`  
+**Date:** 2026-07-20
+**Author:** Instar-codey  
+**Second-pass reviewer:** Claude Sonnet clean-door security review (2026-07-21)
+
+## Summary of the change
+
+This build adds Instar-owned SSH client/host identities, leased paired-peer admission,
+a restricted `instar-rpc` ssh2 endpoint, directional proof, bounded health repair,
+dev-dark/dry-run configuration, boot integration, and a scrubbed health route. It
+touches cryptographic admission and mutual-read invariants but grants no shell access.
+
+## Decision-point inventory
+
+- Bootstrap-advert acceptance — added invariant authority: signed-principal caller
+  supplies identity; this validator enforces schema, epoch, expiry, key and private-
+  endpoint bounds.
+- Peer authentication — added invariant authority: exact leased public-key identity.
+- Direction/mutual truth — added invariant authority: current pinned proof exists in
+  both directions or `mutual` is false.
+- Repair escalation — added bounded deterministic policy; host-key mismatch notifies
+  immediately, ordinary failures exhaust four attempts or 120 seconds.
+
+## 1. Over-block
+
+IPv6 private endpoints are not yet admitted by the narrow endpoint validator, so a
+private IPv6-only paired host is reported blocked rather than weakened to a public or
+unverified bind. Loopback is accepted only for the local real-transport fixture and
+never by signed peer advert validation.
+
+## 2. Under-block
+
+The endpoint relies on the exact-pinned ssh2 parser and Node cryptography. Novel
+parser vulnerabilities remain possible; the narrow algorithm/channel surface and
+dependency audit gate reduce but cannot eliminate that risk. The rollout remains
+dry-run-first and fleet-dark.
+
+## 3. Level-of-abstraction fit
+
+The identity, admission, endpoint, verifier, and controller are separate primitives.
+Mesh/pairing supplies authenticated public facts; SSH independently proves possession
+and reachability. The controller produces transport health and does not become a
+parallel routing authority.
+
+## 4. Signal vs authority compliance
+
+Required reference: `docs/signal-vs-authority.md`. Probe outcomes are signals. The
+deterministic blocks are cryptographic, structural, expiry, resource, and public-bind
+security invariants—the explicitly permitted enumerable-authority case. No heuristic
+interprets operator intent or message meaning.
+
+## 4b. Judgment-point check
+
+No competing-signals judgment heuristic is added. Endpoint selection and validity
+operate within finite authenticated candidates; uncertainty produces no proof.
+
+## 5. Interactions
+
+- Dedicated state is disjoint from personal SSH state and AgentRegistry ports.
+- Pairing epoch, observer boot id, and generations are carried end-to-end; stale
+  replay cannot refresh an admission or proof.
+- Authentication and subsystem-open both re-read the admission lease.
+- The scheduler refuses overlapping sweeps; its concurrency counter and pair breaker
+  prevent unbounded work, while successful proof settles the episode.
+
+## 6. External surfaces
+
+The new SSH listener is restricted to loopback/private/Tailscale-style addresses and
+exposes no general command surface. The read-only health route omits key bodies and
+raw addresses. No operator action is introduced; dry-run/live selection is existing
+configuration policy, not a new API-only approval.
+
+## 6b. Operator-surface quality
+
+The Machines dashboard adds a compact SSH-enrollment card. The read surface uses
+plain enrollment states (`paired`, `ssh-bootstrap`, `ssh-bootstrap-blocked`,
+`ssh-proving`, `ready`) and contains no raw keys or addresses.
+
+1. **Leads with the primary action:** this is status-only, so current readiness and
+   enrollment state are the first content; there is no hidden operator action.
+2. **Zero raw internals as primary content:** the card shows plain state, direction
+   counts, and human-readable blocked reasons; keys, fingerprints, boot ids, epochs,
+   and addresses are omitted.
+3. **Destructive actions de-emphasized:** no destructive action is exposed.
+4. **Plain language + phone width:** the card reuses the responsive Machines grid,
+   short labels, and wrapping reason text; it introduces no table or horizontal
+   overflow at phone width.
+
+## 7. Multi-machine posture
+
+Machine private keys, host keys, admission leases, and endpoint truth are
+**machine-local BY DESIGN** because they are physical credentials and reachability.
+Public adverts travel over authenticated Mesh RPC; signed directional proofs replicate
+through the coherence journal and are revalidated on receipt. The pool health contract
+is **proxied-on-read**. This slice emits no user-facing notice directly and generates
+no URL. The fleet-uniform coherence manifest now also covers the effective Mutual SSH
+dev-gate plus dry-run value, so a half-enabled pool raises the existing skew alarm
+instead of silently presenting asymmetric readiness.
+
+## 8. Rollback cost
+
+Disable the dev gate, drain/close the endpoint, and revert the runtime files. Dedicated
+keys and scrubbed audit metadata may remain inert; no personal SSH repair or user-state
+migration is required. Removing the state directory later is optional cleanup.
+
+## Conclusion
+
+The implementation preserves the central security boundary: paired-machine identity
+is prerequisite, every SSH direction proves itself, and failure stays honestly
+non-mutual. Fleet-dark/dry-run rollout contains exposure. Independent review completed
+before commit because this touches admission, lifecycle, and a self-action controller.
+
+## Second-pass review
+
+**Reviewer:** Claude Sonnet, clean-door read-only review
+**Independent read:** No critical findings. Two major findings were resolved before
+commit: host rotation now carries a separately verified MachineAuth transition
+signature, and malformed proof timestamps fail closed before freshness checks. Full
+dispositions are recorded in `docs/review/mutual-ssh-phase1-security-review.md`.
+
+## Class-Closure Declaration
+
+This closes the `Symmetric Transport Proof` class from the approved spec: the real
+transport fixture and mutuality unit test fail any future implementation that claims
+mutual from one direction. The self-action loop is bounded by four attempts, 120
+seconds, concurrency 4, a three-episode breaker, and a settled proof state; the
+self-action convergence ratchet is part of final ceremony evidence.
+
+- `defectClass`: `unbounded-self-action`
+- `closure`: `guard`
+- `guardEvidence`: `{ enforcementType: ratchet, citation:
+  tests/unit/self-action-convergence.test.ts, howCaught: the registered mutual SSH
+  repair model is driven under permanent path rejection and proves its four-attempt,
+  two-minute episode plus concurrency ceiling and fifteen-minute post-breaker rate
+  floor prevent retry accumulation or acceleration }`