instar 1.3.84 → 1.3.86

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/coherence-indeterminate-summary.md

@@ -0,0 +1,127 @@
+# Side-Effects Review — Coherence Gate indeterminate summaries
+
+**Version / slug:** `coherence-indeterminate-summary`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `self-audit; subagent not spawned by tool policy`
+
+## Summary of the change
+
+This change updates `ScopeVerifier` so unbound topic-project alignment is
+represented as `passed: null`, the overall `passed` flag is true only when every
+check truly passed, and the summary reports passed, warning, error, and
+indeterminate counts. It adds unit, integration, and e2e tests for the
+indeterminate path. The decision point touched is the Coherence Gate's
+pre-action warn/block/proceed response.
+
+## Decision-point inventory
+
+- `ScopeVerifier.check()` — modified — recommendation policy remains the same,
+  while summary and top-level pass reporting now distinguish indeterminate
+  checks from passed checks.
+- `checkTopicProjectAlignment()` — modified — missing topic binding is now an
+  indeterminate warning instead of a boolean false warning.
+
+---
+
+## 1. Over-block
+
+No new block condition is introduced. Unbound topics remain warning-level and do
+not become blockers. A caller that incorrectly treated top-level `passed: true`
+as permission despite `recommendation: "warn"` will now see `passed: false`, but
+that is the intended correction: the check did not actually pass.
+
+---
+
+## 2. Under-block
+
+This does not add new blocking coverage. A topic with no binding still warns
+rather than blocks, so an agent can still proceed after verification. Wrong
+project bindings remain error-severity failures and still block.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This is at the reporting layer of an existing deterministic gate. The gate
+already owns the pre-action recommendation. The change does not add a parallel
+authority; it makes the existing gate's human-readable and machine-readable
+fields agree.
+
+---
+
+## 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.
+- [ ] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context
+  (LLM-backed with recent history or equivalent).
+- [ ] Yes, with brittle logic — STOP. Reshape the design.
+
+The existing Coherence Gate remains the authority for warn/block/proceed. This
+change clarifies a structured signal state (`null` means indeterminate) and the
+summary text derived from those signals. It does not introduce an independent
+blocker.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** No route or hook order changes. The same `/coherence/check`
+  route calls the same `ScopeVerifier.check()` path.
+- **Double-fire:** No new event or side effect is emitted.
+- **Races:** No persistent state or asynchronous coordination is added.
+- **Feedback loops:** Agents may respond more cautiously because `passed` is now
+  false for indeterminate checks, matching the existing warning recommendation.
+
+---
+
+## 6. External surfaces
+
+The `/coherence/check` JSON shape changes for unbound topics: the
+topic-project-alignment check returns `passed: null`, and the top-level `passed`
+field is false when any check is indeterminate. The recommendation field remains
+unchanged. No database, file format, credential, network, or third-party
+surface changes are introduced.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal hot-fix revert. There is no migration and no persistent
+state repair. During rollback propagation, agents would temporarily see the old
+misleading summary for unbound topics again.
+
+---
+
+## Conclusion
+
+The change is narrowly scoped to truthful reporting for an existing warning path.
+It keeps the Coherence Gate policy intact while removing an internal
+contradiction that made summaries less trustworthy. The three-tier tests cover
+the core logic, route response, and full server lifecycle.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** `self-audit; subagent not spawned by tool policy`
+**Independent read of the artifact: concur**
+
+The main risk is API compatibility for callers that assumed `ScopeCheck.passed`
+was always boolean. The route already had contradictory `passed` and
+`recommendation` signals, and the requested contract explicitly uses
+`passed: null` for indeterminate, so the compatibility cost is acceptable and
+tested.
+
+---
+
+## Evidence pointers
+
+- Live verification before the source change reproduced the bug: an unbound
+  topic check returned `recommendation: "warn"` while the summary still claimed
+  all four checks passed.
+- Focused verification after the source change:
+  `npx vitest run tests/unit/ScopeVerifier.test.ts tests/integration/coherence-routes.test.ts tests/e2e/coherence-check-indeterminate-lifecycle.test.ts`