instar 1.3.85 → 1.3.87

package/upgrades/1.3.87.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Two fixes ship together here.
+
+**Operation-safety gate action vocabulary and fail-closed hardening.** The external operation-safety gate emits a proceed action for allowed operations, but the generated guard hook and the docs described the allowed action as allow and only branched explicitly on the block, show-plan, and suggest-alternative cases — so proceed was permitted only by falling through, and an unrecognized action would slip through that same silent path. The hook now permits proceed explicitly (keeping allow for backward compatibility) and blocks any unrecognized action instead of letting it pass, and the docs and generated guidance now use the real vocabulary. This is a safety tightening: an unknown gate decision now fails closed.
+
+**Commitments follow-up contract guidance.** The generated Commitments guidance described creating follow-up promises with a type the server actually rejects and omitted a required field. Agents now record follow-up promises as one-time-action commitments that include both the user request and the agent response before marking them delivered, matching the live contract.
+
+## What to Tell Your User
+
+- **The operation-safety gate is stricter now**: when I check whether an outside action is safe, an allowed action is now handled on purpose rather than by accident, and anything the safety check does not recognize is blocked rather than waved through. How existing approvals and blocks work is unchanged.
+- **Commitment follow-through is more reliable**: when I register a future follow-up for myself, the built-in guidance now uses the same wording the server actually accepts, so the reminder can be created and closed cleanly.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Operation-gate fail-closed on unknown actions | Automatic. The generated operation-safety hook now blocks any unrecognized gate decision instead of permitting it, and treats the allowed action explicitly. |
+| Operation-gate vocabulary alignment | Automatic. Docs and generated guidance now match the action values the gate actually emits. |
+| Commitments follow-up contract guidance | Automatic for newly generated or migrated agent guidance. |
+
+## Evidence
+
+- Operation gate: unit (ExternalOperationGate and hook-installation), integration (operation-safety routes), and e2e (action-vocabulary lifecycle) tests cover the explicit-permit, legacy-compat, and block-unknown paths; the docs, templates, and spec were aligned to the real vocabulary.
+- Commitments: live lifecycle verification created a test commitment, inspected it, delivered it, and verified it was terminal and closed; focused unit, integration, and e2e tests pin the accepted create payload, delivery transition, active-list closure, generated guidance, and PromiseBeacon stop behavior.
+- Note: the operation-gate change merged to main first, but its release notes were dropped during a rebase across a release-cut, so it is released here alongside the commitments guidance fix.

package/upgrades/side-effects/attention-api-vocabulary-compatibility.md

