instar 1.2.43 → 1.2.45

package/upgrades/side-effects/build-methodology-bundle.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — /build Methodology Bundle
+
+**Source:** Cherry-picks from GSD-Instar spike (gsd-planner + gsd-executor methodology)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+None — these are prompt-skill methodology sections, not gates. They add steps the agent runs, not blocks. The Phase 0.5 "quality gate" (must-haves.md exists before Phase 1) is a soft self-check inside the skill, not an external block.
+
+## 2. Under-block
+The methodology is advisory within /build. An agent could skip Phase 0.5. Enforcement of the spirit lives elsewhere (e2e-pairing pre-commit gate, /verify-claim, response-review). This bundle imports the DISCIPLINE; the structural gates are separate cherry-picks.
+
+## 3. Level-of-abstraction fit
+All four changes are content edits to the /build SKILL.md — the natural home for build methodology. The defense-in-depth doc lives in docs/patterns/ alongside other pattern docs. The migration follows the existing migrateSkillPortHardcoding content-sniff pattern.
+
+## 4. Signal-vs-authority compliance
+Compatible. Phase 0.5 must-haves PRODUCE the verification signals that Phase 3 (authority: the agent + reviewers) acts on. STRIDE mitigations bind to tests (the authority). The defense-in-depth doc explicitly reconciles itself with signal-vs-authority. No brittle filter is given blocking authority.
+
+## 5. Cross-feature interactions
+- Phase 0.5 key_links + /verify-claim (separate PR) compose: must-haves define the wiring; /verify-claim checks it.
+- Atomic-commit discipline aligns with the e2e-pairing pre-commit gate (per-task commits make the gate's per-commit check meaningful).
+- SUMMARY deviation-tracking references the executor Rule 1/2/3/4 vocabulary (consistent with the deferral-detector + the GSD methodology framing).
+- The old Phase 5 `git add -A` guidance is REPLACED (it contradicted the new atomic-commit discipline) — a deliberate fix, not just an addition.
+- Migration only touches a stock /build skill; customized skills are fingerprint-guarded.
+
+## 6. Rollback cost
+Moderate-low. Revert the SKILL.md edits + the migration method + the doc + the migration test. Existing agents that already ran the migration would keep the updated SKILL.md (harmless — the new sections are additive guidance). The migration is idempotent and conservative, so a revert-then-re-apply is safe.
+
+## 7. Migration parity
+- New agents: bundled SKILL.md (copied by installBuildSkill on fresh init) carries the sections.
+- Existing agents: migrateBuildSkillMethodology() content-sniffs for the Phase 0.5 marker and re-copies the bundled SKILL.md if absent AND the file matches the stock fingerprint. Wired into the migration sequence after migrateSkillPortHardcoding. Idempotent + fingerprint-guarded (verified by 4 tests).
+- The defense-in-depth doc is a repo doc, not an agent-installed file — ships with the package, no migration needed.
+
+## Conclusion
+Ship. Bundling the four /build-touching items into one PR is correct (separate PRs would self-conflict on SKILL.md). The methodology is the spike's planner+executor discipline imported as Instar's own. Migration parity covered with a conservative content-sniff migration + 4 tests. Seven-dimension review clean.

package/upgrades/side-effects/consent-telegram-buttons.md

@@ -0,0 +1,77 @@
+# Side-effects review — Telegram consent buttons (PR 6 of tunnel-failure-resilience chain)
+
+**Scope (PR 6 of the chain):** Wire the consent state machine (PR 5)
+to a real Telegram inline-button UX. When Tier-1 is exhausted and a
+Tier-2 relay is available, the owner gets a DM with two buttons —
+"Yes, use a backup" / "No, keep waiting" — and tapping one drives
+`grantConsent` / `declineConsent` on the manager. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` Part 3.
+
+**Files touched:**
+- `src/messaging/TelegramAdapter.ts` — adds `setTunnelConsentHandler`
+  (handler injection), `sendOwnerConsentPrompt(text, nonce)` (DM with
+  inline buttons carrying `tc:g:<nonce>` / `tc:d:<nonce>`), and a new
+  `tc:`-prefixed early-return branch in `processCallbackQuery` that
+  enforces the owner-principal check, validates the nonce shape, calls
+  the injected handler, and clears the keyboard. `editMessageWithRetry`
+  gains an optional `chatId` param (defaults to `config.chatId`) so the
+  keyboard-clear edit can target the owner's private DM rather than the
+  group — without disturbing the existing prompt-gate callers.
+- `src/tunnel/TunnelManager.ts` — `attachTelegram` captures the adapter
+  ref, registers the grant/decline handler, and passes
+  `suppressConsentDM: true` to the notifier; `requestConsent` sends the
+  button prompt (degrading to plain-text `sendToOwnerDM` when an adapter
+  lacks button support). Adds `consentPromptText`. The
+  `TunnelMessagingAdapter` interface gains two optional methods.
+- `src/tunnel/TunnelNotifier.ts` — adds `suppressConsentDM` option so
+  the manager-sent button prompt isn't duplicated by the notifier's
+  plain-text owner-DM.
+- `tests/unit/tunnel-consent-telegram.test.ts` — NEW. 10 tests: 6 on
+  the manager↔adapter seam (handler registration, button prompt carries
+  the live nonce, no double-send, grant→relay-active, decline→exhausted
+  +cooldown, stale-nonce no-op) and 4 on the adapter-side callback gate
+  (owner grant/decline, NON-owner rejection, malformed `tc:` data).
+
+**Over-block:** None. The `tc:` prefix is unique in the codebase (a grep
+for `callback_data:` literals returns only PR 6's two buttons), the
+regex is strict (`^tc:([gd]):([0-9a-f]{32})$`), and any non-`tc:`
+callback falls through unchanged to the existing prompt-gate handler
+below. Malformed `tc:` data is answered with "Invalid consent button"
+and consumed, never forwarded.
+
+**Under-block:** One edge worth naming. The owner gate is
+`if (owner && query.from.id !== owner) reject`. When **no** owner is
+configured (`ownerUserId` and `promptGate.ownerId` both unset), the gate
+is skipped. This is benign by construction: with no owner there is no DM
+target, so `sendOwnerConsentPrompt` returns null and **no button is ever
+sent** — there is nothing to click. Even a hand-crafted callback can't
+activate a relay, because `grantConsent` requires a single-use CSPRNG
+nonce that matches the live pending-consent record (cleared-before-start
+so a replay loses). Security is layered: owner-principal check **and**
+nonce match. The adapter regex is only a low-level validator (signal);
+the manager's `grantConsent` holds the blocking authority.
+
+**Level-of-abstraction fit:** Clean. The adapter owns the Telegram
+protocol (parse, owner check, answer toast, keyboard clear); the manager
+owns the tunnel-state transition via the injected handler. The adapter
+never imports tunnel types and the manager never imports Telegram types
+(the duck-typed `TunnelMessagingAdapter` interface is the seam).
+
+**Interactions:**
+- `query.data` is guarded (`if (!query.data) return`) immediately above
+  the `tc:` block, so `.startsWith` can't throw.
+- The path is reached both by the poll loop and by
+  `handleForwardedCallback` — the Lifeline forwards callbacks in
+  send-only mode, which is exactly the tunnel-down scenario this feature
+  exists for.
+- `suppressConsentDM` prevents a double owner-DM (button prompt from the
+  manager + plain-text prompt from the notifier).
+- No HTTP surface in this PR, so the Tier-2/Tier-3 "feature is alive"
+  HTTP tests are N/A. Wiring is verified two ways: the unit test asserts
+  `attachTelegram` registers the handler, and the production call site
+  exists at `src/commands/server.ts` (`tunnel.attachTelegram(telegram, …)`).
+
+**Rollback cost:** Low. Purely additive; `suppressConsentDM` defaults
+false (back-compat for existing notifier callers). No config schema,
+migration, or persistent state. Revert = drop the three method additions
++ the `tc:` block + the `attachTelegram` handler-registration lines.

package/upgrades/side-effects/slopcheck-guard.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — Slopcheck Guard Hook
+
+**Source:** Cherry-pick from GSD-Instar spike (gsd-executor Rule 3 exclusion)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+Could over-fire on legitimate installs of new-but-real packages. Mitigation: NEVER blocks — signal-only nudge. Worst case is one extra checklist the agent reads and proceeds past. Familiar packages (in any manifest/lockfile) are silently skipped.
+
+## 2. Under-block
+Could miss a slopsquat if it happens to share a token with something in a lockfile. Mitigation: the lockfile presence check is deliberately loose (favors NOT nagging on known-safe). The nudge is a backstop, not the only defense — the agent still reasons about each install. Acceptable: under-block here means "no extra nudge", not "install proceeds unchecked" (the agent always sees the command).
+
+## 3. Level-of-abstraction fit
+PreToolUse Bash hook alongside dangerous-command-guard, deferral-detector, grounding-before-messaging. Same layer, same idiom, same generator pattern (PostUpdateMigrator getter).
+
+## 4. Signal-vs-authority compliance
+Compliant. Pure pattern-match + lockfile lookup = low-context filter emitting a signal (additionalContext). The agent (full-context authority) decides whether to install. Never blocks.
+
+## 5. Cross-feature interactions
+- dangerous-command-guard (PreToolUse Bash, blocking) runs first and independently — no overlap (it blocks destructive commands; slopcheck nudges on installs).
+- deferral-detector (PreToolUse Bash) matches communication commands — no overlap with install commands.
+- The hook reads project manifests read-only; no mutation, no shared state.
+- Edge: `echo npm install foo` would trigger the nudge (regex matches anywhere). Harmless — signal-only, rare, and erring toward caution on anything that looks like an install is the safe direction.
+
+## 6. Rollback cost
+Trivial. One generator method, one settings-template entry, one migrateSettings ensure-block, one manifest entry, one known-list entry, one test file. Revert the commit; the hook stops generating and existing copies become inert.
+
+## 7. Migration parity
+Full coverage:
+- New agents: settings-template.json PreToolUse Bash entry.
+- Existing agents: explicit ensure-block in migrateSettings() adds the slopcheck entry to the Bash matcher if absent (idempotent — checks `hasSlopcheck` first).
+- Hook script: always-overwritten by migrateHooks() (built-in hook).
+- builtin-manifest.json: registered.
+- known-builtin-hooks list: registered (orphan-cleanup safe).
+
+## Conclusion
+Ship. Real supply-chain defense Instar lacked. Signal-only, trivial rollback, full migration parity. Seven-dimension review clean.

package/upgrades/side-effects/verify-claim-skill.md

@@ -0,0 +1,33 @@
+# Side-Effects Review — /verify-claim Skill
+
+**Source:** Cherry-pick from GSD-Instar spike (gsd-verifier 4-level protocol)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+N/A — a prompt skill, blocks nothing. Worst case: the agent runs a few extra grep/test commands before claiming done. That's the intended cost.
+
+## 2. Under-block
+The skill is advisory — an agent could skip invoking it. Mitigation: it's wired into the recommended /build Phase 3 flow and the "before claiming shipped" trigger. Not a hard gate (that would be the e2e-pairing pre-commit hook + response-review). This is the verification METHODOLOGY made callable; enforcement lives elsewhere.
+
+## 3. Level-of-abstraction fit
+A user-invocable skill alongside the other built-in skills in installBuiltinSkills(). Same inline-content pattern, same install mechanism, same idempotency guarantee.
+
+## 4. Signal-vs-authority compliance
+N/A in the gate sense — it's a methodology the agent runs. It PRODUCES signals (the per-level status), and the agent (authority) acts on them. Aligned with the spike's whole verdict: import the methodology, let the agent wield it.
+
+## 5. Cross-feature interactions
+- Complements the e2e-pairing pre-commit gate (that enforces an e2e test FILE exists; this verifies a claim is actually wired). Different layers, no overlap.
+- Complements response-review (Stop hook). /verify-claim is invoked DURING work; response-review checks the outbound message.
+- Referenced from /build Phase 3 VERIFY as the per-must-have check.
+- Pure additive skill — no existing skill changes.
+
+## 6. Rollback cost
+Trivial. One entry in the installBuiltinSkills record + one test file. Revert the commit; the skill stops being installed for new agents. Existing agents that already have the SKILL.md keep an inert copy (harmless).
+
+## 7. Migration parity
+Adding a NEW skill needs no migration per the Migration Parity Standard: installBuiltinSkills() is called from refreshHooksAndSettings() on every update and is non-destructive (only writes missing SKILL.md files). Existing agents get verify-claim on their next update. Idempotency verified in the test (does not overwrite a customized copy).
+
+Note: a follow-up should add /verify-claim to the CLAUDE.md template's capability list (Agent Awareness Standard) so agents surface it conversationally — tracked, not blocking this PR.
+
+## Conclusion
+Ship. The spike's #1 cherry-pick by leverage. Pure additive prompt skill, trivial rollback, no migration needed. Seven-dimension review clean.

package/upgrades/1.2.43.md

@@ -1,31 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- bump: patch -->
-
-## What Changed
-
-**feat(dev): e2e-pairing pre-commit gate — GSD cherry-pick.**
-
-New pre-commit gate (`scripts/check-e2e-pairing.cjs`, wired into `.husky/pre-commit`) that blocks any commit changing a non-test `src/server/*.ts` file unless it also stages at least one `tests/e2e/*.test.ts`. Structurally enforces the Tier-3 "feature is alive" discipline that CLAUDE.md calls the single most important test for any feature with API routes.
-
-From the GSD-Instar spike, where the gsd-planner methodology surfaced that the Topic Intent Layer's Tier-3 lifecycle test would have been forgotten under ad-hoc planning. This gate makes "ship a route without an e2e test" structurally hard rather than discipline-dependent.
-
-Two escape hatches keep it from being tyrannical: env bypass (`INSTAR_SKIP_E2E_PAIRING=1`) and an `E2E-PAIRING: EXEMPT — <reason>` marker in a staged server file (for genuine refactors / type-only / comment changes).
-
-This governs instar's OWN development commits (it's in instar's `.husky/`), not agent-installed files — so no migration parity needed.
-
-## Evidence
-
-8 unit tests, all green (tmp-git-repo harness): passes with no server files, blocks server-without-e2e, passes server-with-e2e, ignores server test files + .d.ts, respects env bypass + EXEMPT marker, blocks when only an unrelated unit test is staged. TypeScript clean.
-
-Verified the gate does not block this very PR (this PR changes scripts/ + .husky/ + tests/, not src/server/).
-
-Side-effects review: `upgrades/side-effects/e2e-pairing-gate.md`.
-
-## What to Tell Your User
-
-Nothing user-visible. Internal dev-discipline gate for instar contributors.
-
-## Summary of New Capabilities
-
-One new pre-commit gate script + one line in .husky/pre-commit. Signal-with-commit-authority (blocks), with two escape hatches. Errs toward false positives because a route shipped without an e2e test is the corruption-class failure being defended against.