@event4u/agent-config 6.1.0 → 7.0.1

package/dist/agent-src/commands/brand/tokens.md

@@ -0,0 +1,28 @@
+---
+model_tier: high
+name: brand-tokens
+pack: brand
+tier: 2
+visibility: internal
+cluster: brand
+sub: tokens
+skills: [brand-to-tokens]
+description: Derive a DTCG .tokens.json source of truth from brand decisions, then emit CSS vars + Tailwind via the no-Node token generator.
+suggestion:
+  eligible: true
+  trigger_description: "derive brand tokens, turn our brand into design tokens, generate a .tokens.json from the brand"
+  trigger_context: "user has brand identity decisions and wants a DTCG token source of truth + CSS/Tailwind output"
+workspaces:
+  - small-business
+packs:
+  - brand
+---
+
+# /brand:tokens
+
+Run the [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) skill — brand
+decisions → a DTCG `.tokens.json` source of truth → `design-tokens` emits CSS
+vars + Tailwind (no Node). The same `.tokens.json` is the export pack-ai-image's
+brand-asset generation and the greenfield scaffold seed consume; stays on
+`$value`/`$type` so Tokens Studio / Style Dictionary round-trip. Args:
+`"<identity ref>"`.

package/dist/agent-src/commands/brand/voice.md

@@ -0,0 +1,27 @@
+---
+model_tier: high
+name: brand-voice
+pack: brand
+tier: 2
+visibility: internal
+cluster: brand
+sub: voice
+skills: [voice-and-tone-design]
+description: Define the brand voice-and-tone profile — register, do/don't lexicon, and tone shifts by context — the profile the brand-consistency gate checks copy against.
+suggestion:
+  eligible: true
+  trigger_description: "define our brand voice, voice and tone guide, how should our copy sound, tone of voice profile"
+  trigger_context: "user wants a documented voice-and-tone profile for the brand to govern copy"
+workspaces:
+  - small-business
+packs:
+  - brand
+---
+
+# /brand:voice
+
+Run the [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md)
+skill — register, do/don't lexicon, per-context tone shifts. The voice profile
+is what `/brand:review` and the `brand-consistency` gate check emitted copy
+against. Args: `"<brand/strategy ref>"`. Run `/brand:strategy` first when the
+archetype/positioning is not yet set.

package/dist/agent-src/commands/brand.md

@@ -0,0 +1,58 @@
+---
+model_tier: inherit
+name: brand
+pack: brand
+tier: 2
+visibility: internal
+cluster: brand
+type: orchestrator
+description: Brand-as-UX orchestrator — strategy, identity, tokens, review, voice. Routes to the brand-grounding skills that constrain the design layer.
+suggestion:
+  eligible: true
+  trigger_description: "work on our brand, define brand strategy/identity/voice, derive brand tokens, audit brand consistency"
+  trigger_context: "user wants to define or govern a brand layer (positioning, identity, tokens, voice) that constrains the UI"
+workspaces:
+  - small-business
+packs:
+  - brand
+---
+
+# /brand
+
+Top-level orchestrator for the `/brand:*` family — brand as a first-class UX
+layer that **constrains** the UI. Consulted **before**
+[`design-intelligence`](../../skills/design-intelligence/SKILL.md) so brand
+bounds style selection. Designer flow: discover → strategy → identity → tokens →
+application → governance. Derived brand tokens are the export pack-ai-image's
+brand-asset generation and the greenfield scaffold seed consume (B → A).
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/brand:strategy "<brief>"` | `commands/brand/strategy.md` | Positioning, archetype, voice, tone, messaging over the brand corpus |
+| `/brand:identity "<strategy ref>"` | `commands/brand/identity.md` | Logo/colour/type/imagery direction; defines the token constraints |
+| `/brand:tokens "<identity ref>"` | `commands/brand/tokens.md` | Derive a DTCG `.tokens.json` source of truth → CSS vars + Tailwind |
+| `/brand:review "<artifact>"` | `commands/brand/review.md` | Audit emitted UI/copy/assets against active brand tokens + voice |
+| `/brand:voice "<brand ref>"` | `commands/brand/voice.md` | Define the voice-and-tone profile the consistency gate checks copy against |
+
+## Dispatch
+
+1. Parse `/brand <sub-command> [args]`. Sub-command = first token; match against
+   the table's exact names only.
+2. Look up the sub-command and execute its file verbatim with the remaining args.
+3. Unknown / missing sub-command → print the table and ask which stage to run.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** — subcommands never do this.
+- **Do NOT chain subcommands.** One `/brand <sub>` per turn.
+- **Consumer brand tokens are the source of truth.** Corpus only fills gaps; a
+  value not traceable to a brand token or voice rule is off-brand (per
+  [`brand-consistency`](../rules/brand-consistency.md)).
+- **Edit `src/` only.** Generated mirrors regenerate.
+
+## See also
+
+- [`brand-strategy`](../../skills/brand-strategy/SKILL.md) · [`brand-identity`](../../skills/brand-identity/SKILL.md) · [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) · [`brand-audit`](../../skills/brand-audit/SKILL.md) · [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md) — the skills these commands invoke.
+- [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md) — `brand` cluster registration.

package/dist/agent-src/commands/check-current-md.md

@@ -37,7 +37,7 @@ Stop here.
 ### 2. Run the checker
 
 ```bash