@@ -0,0 +1,126 @@
+# Side-Effects Review — Attention API vocabulary compatibility
+
+**Version / slug:** `attention-api-vocabulary-compatibility`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `self-audit; subagent not spawned by tool policy`
+
+## Summary of the change
+
+This change adds a route-boundary normalizer for Attention Queue status and
+priority vocabulary. Canonical read/store values stay uppercase, while write
+requests may use documented aliases such as `resolved`, `medium`, `body`, and
+`source`. Generated guidance is also corrected to show the required stable item
+id. Files touched include `src/server/attentionApi.ts`, `src/server/routes.ts`,
+the generated guidance templates, and unit/integration/e2e tests.
+
+## Decision-point inventory
+
+- `PATCH /attention/:id` — modified — accepts documented aliases before calling
+  the existing status updater.
+- `GET /attention?status=...` — modified — accepts status aliases for filtering.
+- `POST /attention` — modified — accepts documented create-field aliases before
+  the existing tone-gated create path.
+- Attention topic-flood guard — pass-through — no threshold, coalescing, or
+  topic creation behavior is changed.
+
+---
+
+## 1. Over-block
+
+The change reduces rejection of legitimate documented request shapes. It does
+not add new block conditions. Unknown statuses and priorities still reject on
+write, which is appropriate because the server cannot safely infer arbitrary
+lifecycle states.
+
+---
+
+## 2. Under-block
+
+The alias layer broadens accepted write vocabulary. The main residual risk is an
+operator using an ambiguous word outside the alias set; those values still
+reject. The accepted aliases map only to existing canonical values, so no new
+state can bypass lifecycle handling.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The fix belongs at the HTTP route boundary. Internal storage and Telegram topic
+commands already use canonical statuses; external callers and generated
+guidance use friendlier names. Normalizing at the boundary preserves internal
+consistency without forcing every caller to know storage vocabulary.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [x] Yes — but this is hard-invariant API validation over a finite enum.
+- [ ] Yes, with brittle logic — STOP. Reshape the design.
+
+This is not a judgment gate. The route validates and normalizes finite API enum
+values, which is one of the hard-invariant validation cases allowed by the
+principle. It does not inspect message meaning or add a new block authority.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The normalizer runs before existing `updateAttentionStatus` and
+  `createAttentionItem` calls. Canonical values pass through unchanged.
+- **Double-fire:** No additional Telegram send, topic creation, callback, or
+  persistence path is added.
+- **Races:** No shared mutable state is introduced; normalization is pure.
+- **Feedback loops:** Internal release-readiness resolution calls that already
+  send `resolved` now work against the route instead of failing.
+
+---
+
+## 6. External surfaces
+
+The `/attention` write surface becomes more permissive for documented aliases.
+The read surface remains canonical uppercase. Generated AGENTS/CLAUDE guidance
+will include a stable `id` in new installs and migrations. No existing attention
+state is rewritten. No new attention items are created by the verification path.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal hot-fix revert. There is no data migration. If reverted,
+documented lowercase resolve calls and create aliases would fail again until a
+replacement patch lands.
+
+---
+
+## Conclusion
+
+The fix aligns the documented write vocabulary with the canonical read/store
+vocabulary without changing topic creation policy or existing state. The
+three-tier tests cover the compatibility path and keep the topic-facing effects
+stubbed during verification.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** `self-audit; subagent not spawned by tool policy`
+**Independent read of the artifact: concur**
+
+The compatibility layer is intentionally limited to finite enum and field-name
+aliases. It does not create automatic item ids, because stable ids are part of
+the queue's dedupe discipline; the docs now show that requirement explicitly.
+
+---
+
+## Evidence pointers
+
+- Read-only live inspection found 9 existing attention items using statuses
+  `OPEN` and `DONE`, priorities `HIGH` and `NORMAL`, and no suppressed-topic log
+  present.
+- Focused verification:
+  `npx vitest run tests/unit/attention-api-normalization.test.ts tests/integration/attention-route-vocabulary.test.ts tests/e2e/attention-queue-vocabulary-lifecycle.test.ts tests/unit/SeedMigration.test.ts`

package/upgrades/side-effects/commitments-agent-contract-vocabulary.md

@@ -0,0 +1,39 @@
+# Commitments Agent Contract Vocabulary
+
+## Scope
+
+Align generated agent guidance with the live `/commitments` API contract for one-time follow-up promises.
+
+## Runtime Finding
+
+Live verification showed the lifecycle works with the actual contract:
+
+1. Create with `type:"one-time-action"`, `userRequest`, `agentResponse`, and `topicId` returns a `pending` commitment with the expected fields.
+2. Direct lookup returns the same record.
+3. Delivery transitions the commitment to `delivered`, sets `resolvedAt`, increments the version, and closes it from active follow-up.
+4. PromiseBeacon delivery behavior is already covered by integration: delivered commitments stop scheduled beacon work and later fires are no-ops.
+
+The rejected shape was the generated guidance: `type:"follow-up"` plus no `agentResponse`.
+
+## Files
+
+- `src/scaffold/templates.ts` — update new-agent Commitments guidance to use `one-time-action` and include `agentResponse`.
+- `src/core/PostUpdateMigrator.ts` — update migrated Commitments guidance for existing agents.
+- `src/data/builtin-manifest.json` — regenerated after template guidance changes.
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — pin migrated guidance vocabulary.
+- `tests/unit/commitments-agent-guidance-contract.test.ts` — pin template and migrator vocabulary together.
+- `tests/unit/commitment-routes.test.ts` — cover the agent-facing create shape and deliver transition.
+- `tests/e2e/commitments-api-lifecycle.test.ts` — cover create, lookup, deliver, lookup, and active-list closure through HTTP.
+- `docs/specs/COMMITMENTS-AGENT-CONTRACT-VOCABULARY-SPEC.md` — durable contract note.
+- `docs/specs/COMMITMENTS-AGENT-CONTRACT-VOCABULARY-SPEC.eli16.md` — plain-language overview.
+- `upgrades/NEXT.md` — release-note entry for the next patch.
+
+## Side Effects
+
+Existing agents that receive migrated guidance will be taught the accepted route contract. Existing commitment records are not migrated and no stored status vocabulary changes.
+
+The guidance still uses "open" as a human verb. The API status for a newly created one-time follow-up remains `pending`.
+
+## Rollback
+
+Revert the template/migrator and tests. Runtime commitment behavior is unchanged by this PR.

