instar 1.3.322 → 1.3.324

package/upgrades/1.3.324.md

@@ -0,0 +1,51 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Adds the **agent digital passport** — Salim Ismail's EXO 3.0 concept (from *The
+80-Year Business Rule AI Just Broke*): "every AI agent gets a digital passport
+with metadata saying what it's allowed to do and what it's not allowed to do,
+and other agents watching that it's complying."
+
+This packages Instar's existing primitives — agent identity (name + routing
+fingerprint), trust level, and ORG-INTENT constraints — into one portable
+passport, plus a deterministic compliance check a peer runs before trusting an
+action:
+
+- `GET /passport` → `{ version, agent, fingerprint, trustLevel,
+  allowedCapabilities, forbiddenActions, issuedAt }`. `forbiddenActions` are
+  drawn from the agent's ORG-INTENT constraints.
+- `POST /passport/verify` `{ passport, action }` → `{ permitted, basis, reason,
+  matched? }` where `basis` is `forbidden-action` | `trust-floor` (an untrusted
+  passport may observe but not act) | `out-of-scope` | `ok`.
+- A `/agent-passport` skill so agents reach for it proactively.
+
+Deterministic + advisory — it answers "should I let this passport do this?"; the
+caller decides. Pairs with the MTP Protocol (`/intent/org/test-action`).
+
+## What to Tell Your User
+
+Your agent now carries a digital passport — one portable card that says who it is (name + cryptographic fingerprint), how trusted it is, and exactly what it's forbidden to do (drawn straight from your organization's written constraints). When two agents work together, one can check the other's proposed action against that passport before trusting it: "is this allowed, forbidden, or outside your scope?" It's the EXO 3.0 idea that agents police each other's compliance — made real. Nothing changes in day-to-day use until agents start exchanging passports; there's nothing you need to configure.
+
+## Summary of New Capabilities
+
+- `GET /passport` — your own passport: `{ agent, fingerprint, trustLevel, allowedCapabilities, forbiddenActions, issuedAt }` (forbiddenActions = ORG-INTENT constraints).
+- `POST /passport/verify` `{ passport, action }` — deterministic peer compliance check → `{ permitted, basis, reason }` (basis: forbidden-action / trust-floor / out-of-scope / ok). Advisory — the caller decides.
+- `/agent-passport` skill — the proactive entry point before trusting a peer's proposed action.
+
+## Evidence
+
+Three-tier coverage, all green, `tsc --noEmit` clean:
+
+- Unit — `AgentPassport.test.ts` (6): build defaults + `permits()` across every
+  boundary (forbidden-action, trust-floor, out-of-scope, in-scope, unscoped).
+- Integration — `agent-passport-routes.test.ts` (3): both routes over real HTTP,
+  with ORG-INTENT constraints surfaced as the passport's forbidden actions.
+- E2E — `agent-passport-lifecycle.test.ts` (2): a real server on a real port;
+  `GET /passport` and `POST /passport/verify` alive end-to-end (200, not 404/503).
+
+Skill registered in `installBuiltinSkills`; CLAUDE.md scaffold template documents
+both endpoints.

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.

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

@@ -0,0 +1,31 @@
+# Side-effects — EXO 3.0 G3 (#793) CI greening on post-rebase main
+
+## Change set
+
+- `tests/integration/agent-passport-routes.test.ts` + `tests/e2e/agent-passport-lifecycle.test.ts`
+  — teardown `fs.rmSync` → `SafeFsExecutor.safeRmSync` (lint compliance; test-only).
+- `src/server/CapabilityIndex.ts` — new `agentPassport` entry (prefix `/passport`,
+  static `configured: true`, two endpoints).
+- `src/core/PostUpdateMigrator.ts` — migrateClaudeMd Agent Digital Passport
+  section (content-sniffed, idempotent) + shadow marker
+  `'**Agent Digital Passport (EXO 3.0'`.
+- `tests/unit/feature-delivery-completeness.test.ts` — featureSections entry.
+- `upgrades/next/agent-digital-passport.md` — the two required user sections.
+
+## Side effects considered
+
+- **/capabilities grows** one static block (no ctx dependency; the passport
+  builder reads identity/trust/intent lazily inside the route, not the index).
+- **Existing agents' CLAUDE.md grows** one section on next migration; sniff
+  phrase 'Agent Digital Passport (EXO 3.0' matches template + migrator variants.
+- **Shadow mirror**: marker bounded by the next-marker scan like its siblings.
+- **No passport behavior change**: AgentPassport module and routes untouched.
+
+## Verification
+
+- Passport unit/integration/e2e + completeness + discoverability suites green
+  locally; `check-repo-invariants` holds; destructive lint clean; `tsc --noEmit` 0.
+
+## Rollback
+
+Revert this single commit; feature commits untouched.