-python3 scripts/check_md_language.py <path> [<path> …] --format json
+./scripts-run src/scripts/check_md_language <path> [<path> …] --format json
 ```
 
 Exit codes:
@@ -105,7 +105,7 @@ Edit only the source-of-truth file:
 After all fixes, re-run:
 
 ```bash
-python3 scripts/check_md_language.py <path> [<path> …]
+./scripts-run src/scripts/check_md_language <path> [<path> …]
 ```
 
 ### 6. Mark hashes (only if `.agent-src.uncondensed/` was edited)
@@ -113,7 +113,7 @@ python3 scripts/check_md_language.py <path> [<path> …]
 For each modified source file:
 
 ```bash
-python3 scripts/condense.py --mark-done "{relative_path}"
+./scripts-run src/scripts/condense --mark-done "{relative_path}"
 ```
 
 This keeps `.condensation-hashes.json` consistent with the new content.

package/dist/agent-src/commands/condense.md

@@ -112,7 +112,7 @@ For each changed `.md` file:
 7. **MANDATORY: Run condensation quality check on this file:**
 
 ```bash
-python3 scripts/check_condensation.py --format text 2>&1 | grep "{path}"
+./scripts-run src/scripts/check_condensation --format text 2>&1 | grep "{path}"
 ```
 
 If the output contains 🔴 (error) for this file: **STOP. Fix the condensed file before continuing.**
@@ -146,7 +146,7 @@ bash scripts/condense.sh --check
 Must show ✅ (hashes in sync).
 
 ```bash
-python3 scripts/check_condensation.py
+./scripts-run src/scripts/check_condensation
 ```
 
 Must show **zero 🔴 errors**. Warnings (🟡) are acceptable.

package/dist/agent-src/commands/council/debate.md

@@ -87,7 +87,7 @@ to abort.
 ### 5. Invoke the CLI
 
 ```bash
-python3 scripts/council_cli.py debate <topic-path> \
+./scripts-run src/scripts/council_cli debate <topic-path> \
   --output agents/runtime/council/sessions/<date>-<slug>/ \
   --confirm \
   --rounds <N> \