package/upgrades/side-effects/external-operation-action-vocabulary.md

@@ -0,0 +1,132 @@
+---
+title: External Operation Gate — action vocabulary alignment
+slug: external-operation-action-vocabulary
+date: 2026-05-29
+author: codey
+second_pass_required: false
+---
+
+## Summary of the change
+
+The External Operation Gate endpoint already used `proceed` as its canonical
+allowed action, but generated documentation described the action as `allow`, and
+the generated PreToolUse hook accepted `proceed` only through an implicit
+fallthrough path. This change aligns the docs and hook with the core gate:
+`proceed`, `show-plan`, `suggest-alternative`, and `block`. The hook explicitly
+permits `proceed`, keeps legacy `allow` compatibility, and blocks unknown action
+values instead of silently proceeding.
+
+Files touched include the hook generator in `PostUpdateMigrator`, generated and
+source documentation, capability text, and unit/integration/e2e tests.
+
+## Decision-point inventory
+
+- `ExternalOperationGate.evaluate()` — pass-through — remains the authority and
+  source of truth for emitted action values.
+- Generated `external-operation-gate.js` hook — modified — explicitly maps
+  `proceed` and legacy `allow` to permit; unknown actions now block.
+- Generated/documented External Operation Safety guidance — modified — names
+  `proceed` instead of `allow`.
+
+---
+
+## 1. Over-block
+
+The new over-block risk is a gate response with a valid future action value that
+this hook version does not recognize. The hook would block it. That is
+intentional for this trust boundary: new action values must be added to the hook
+and tests deliberately, rather than inheriting permission through fallthrough.
+
+Legacy `allow` is accepted to avoid over-blocking stale local test doubles or
+older endpoints during mixed-version windows.
+
+---
+
+## 2. Under-block
+
+The main previous under-block was unknown action fallthrough. That is removed.
+The remaining under-block is the existing designed fail-open path when the local
+server is unreachable or the hook cannot parse input. This change does not alter
+that broader availability policy.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The endpoint remains the authority for operation risk. The hook is the local
+enforcement adapter that translates action words into command behavior. Keeping
+legacy compatibility at the hook boundary is the right layer because it protects
+mixed-version local installs without changing the core gate's canonical type.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change does not add a brittle detector with blocking authority.
+
+The hook is already an enforcement authority at an external-service trust
+boundary. This change narrows that authority's accepted action vocabulary to the
+canonical gate contract, plus one explicit legacy alias. It does not introduce a
+new heuristic signal.
+
+---
+
+## 5. Interactions
+
+- **Hook install/migration:** existing installations receive the updated hook
+  when the post-update migrator refreshes built-in hook content.
+- **Mixed versions:** a hook updated before an endpoint still accepts legacy
+  `allow`; an endpoint updated before a hook already worked because old hooks
+  fell through on `proceed`.
+- **Identity grounding:** irreversible writes that receive `proceed` still pass
+  through the existing identity-grounding injection path before allowing the
+  operation.
+- **Read fast path:** read MCP calls still exit locally before calling the gate.
+
+---
+
+## 6. External surfaces
+
+External-service MCP calls are affected. The successful endpoint action is
+documented as `proceed`; callers that asserted the old documentation should
+update. The hook's runtime behavior is stricter for malformed gate responses:
+unknown actions now block non-read external operations instead of silently
+running them.
+
+No persistent state schema changes, no database migrations, and no external API
+credentials are affected.
+
+---
+
+## 7. Rollback cost
+
+Pure code and docs rollback. Revert the hook generator and docs/tests; no data
+cleanup is needed. During rollback, `proceed` would again be permitted only by
+unknown fallthrough in the hook, which is the behavior this change removes.
+
+---
+
+## Conclusion
+
+The mismatch is reconciled by treating the core gate as authoritative and
+pinning `proceed` as the canonical allowed action. The compatibility alias keeps
+mixed-version behavior stable, while the unknown-action block removes the
+silent-fallthrough safety gap. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+---
+
+## Evidence pointers
+
+- `tests/unit/ExternalOperationGate.test.ts`
+- `tests/unit/hook-installation.test.ts`
+- `tests/integration/external-operation-safety-routes.test.ts`
+- `tests/e2e/external-operation-action-vocabulary-lifecycle.test.ts`