instar 1.3.321 → 1.3.323

package/upgrades/1.3.323.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Adds **agent-readiness scoring** — Salim Ismail's EXO 3.0 "task decomposition
+matrix," made runnable. Score a task or workflow on its **coordination-vs-judgment
+ratio** to tell whether it's a good agent candidate:
+
+- **Coordination work** (routing, approvals, scheduling, status-tracking,
+  prescriptive/standardized steps) is what agents do best → agent-ready.
+- **Judgment work** (ambiguity, exceptions, relationships, no-playbook calls)
+  → stays human.
+
+New surface:
+
+- `POST /agent-readiness/score` `{ "task": {description} }` or
+  `{ "workflow": {steps:[...]} }` → `{ coordinationSignals, judgmentSignals,
+  coordinationRatio, overallReadiness (0-100), recommendation, reason, matched }`.
+  `recommendation` is `deploy-agent` (75+) / `agent-with-oversight` (55-74) /
+  `hybrid` (40-54) / `human-led` (<40).
+- A `/agent-readiness` skill so agents reach for it proactively before delegating
+  work or deciding what to automate.
+
+Deterministic + advisory — it answers a question, never blocks. Pairs with the
+MTP Protocol's `/intent/org/test-action` (is it agent-ready AND does our purpose
+endorse it?).
+
+## What to Tell Your User
+
+Your agent can now grade any task or workflow on whether it's a good fit for an agent at all. Ask it to "score this task for agent-readiness" and you get a 0-100 readiness score with a plain recommendation: hand it to an agent, agent-with-oversight, split it, or keep it human. The logic mirrors how EXO 3.0 thinks about delegation — coordination-heavy work (routing, scheduling, status-chasing) is agent-ready; judgment-heavy work (ambiguity, exceptions, relationships) stays with people. Useful the moment you're deciding what to automate next.
+
+## Summary of New Capabilities
+
+- `POST /agent-readiness/score` — score `{task}` or `{workflow}`; returns coordination/judgment signals, `overallReadiness` 0-100, and a `deploy-agent` / `agent-with-oversight` / `hybrid` / `human-led` recommendation. Deterministic + advisory, never blocks.
+- `/agent-readiness` skill — the proactive entry point before delegating work or choosing what to automate.
+- Pairs with `POST /intent/org/test-action`: is it agent-ready AND does the org's purpose endorse it?
+
+## Evidence
+
+Three-tier coverage, all green, `tsc --noEmit` clean (0 errors):
+
+- Unit — `AgentReadinessScorer.test.ts` (6): coordination-dominant → deploy-agent,
+  judgment-dominant → human-led, mixed → hybrid, no-signal default, and a
+  substring-false-match guard (log vs logical).
+- Integration — `agent-readiness-routes.test.ts` (4): the route over the real
+  HTTP pipeline (400 on neither task nor workflow; task + workflow scoring).
+- E2E — `agent-readiness-lifecycle.test.ts` (3): boots a real server on a real
+  port and confirms the feature is alive (200, not 404/503) end-to-end.
+
+Skill registered in `installBuiltinSkills` (auto-installs for new + updated
+agents, non-destructive); CLAUDE.md scaffold template documents the endpoint.

package/upgrades/side-effects/exo3-g1-ci-greening.md

@@ -0,0 +1,42 @@
+# Side-effects — EXO 3.0 G1 (#785) CI greening on post-rebase main
+
+## Change set
+
+- `tests/e2e/mtp-protocol-test-action-lifecycle.test.ts` — teardown `fs.rmSync`
+  → `SafeFsExecutor.safeRmSync` (lint-no-direct-destructive compliance; test-only).
+- `upgrades/next/mtp-protocol-exo3.md` — adds `## What to Tell Your User` +
+  `## Summary of New Capabilities` (fragment validation + Repo Invariants).
+- `tests/unit/feature-delivery-completeness.test.ts` — registers
+  'MTP Protocol — the two EXO 3.0 tests' in `featureSections`.
+- `src/core/PostUpdateMigrator.ts` — adds the `'**MTP Protocol — the two EXO
+  3.0 tests'` shadow marker to `migrateFrameworkShadowCapabilities` markers[]
+  (mirrors the section to AGENTS.md / GEMINI.md).
+
+## Side effects considered
+
+- **Shadow mirror growth**: Codex/Gemini agents gain one more mirrored section
+  on their next migration run. Idempotent (`appended.includes(marker)` guard);
+  marker omits trailing punctuation so it matches both the template variant
+  ("…tests (Phase 5).") and the migrator variant ("…tests."). Risk: none beyond
+  a few hundred bytes in shadow files.
+- **Slice bounding**: the marker participates in the next-marker boundary scan
+  for OTHER sections' slices. Because the MTP section sits adjacent to other
+  bold-marker sections, including it actually IMPROVES slice precision (the
+  same reason the markers list exists — see the Secret Drop regression note in
+  the migrator).
+- **No runtime behavior change**: no route, no migration logic, no scheduler,
+  no messaging path touched. The only src edit is data (one marker string).
+- **Test-only deletions**: SafeFsExecutor in e2e teardown routes through the
+  audited funnel; tmpdir-scoped, recursive+force semantics unchanged.
+
+## Verification
+
+- `tests/unit/feature-delivery-completeness.test.ts` + the MTP e2e: 73/73 green locally.
+- `node scripts/check-repo-invariants.mjs` → "Repository invariants hold."
+- `node scripts/lint-no-direct-destructive.js` → clean.
+- `tsc --noEmit` → 0 errors.
+
+## Rollback
+
+Revert this single commit; the feature commit (da33b79a7) and merge commit
+(bf8022b1b) are untouched by it.

package/upgrades/side-effects/exo3-g2-ci-greening.md

@@ -0,0 +1,35 @@
+# Side-effects — EXO 3.0 G2 (#791) CI greening on post-rebase main
+
+## Change set
+
+- `src/server/CapabilityIndex.ts` — new `agentReadiness` CAPABILITY_INDEX entry
+  (prefix `/agent-readiness`, static `configured: true`, one endpoint).
+- `src/core/PostUpdateMigrator.ts` — migrateClaudeMd gains the Agent-Readiness
+  Scoring section (content-sniffed, idempotent) + the shadow marker
+  `'**Agent-Readiness Scoring (EXO 3.0'` in migrateFrameworkShadowCapabilities.
+- `tests/unit/feature-delivery-completeness.test.ts` — registers the section in
+  featureSections (enforces template + migrator + shadow parity).
+- `upgrades/next/agent-readiness-scoring.md` — adds the two user-facing
+  sections fragment validation requires.
+
+## Side effects considered
+
+- **/capabilities response grows** by one block; builder is pure/static (no
+  ctx dependency — the route is a stateless scorer behind a dynamic import),
+  so no probe-path cost or null-ctx risk.
+- **Existing agents' CLAUDE.md grows** one section on next migration
+  (idempotent via `content.includes` sniff on a distinctive phrase that matches
+  both template and migrator variants: 'Agent-Readiness Scoring (EXO 3.0').
+- **Shadow files** (AGENTS.md/GEMINI.md) mirror the section; marker bounded by
+  the next-marker scan like its siblings.
+- **No scorer behavior change**: AgentReadinessScorer and its route untouched.
+
+## Verification
+
+- feature-delivery-completeness + capabilities-discoverability + agent-readiness
+  unit/integration/e2e suites green locally; `check-repo-invariants` holds;
+  `tsc --noEmit` 0 errors.
+
+## Rollback
+
+Revert this single commit; the feature commits are untouched by it.