@@ -114,7 +114,7 @@ After all rounds complete, render the last round's JSON via
 `/council` render flow:
 
 ```bash
-python3 scripts/council_cli.py render agents/runtime/council/sessions/<dir>/debate-round-<N>.json
+./scripts-run src/scripts/council_cli render agents/runtime/council/sessions/<dir>/debate-round-<N>.json
 ```
 
 The debate mode uses the structured decision-lens template (Karpathy

package/dist/agent-src/commands/council/default.md

@@ -52,8 +52,8 @@ the host translates that to `--depth deep` on the CLI. If multiple
 active artefacts disagree, **deep wins** (max policy). Explicit
 `rounds:N` overrides depth.
 
-The default comes from `ai_council.min_rounds` in
-`.agent-settings.yml` (default `2` so members critique each other at
+The default comes from `defaults.min_rounds` in the resolved
+`.ai-council.yml` (default `2` so members critique each other at
 least once before convergence). **Do NOT ask the user "how many
 rounds?"** when `rounds:N` is unset or `N <= min_rounds` — proceed
 with the settings default. Ask only when the artefact is genuinely
@@ -88,16 +88,40 @@ Neutrality — context-handoff).
 
 ### 2. Check the council is configured + price table fresh
 
-Read `.agent-settings.yml` → `ai_council`:
+Council config lives in **`.ai-council.yml`**, NOT in `.agent-settings.yml`.
+The CLI (`scripts/ai_council/config.py:resolve_config_path`, per
+[ADR-093](../../../docs/decisions/ADR-093-ai-council-config-user-global.md))
+resolves it — first hit wins:
 
-- If `ai_council.enabled` is false → state that and offer to flip it
-  on. Do not flip it autonomously.
-- If no member has `enabled: true` → list the install commands
-  (`./agent-config keys:install-anthropic`, `./agent-config keys:install-openai`)
-  and stop.
-- If a member is enabled but its `*.key` file is missing or has the
-  wrong mode → tell the user which key to install. Do not fall back
-  to env vars. Ever.
+1. Project-local `<project_root>/agents/settings/.ai-council.yml` (if present).
+2. User-global `~/.event4u/agent-config/settings/.ai-council.yml` — default
+   home; one global config serves every project.
+
+Keys are **top-level** (`enabled`, `defaults:`, `members:`). No `ai_council:`
+parent block; the legacy `ai_council.*` block under `.agent-settings.yml` was
+removed in ADR-093 — never read or recommend that path for council config.
+
+```
+NEVER claim the council "needs `.agent-settings.yml` set up" or an
+`ai_council` block. The CLI's `resolve_config_path` is authoritative:
+run `council:estimate` (Step 3) and read its exit code + message before
+making any "not configured" claim. A user-global `.ai-council.yml` with
+`enabled: true` works from EVERY project, including consumer repos that
+have no project-local config.
+```
+
+CLI is the single source of truth for the configured-check — do not hand-parse
+the YAML to second-guess it. Map its outcomes (Step 4 exit codes + the
+**CLI exits 2** cases below):
+
+- `enabled: false` (top-level in resolved `.ai-council.yml`) → CLI exits 2 with
+  `ai_council.enabled is false`. State that, offer to flip it on. Do not flip
+  it autonomously.
+- No member has `enabled: true` (under top-level `members:`) → list install
+  commands (`./agent-config keys:install-anthropic`,
+  `./agent-config keys:install-openai`) and stop.
+- A member is enabled but its `*.key` file is missing or wrong-mode → tell the
+  user which key to install. Do not fall back to env vars. Ever.
 
 Load the price table via `scripts.ai_council.pricing.load_prices()`
 (auto-bootstraps `agents/runtime/.agent-prices.md` from defaults if missing). Run
@@ -172,8 +196,8 @@ Once the user picks `1`, invoke the same arguments with `run` plus
     [--original-ask "<framing sentence>"]
 ```
 
-`--rounds` defaults to `ai_council.min_rounds` from
-`.agent-settings.yml` (or `2` if unset). Pass `--rounds N` only when
+`--rounds` defaults to `defaults.min_rounds` from the resolved
+`.ai-council.yml` (or `2` if unset). Pass `--rounds N` only when
 the user explicitly asked for a different count or a complex
 artefact justifies more depth — do not pass `--rounds 1` to "save
 money" by default; the settings owner already chose `min_rounds`.
@@ -181,15 +205,15 @@ money" by default; the settings owner already chose `min_rounds`.
 `--depth` defaults to `standard`. Set `--depth deep` when the
 active rule, skill, or command declares `council_depth: deep` in
 its frontmatter; the floor becomes
-`max(ai_council.deep_min_rounds, ai_council.min_rounds)` (default
+`max(defaults.deep_min_rounds, defaults.min_rounds)` (default
 `3`). If `--rounds N` is also passed, `--rounds` wins.
 
 The CLI:
 
 - bundles the artefact via `scripts.ai_council.bundler` (redaction +
   size guard — `BundleTooLarge` exits 2 with the byte count),
-- builds members from `.agent-settings.yml` (refusing if
-  `ai_council.enabled` is false or no member is wired up),
+- builds members from the resolved `.ai-council.yml` (refusing if
+  top-level `enabled` is false or no member is wired up),
 - detects project context via `detect_project_context()`,
 - calls `orchestrator.consult(...)` with the `cost_budget` from
   settings,
@@ -253,8 +277,11 @@ council can act on the project directly.
 
 ## Failure modes
 
-- **CLI exits 2, "ai_council.enabled is false"** → tell the user how
-  to flip it on; do not flip it autonomously.
+- **CLI exits 2, "ai_council.enabled is false"** → tell the user to set
+  top-level `enabled: true` in the resolved `.ai-council.yml` (user-global
+  `~/.event4u/agent-config/settings/.ai-council.yml`, or project-local
+  `<project_root>/agents/settings/.ai-council.yml`) — never in
+  `.agent-settings.yml`. Do not flip it autonomously.
 - **CLI exits 2, "no council member has `enabled: true`"** → list the
   install commands (`./agent-config keys:install-anthropic`,
   `./agent-config keys:install-openai`) and stop.

package/dist/agent-src/commands/fix/portability.md

@@ -23,7 +23,7 @@ packs:
 ### 1. Run the portability checker
 
 ```bash
-python3 src/scripts/check_portability.py --format json
+./scripts-run src/scripts/check_portability --format json
 ```
 
 ### 2. Parse findings
@@ -88,7 +88,7 @@ Edit files in `.agent-src.uncondensed/`, then run `bash src/scripts/condense.sh
 After all fixes, re-run:
 
 ```bash
-python3 src/scripts/check_portability.py
+./scripts-run src/scripts/check_portability
 ```
 
 ### 6. Mark hashes
@@ -96,7 +96,7 @@ python3 src/scripts/check_portability.py
 For each modified file:
 
 ```bash
-python3 src/scripts/condense.py --mark-done "{relative_path}"
+./scripts-run src/scripts/condense --mark-done "{relative_path}"
 ```
 
 ## Rules

package/dist/agent-src/commands/fix/refs.md

@@ -23,7 +23,7 @@ packs:
 ### 1. Run the reference checker
 
 ```bash
-python3 src/scripts/check_references.py --format json
+./scripts-run src/scripts/check_references --format json
 ```
 
 ### 2. Parse findings
@@ -83,7 +83,7 @@ Edit files in `.agent-src.uncondensed/` (source of truth). Regenerate `dist/agen
 After all fixes:
 
 ```bash
-python3 src/scripts/check_references.py
+./scripts-run src/scripts/check_references
 ```
 
 Show final result.
@@ -93,7 +93,7 @@ Show final result.
 For each modified file:
 
 ```bash
-python3 src/scripts/condense.py --mark-done "{relative_path}"
+./scripts-run src/scripts/condense --mark-done "{relative_path}"
 ```
 
 ## Rules

package/dist/agent-src/commands/implement-ticket.md

@@ -25,22 +25,51 @@ packs:
 
 ### 1. Resolve input
 
-Accept one of four input paths:
+Accept one of five input paths:
 
 1. **Explicit key** — `/implement-ticket PROJ-123`
 2. **Branch detection** — no arg → `git branch --show-current` + regex
    `[A-Z]+-[0-9]+`
 3. **Pasted text** — markdown block under the command
 4. **URL** — `/implement-ticket https://…/browse/PROJ-123`
+5. **Local ticket bundle** — a path to a bundle ticket file,
+   `/implement-ticket agents/tickets/{slug}/T-NNN-….md` (the
+   ticket-bundle artifact from [`emit-tickets`](emit-tickets.md);
+   format: [`ticket-bundle-format`](../docs/contracts/ticket-bundle-format.md)).
 
 For paths 1, 2, 4: run steps 1-3 of the [`jira-ticket`](jira-ticket.md) command
 (extract ID, fetch ticket, scan for Sentry links). For path 3: parse the pasted
-markdown. If no input resolves:
+markdown. For path 5: parse the bundle ticket — its YAML frontmatter +
+Markdown body map straight onto the work-state envelope with **no engine
+schema fork** (`input.data = {id, title, body, acceptance_criteria}`; the
+ticket `acceptance` list → `acceptance_criteria`, the body → `body`). Then
+apply the **bundle-mode guards** in §1a before driving the engine. If no
+input resolves:
 
 ```
 🎫 Which ticket should I implement? Paste a key, URL, or the ticket text.
 ```
 
+### 1a. Bundle-mode guards (path 5 only)
+
+When the input is a local ticket bundle, three guards run **before** the
+engine — they make a `lite`-tier build safe (per
+[`ADR-101`](../../docs/decisions/ADR-101-ticket-bundle-emission.md)):
+
+- **Dependency-driven selection.** Read the bundle `manifest.yml`
+  `dependency_graph`. Only build a ticket whose `blocked_by` are all
+  `done`. If a dependency is open, STOP and surface it — never build
+  out of order.
+- **Pre-build staleness gate.** Run
+  `python3 src/scripts/lint_ticket_buildable.ts` on the bundle. An
+  `adr_refs` SHA drift is a **hard** stop ("re-emit the bundle"); a
+  `source_refs` SHA drift only **warns** and proceeds (split severity).
+- **Boundary guard.** Carry the ticket's `boundaries`
+  (`must_touch` / `may_touch` / `must_not_touch`) into the
+  `apply-plan` and `review-changes` directives (§4). Any changeset file
+  outside `must_touch ∪ may_touch` HALTS with an escalation surface —
+  prose "do not touch" does not bind a cheap agent; this guard does.
+
 ### 2. Prepare the state file
 
 The engine persists everything in a JSON state file (default:
@@ -59,10 +88,11 @@ Three cases, in this order:
   ./agent-config migrate
   ```
 
-  Unified `migrate` writes `.work-state.json`, renames source to
-  `.implement-ticket-state.json.bak`, sweeps other legacy install
-  artefacts (see `docs/contracts/migrate-command.md`). Idempotent and
-  safe to skip if already done. After this, treat the run as **Resume**.
+  The unified `migrate` command writes `.work-state.json`, renames the
+  source to `.implement-ticket-state.json.bak`, and sweeps any other
+  legacy install artefacts in the same pass (see
+  `docs/contracts/migrate-command.md`). Idempotent and safe to skip if
+  already done. After this, treat the run as **Resume**.
 - **Fresh run** — no state file at all. Write the resolved ticket to
   `ticket.json` (id, title, body, acceptance_criteria) and pass it via
   `--ticket-file ticket.json`. Honour `roles.active_role` from

package/dist/agent-src/commands/knowledge/cross-repo.md

@@ -45,7 +45,7 @@ concept (≥ 1 term > 2 chars). A `--path-scope` glob narrows the search and is
 ### 2. Run the retrieval
 
 ```bash
-python3 scripts/cross_repo_retrieve.py "<query>" [--path-scope <glob>] [--max-chunks 8]
+./scripts-run src/scripts/cross_repo_retrieve "<query>" [--path-scope <glob>] [--max-chunks 8]
 ```
 
 The script reads opted-in siblings only, runs a targeted path-glob + content

package/dist/agent-src/commands/memory/add.md

@@ -111,7 +111,7 @@ On confirmation:
 ### 6. Cross-link
 
 If the entry has a `references:` block pointing to a skill, rule, or
-ADR file, run `python3 scripts/check_references.py` to verify the
+ADR file, run `./scripts-run src/scripts/check_references` to verify the
 link resolves. Broken link → block and ask the user to fix.
 
 ## When to reject

package/dist/agent-src/commands/mission/upgrade.md

@@ -0,0 +1,182 @@
+---
+model_tier: medium
+name: mission-upgrade
+pack: engineering-base
+intent: "Upgrade a Laravel application one major version (10→11, 11→12) via the gated /work engine with a structured breaking-change catalog"
+routes_to: [dependency-upgrade]
+replaces: []
+tier: 1
+visibility: advanced
+skills: [dependency-upgrade]
+framework: laravel
+description: Gated Laravel major-version upgrade mission — provisional branch, breaking-change catalog, size-tier surfaced, git-as-rollback. Never auto-commits or auto-PRs.
+suggestion:
+  eligible: true
+  trigger_description: "upgrade Laravel to version X, Laravel 10 to 11 upgrade, bump framework major version"
+  trigger_context: "composer.json present with a laravel/framework constraint and user asks for a major version bump"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - engineering-base
+disable-model-invocation: true
+---
+
+# /mission:upgrade
+
+## Overview
+
+Structured, catalog-driven Laravel major-version upgrade through the existing gated `/work` engine. **Not** a new autonomous runtime:
+
+- Every phase uses `/work`'s confidence-band gating, N=3 retry budget, persisted `.work-state.json`.
+- Rollback = git. Changes land on a provisional branch (`mission/upgrade-…`); revert is `git reset` or `git revert`, never a daemon.
+- No auto-commit, no auto-PR. User reviews before anything is staged.
+
+## Single-mission-per-branch guard
+
+Before starting, confirm:
+
+1. Working tree clean (`git status --porcelain` empty).
+2. No other `mission/*` branch checked out.
+3. No `.work-state.json` with a mission envelope present.
+
+Any fail → surface the conflict and stop. Run:
+
+```bash
+python3 src/scripts/lint_missions.ts --check-precondition upgrade .
+```
+
+(Currently a documented stub — full live-repo check lands in Phase 1 PoC.)
+
+## Inputs
+
+| Input | Required | Description |
+|---|---|---|
+| `target_version` | Yes | Target major version to upgrade to (`11`, `12`, …) |
+| `framework` | No (default: `laravel`) | Framework slug — auto-detected from `composer.json` |
+
+## Execution flow
+
+### 1. Resolve inputs
+
+Accept inline arguments:
+
+```
+/mission:upgrade 11
+/mission:upgrade target_version=11 framework=laravel
+```
+
+`target_version` missing → ask once (numbered options per [`user-interaction`](../../rules/user-interaction.md)).
+
+### 2. Surface the size tier
+
+Read `size_tier` from `src/missions/upgrade/mission.yaml`; display before starting:
+
+```
+> Mission: upgrade Laravel {from} → {target_version}
+> Size tier: standard (touches public API and configuration)
+> Provisional branch: mission/upgrade-laravel-{from}-to-{target_version}
+>
+> 1. Proceed on a new branch
+> 2. Adjust size tier — I'll override
+> 3. Abort
+```
+
+`standard` is the floor for upgrade missions (public API + config changes).
+
+### 3. Create the provisional branch
+
+```bash
+git checkout -b mission/upgrade-laravel-{from}-to-{target_version}
+```
+
+Per [`scope-control`](../../rules/scope-control.md), requires explicit user confirmation (step 2 provides it).
+
+### 4. Load the breaking-change catalog
+
+Read `src/missions/upgrade/laravel-10-to-11.yaml` (or the matching version). Lists breaking changes with `detection`, `fix`, `verification` command blocks restricted to safe prefixes (`composer`, `php`, `php artisan`, `git`, `sed`, `rector`, `vendor/bin/*`).
+
+### 5. Drive the /work engine
+
+```bash
+./agent-config work \
+    --state-file .work-state.json \
+    --prompt-file prompt.txt
+```
+
+Write a structured prompt to `prompt.txt` describing the mission phases (`analyze` → `plan` → `implement` → `test` → `verify` → `report`) referencing the catalog entries the engine should address.
+
+**Candidate phase (opt-in, never auto-on):** the `test` → `verify` step MAY use
+[`verify-repair-loop`](../../skills/verify-repair-loop/SKILL.md) when the upgrade's
+catalog fixes are test-driven — a bounded generate→run→revise→re-run loop gated by
+a numeric threshold (then a judge confirms), reusing the same N=3 cap. Use
+test/quality verdicts only; the live-app Playwright verdict stays deferred. The
+loop is multi-turn reasoning, not a runtime — honors
+[`no-runtime-boundary`](../../docs/contracts/no-runtime-boundary.md) exactly as the
+mission does.
+
+Handle exit codes per the `/work` contract:
+
+| Exit | Meaning | Action |
+|---|---|---|
+| `0` | SUCCESS — final report on stdout | Go to step 6 |
+| `1` | BLOCKED — halt surface on stdout | Inspect `questions[0]`, respond, re-run |
+| `2` | Config/IO error | Surface stderr to the user, stop |
+
+### 6. Rollback path
+
+Fix step fails beyond the N=3 budget:
+
+```bash
+git revert HEAD        # revert the last mission commit
+# or
+git reset --hard HEAD~1  # if no remote tracking the branch yet
+```
+
+Rollback is always manual — the mission surfaces the command, never auto-runs it.
+
+### 7. Final report and close-prompt
+
+On `/work` exit `0`, surface the delivery report unchanged, then append:
+
+```
+> Mission: upgrade complete. Review the changes on branch mission/upgrade-…
+>
+> 1. /commit — stage + commit per the delivery report
+> 2. /create-pr — open a pull request from this branch
+> 3. Keep working — hold the state file for follow-up
+> 4. Discard — delete .work-state.json and reset the branch
+```
+
+Per [`scope-control`](../../rules/scope-control.md), git operations are permission-gated. Never run `/commit` or `/create-pr` without the user choosing them.
+
+## Rules
+
+- Honour [`scope-control`](../../rules/scope-control.md), [`non-destructive-by-default`](../../rules/non-destructive-by-default.md), [`minimal-safe-diff`](../../rules/minimal-safe-diff.md), [`verify-before-complete`](../../rules/verify-before-complete.md).
+- Every catalog `command:` field is restricted to the safe-prefix allowlist. Never run arbitrary shell from the catalog.
+- The N=3 retry budget from [`autonomous-execution`](../../rules/autonomous-execution.md) applies per breaking-change fix step, not per mission.
+- Never skip the size-tier surface step — user must see scope before the provisional branch is created.
+
+## Breaking-change catalog
+
+Knowledge source: `src/missions/upgrade/laravel-10-to-11.yaml`. Versionable, diffable, CI-tested via `lint_missions.py`. Each entry carries:
+
+- `id` — unique checkpoint key (used in `.work-state.json`)
+- `severity` — `critical` / `high` / `medium` / `low`
+- `detection` — how to check if this change affects the project
+- `fix` — how to apply the fix (may reference a Rector rule)
+- `verification` — how to confirm the fix is complete
+
+## See also
+
+- [`/work`](../../work/command.md) — the gated engine this mission drives
+- [`dependency-upgrade`](../../skills/dependency-upgrade/SKILL.md) — the stack-agnostic upgrade skill this mission specialises
+- `src/missions/upgrade/mission.yaml` — the mission manifest
+- `src/missions/upgrade/laravel-10-to-11.yaml` — the breaking-change catalog
+- `src/scripts/lint_missions.ts` — validates the manifest and catalog
+
+## Examples
+
+```
+/mission:upgrade 11
+/mission:upgrade target_version=11
+```

package/dist/agent-src/commands/optimize/skills.md

@@ -28,7 +28,7 @@ Skill audit: measure, find duplicates/merge candidates, run linter, present find
 ### 1. Measure baseline
 
 ```bash
-total=$(ls -d .agent-src.uncondensed/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+total=$(ls -d src/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
 total_lines=$(cat .agent-src.uncondensed/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
 echo "Skills: $total, Total lines: $total_lines"
 
@@ -43,7 +43,7 @@ done | sort -rn | head -15
 ### 2. Run skill linter
 
 ```bash
-python3 scripts/skill_linter.py --pairs --duplicates .agent-src.uncondensed/skills/*/SKILL.md 2>&1 | tail -20
+./scripts-run src/scripts/skill_linter --pairs --duplicates src/skills/*/SKILL.md 2>&1 | tail -20
 ```
 
 Report FAIL/WARN counts. Do NOT fix linter issues here — that's the linter's or `skill-reviewer`'s job.

package/dist/agent-src/commands/orchestrate.md

@@ -44,7 +44,7 @@ side; this command reads the same shape and dispatches each step.
 Run the linter against the resolved file:
 
 ```
-python3 scripts/lint_orchestration_dsl.py --file <path>
+./scripts-run src/scripts/lint_orchestration_dsl --file <path>
 ```
 
 Exit code ≠ 0 → surface the linter output and stop. **Never** run

package/dist/agent-src/commands/pr/create.md

@@ -74,12 +74,14 @@ Run, in order:
 | Behind | Overlapping open PR touches same files? | Action |
 |---|---|---|
 | `0` | — | Proceed to Step 2 |
-| `1–N` | No | Surface the count, ask: rebase / merge-main / proceed-anyway / cancel |
+| `1–N` | No | **Merge `origin/main` in** — `git merge origin/{target-base} --no-edit` — then proceed. No need to ask; state that you did it. Abort + surface only on conflict. |
 | `1–N` | **Yes** | STOP — surface the overlapping PR number, ask: stack on top of it / wait for it to land / proceed-anyway-and-accept-conflicts / cancel |
 
-Never improvise the base or silently proceed when the branch is behind
-and overlap exists. The 10-second fetch beats hours of rebase
-reconciliation after the parent PR lands.
+A branch behind its base is **not** current — bring `main` in **before** the PR
+exists, never after. Auto-merge when there is no file overlap (the common case);
+only ask when an overlapping open PR makes the base genuinely ambiguous. Never
+improvise the base or silently proceed when behind **and** overlapping. The
+10-second fetch beats hours of rebase reconciliation after the parent PR lands.
 
 ### 1c. PR-gate — archive completed roadmaps (MANDATORY)