@event4u/agent-config 7.5.0 → 8.1.0

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

@@ -0,0 +1,243 @@
+---
+model_tier: high
+name: optimize-project
+pack: engineering-base
+tier: 2
+visibility: internal
+skills: [project-analyzer, decision-review, roadmap-writing]
+description: "Project-wide optimization sweep — inventory roadmaps, ADRs, agent folders (incl. modules), challenge stale decisions with the user in the loop, emit new roadmap(s). E.g. 'optimize this project'."
+suggestion:
+  eligible: true
+  trigger_description: "optimize this project, optimize the project, what should we improve based on current state, challenge our old decisions, are our roadmaps and ADRs still right, optimiere das Projekt, hinterfrag unsere alten Entscheidungen"
+  trigger_context: "user wants a project-wide review that questions existing state (roadmaps, ADRs, decisions, structures) and ends in new roadmap(s) — NOT a bug fix, NOT a single-decision audit (/analyze:decision), NOT agent-layer tooling (/optimize)"
+workspaces:
+  - engineering
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /optimize-project
+
+Project-wide optimization loop: **inventory → challenge → interview →
+roadmap(s)**. Analyzes project it runs in (package or consumer),
+questions existing state — roadmaps, ADRs, decisions, structures, in
+this package e.g. token consumption, memory, learnings — asks user
+when flipping old decision would be real improvement, ends by emitting
+one or more NEW roadmaps via `/roadmap:create`.
+
+**Coordinator** over existing primitives — composes, never
+reimplements: `/project-health`-style inventory, `/challenge-me`
+interview mechanics, `/analyze:decision`-style decision challenge,
+`/roadmap:create` output.
+
+> Looking for agent-layer tooling (skills, agents-dir, augmentignore,
+> rtk filters)? That is the [`/optimize`](optimize.md) cluster —
+> different surface. This command optimizes the **project**, not the
+> agent layer.
+
+## When to invoke
+
+- "Optimize this project" / "optimiere das Projekt".
+- "What should we improve based on the current state?"
+- "Challenge our old decisions" / "are our roadmaps and ADRs still right?"
+- Periodic hygiene: roadmaps accumulated, decisions feel stale,
+  structures grew organically, nobody questioned them.
+
+Do NOT invoke for: single named bug ("fix this"), single decision
+audit (route to `/analyze:decision`), code-only analysis
+(`/project-analyze`), AGENTS.md / agent-layer work (`/agents`,
+`/optimize`).
+
+## Steps
+
+### Step 0 — Scope detection (read-only)
+
+1. Detect target type:
+   - **Package mode** — repo IS `event4u/agent-config` (marker:
+     `src/config/budgets.yml` + `dist/agent-src/` present). Optimization
+     surface additionally: token budget, memory index,
+     learnings/knowledge corpus, lint debt.
+   - **Consumer mode** — any other project with `agents/` tree and/or
+     installed agent layer. Surface = workflows, structures, docs,
+     roadmaps, decisions.
+2. Resolve module roots via
+   `scripts/_lib/agent_settings.py::enumerate_modules()` (Laravel shape:
+   `app/Modules/*/agents/`); fallback `modules.root_paths` in
+   `.agent-settings.yml`.
+3. Exclusions hard: never analyze `vendor/`, `node_modules/`, `dist/`,
+   any generated projection (`.augment/`, `.claude/`, `.cursor/`).
+
+### Step 1 — Inventory (read-only, parallel)
+
+Gather without creating or modifying anything:
+
+- **Roadmaps** — `agents/roadmaps/` (+ per-module roadmap dirs): counts
+  per disposition (active / `later/` / `skipped/` / `archive/`),
+  per-roadmap open/done/deferred checkbox counts, staleness
+  (mtime > 60 days with open items), complete-but-unarchived.
+- **Decisions** — ADR dirs (`docs/adr/`, `docs/decisions/`,
+  `agents/decisions/`): count, age distribution, `status:` fields,
+  superseded chains.
+- **Agent folders** — `agents/` root + every module `agents/` folder:
+  docs, features, contexts; orphaned or stale files (referencing
+  deleted code).
+- **Memory / learnings** (if present) — memory index size, knowledge
+  cards, low-impact decisions corpus; entries whose subject no longer
+  exists in repo.
+- **Package mode only** — budget usage vs cap
+  (`src/config/budgets.yml`), kernel share, corpus size trends, known
+  lint debt, honest-null / don't-relitigate lock inventory (memory
+  index + `agents/settings/contexts/`).
+
+Emit compact inventory report (counts + flagged items), in user's
+language. Present findings incrementally, not one dump.
+
+### Step 2 — Findings & challenge candidates
+
+Classify everything flagged in Step 1 into three buckets:
+
+1. **Mechanical optimizations** — no decision needed, just work: stale
+   roadmap cleanup, complete-but-unarchived roadmaps, dead references,
+   missing module docs, memory entries pointing at deleted code.
+2. **Decision-challenge candidates** — existing decision (ADR, lock,
+   council verdict, structural convention) whose original assumptions
+   may no longer hold. Per candidate record: *the decision · original
+   assumption · what changed since · expected gain from flipping · flip
+   cost/blast radius*. Candidate without concrete "what changed" is not
+   a candidate — drop it.
+3. **Structural / process improvements** — recurring friction visible
+   in inventory (e.g. roadmap sprawl, duplicate contexts, token
+   hot-spots in package mode).
+
+Rank by expected impact vs. effort. **Cap decision-challenge list at
+top 5** (override: `--max-questions=N`). Everything below cap carries
+into Step 4 as "further candidates" — never silently dropped.
+
+Before a candidate built on a claim about current state enters the
+interview, verify the claim against the real source (grep, file read,
+live git/CI state) per
+[`source-discovery-gate`](../rules/source-discovery-gate.md) —
+never challenge a decision from a remembered or assumed fact.
+
+### Step 3 — Challenge interview (user-gated, budgeted)
+
+One question per turn, numbered options with recommendation —
+`/challenge-me` mechanics, per
+[`ask-when-uncertain`](../rules/ask-when-uncertain.md) and
+[`user-interaction`](../rules/user-interaction.md).
+
+Per candidate, present:
+
+```
+> **Decision:** <what was decided, where it is recorded>
+> **Then:** <original assumption>
+> **Now:** <what changed — with evidence source>
+> **Gain if flipped:** <expected improvement> · **Cost:** <blast radius>
+>
+> 1. Keep — assumptions still hold
+> 2. Flip — schedule the change in the output roadmap
+> 3. Re-evaluate via council — genuinely contested, worth a multi-model pass
+> 4. Defer — park as "further candidate"
+```
+
+Hard rules for this step:
+
+- **Locked decisions are never silently flipped.** Honest-null verdict,
+  "don't relitigate" note, budget-canon line, or locked council
+  convergence follows
+  [`decision-revisit-gate`](../rules/decision-revisit-gate.md):
+  check the lock's mechanism/scope actually matches the proposed change
+  and its recorded revisit-conditions first; if it truly blocks, the
+  only flip path offered is option 3 (council re-eval) — "Flip" is not
+  offered for locks.
+- **Session budget:** max 5 interview questions by default
+  (`--max-questions=N` to override). Budget exhausted → remaining
+  candidates go to Step 4 as "further candidates".
+- Interview answers adopted immediately; never re-argue a settled
+  answer.
+
+### Step 4 — Synthesize → roadmap(s)
+
+1. Group accepted work — mechanical optimizations + flipped decisions +
+   structural improvements — into **one or more roadmaps by concern**
+   (keep k small; one roadmap per coherent theme, not one per finding).
+2. For each group, route to [`/roadmap:create`](roadmap/create.md)
+   with structured seed: goal, findings (with evidence), accepted
+   interview decisions, "further candidates" section for uninterviewed
+   remainder.
+3. Council re-evals chosen in interview (option 3) land as explicit
+   first step in the matching roadmap — do NOT auto-run the council
+   from here.
+4. Regenerate roadmap dashboard in same reply
+   (`./agent-config roadmap:progress`) per
+   [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md).
+5. **Hand back and stop.** Per
+   [`scope-control § Authoring vs. implementation`](../rules/scope-control.md)
+   the roadmap is the deliverable — never auto-offer
+   `/roadmap:process-*` or start executing.
+
+## Output
+
+1. **Inventory report** (Step 1) — compact counts + flagged items.
+2. **Findings report** (Step 2) — three buckets, ranked, with
+   challenge-candidate cards.
+3. **Interview** (Step 3) — one question per turn, ≤ budget.
+4. **Roadmap file(s)** (Step 4) — the only files this command creates,
+   via `/roadmap:create`, plus dashboard regen.
+
+## Rules
+
+- **Read-only until Step 4.** Only writes: new roadmap file(s) +
+  dashboard regen. No code edits, no doc rewrites, no deletion —
+  cleanup work becomes roadmap steps, not inline actions.
+- **Never edit or delete existing roadmaps / ADRs / decisions** —
+  flipped decision becomes a roadmap step ("supersede ADR-NNN with …"),
+  never an in-place edit from this command.
+- **No commits, no push, no PR** — [`commit-policy`](../rules/commit-policy.md).
+- **Never silently flip a lock** — [`decision-revisit-gate`](../rules/decision-revisit-gate.md).
+- **One question per turn**, recommendation line under every options
+  block.
+- Mirror user's language in all reports and questions.
+
+## Gotchas
+
+- **Unbounded interview** — without question budget the decision-flip
+  loop can eat the session. Cap is load-bearing; don't lift silently.
+- **Re-litigating without new evidence** — challenge candidate needs
+  concrete "what changed". "I would decide differently today" is not
+  evidence; check the lock's recorded revisit-conditions first.
+- **Scope bleed into `/optimize`** — token/skill/agents-dir tooling
+  findings in package mode are reported, but their execution routes to
+  `/optimize` cluster sub-commands inside the output roadmap.
+- **Roadmap sprawl as output** — five roadmaps for one theme recreates
+  the problem this command fixes. Group by concern.
+- **Vendor noise** — module enumeration comes from
+  `enumerate_modules()`, never a bare glob that catches `vendor/`.
+
+## Do NOT
+
+- Do NOT execute any found optimization in this command's turn — the
+  roadmap is the deliverable.
+- Do NOT auto-run a council session; record it as a roadmap step.
+- Do NOT offer "Flip" on locked decisions — council re-eval only.
+- Do NOT create analysis files (that is `/project-analyze`); this
+  command creates roadmaps only.
+- Do NOT re-ask a settled interview answer.
+
+## See also
+
+- [`/optimize`](optimize.md) — agent-layer tooling cluster (skills,
+  agents-dir, augmentignore, rtk); cross-linked on purpose — closest
+  name, different surface.
+- [`/project-analyze`](project-analyze.md) — deep code/stack analysis
+  with analysis-file output.
+- [`/project-health`](project-health.md) — quick read-only counts, no
+  challenge loop.
+- [`/analyze:decision`](analyze/decision.md) — single-decision audit;
+  this command sweeps and hands hot ones to the interview.
+- [`/challenge-me with-docs`](challenge-me/with-docs.md) — interview
+  mechanics this command borrows, applied to a seed instead of the
+  project state.
+- [`decision-revisit-gate`](../rules/decision-revisit-gate.md) —
+  lock-flip discipline Step 3 enforces.

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

@@ -27,6 +27,11 @@ Top-level orchestrator for the `/optimize` family.
 
 > Looking for `AGENTS.md` operations (init, refactor, audit)? Those
 > live under [`/agents`](agents.md) (`init / optimize / audit`).
+>
+> Looking for **project-wide** optimization (roadmaps, ADRs, decisions,
+> structures — challenge-and-roadmap loop)? That is the standalone
+> [`/optimize-project`](optimize-project.md) — this cluster only covers
+> the agent layer.
 
 ## Sub-commands
 

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

@@ -92,7 +92,7 @@ trunk (that rot is exactly what the PR-gate replaces; see
 Run the deterministic sweep:
 
 ```bash
-python3 .augment/scripts/archive_completed_roadmaps.py   # --changed-only (default)
+./agent-config roadmap:archive   # --changed-only (default)
 ```
 
 It `git mv`s each completed roadmap (that this branch touched, per
@@ -178,7 +178,7 @@ github-api
 
 **Hard prohibitions** (each one cost 3+ extra tool calls in past runs):
 
-- ❌ `python3 -c "import urllib..."` / `python3 - <<PY ... PY` heredocs
+- ❌ `node -e "..."` / shell heredoc hacks
   to serialize the body or POST it.
 - ❌ `save-file PR_BODY.md` → read back → `curl -d @PR_BODY.md`.
 - ❌ `gh pr create --body-file …` shelling out when `github-api` is
@@ -252,24 +252,53 @@ Per `verbosity.post_action_reports` (default `minimal`):
   \`gh pr ready N\` to flip` when silent-draft (rule 4); omit on ready.
 - `full` → multi-line: PR number, URL, draft state, base/head, ready-reminder.
 
-#### 4c. Jira transition (only when transitioned)
+#### 4c. Status claims — verified facts only (MANDATORY)
+
+```
+NEVER STATE CI, CHECK, MERGEABILITY, OR DRAFT STATUS FROM ASSUMPTION.
+EVERY STATUS CLAIM IN THE REPLY CITES A COMMAND RUN THIS TURN.
+"BLOCKED" IS NEVER PARAPHRASED AS "CI IS STILL RUNNING".
+```
+
+Any statement about the PR's state — in the creation reply, after a
+conflict-resolution push, after ANY push to the PR branch — must be
+backed by fresh command output from the same reply:
+
+| Claim | Required evidence |
+|---|---|
+| Draft / ready | `gh pr view <n> --json isDraft` — quote the value |
+| CI green / red / running | `gh pr checks <n>` — report the actual fail list; a single `fail` row means FAIL, not "running" |
+| Mergeable / conflicts | `gh pr view <n> --json mergeable,mergeStateStatus` |
+
+`mergeStateStatus: BLOCKED` has several distinct causes (failing
+checks, draft state, missing reviews, branch protection). Resolving
+WHICH one requires `gh pr checks` — never guess the cause. If checks
+are still pending, say "pending" and name the pending jobs; never
+declare an outcome the output does not show.
+
+This is the [`direct-answers` Iron Law 2](../rules/direct-answers.md)
+live-state clause applied to the PR surface: git/PR/CI state decays
+silently and is NEVER reported from memory or inference.
+
+#### 4d. Jira transition (only when transitioned)
 
 Linked ticket + `routine_confirmations: true` → ask `1. Yes / 2. No`.
 Default (`false`) → skip silently. **Only emit a transition line when
 an actual Jira API call succeeded** — never announce "skipped".
 
-#### 4d. Settings short-circuit — single read per run
+#### 4e. Settings short-circuit — single read per run
 
 `verbosity.routine_confirmations`, `verbosity.post_action_reports`, and
 `commands.create_pr.preview_description` are read **once** at the top
 of the run and cached for the whole `/create-pr` invocation. Do **not**
-re-read `.agent-settings.yml` in 4b / 4c — both branches resolve from
+re-read `.agent-settings.yml` in 4b / 4d — both branches resolve from
 the cached values from step 1.
 
 When all three resolve to their silent defaults (`false` / `minimal` /
-`false`), steps 4b–4c collapse to the single `→ #N opened: <url>` line
-from 4b and a silent 4c. No extra file reads, no "checking settings…"
-narration, no confirmation prompts.
+`false`), steps 4b + 4d collapse to the single `→ #N opened: <url>` line
+from 4b and a silent 4d. No extra file reads, no "checking settings…"
+narration, no confirmation prompts. Step 4c is never collapsed — status
+claims always carry evidence.
 
 ### Rules
 

package/dist/agent-src/commands/prediction-pool.md

@@ -79,7 +79,7 @@ no silent best-guess.
 
 ### 2. Resolve the per-event analysis (state ground-truth)
 
-Look for `agents/tmp/prediction-pool/<slug>.md`.
+Look for `agents/runtime/tmp/prediction-pool/<slug>.md`.
 
 - **None →** start a new analysis (created at Step 9, never before).
 - **Exists →** read it. Then:
@@ -178,7 +178,7 @@ pool / site. If yes, loop Steps 3–7 for that pool.
 
 ### 9. Persist / extend the analysis (only now)
 
-Append a run-stamped section to `agents/tmp/prediction-pool/<slug>.md`: pool
+Append a run-stamped section to `agents/runtime/tmp/prediction-pool/<slug>.md`: pool
 URL(s), parsed rules, the entered tips with state `entered, not submitted`
 (or `submitted` if Step 7 submitted), council verdicts if any, and
 standing notes. Append-only — earlier runs stay as history. This is the

package/dist/agent-src/commands/profile/activate.md

@@ -32,7 +32,7 @@ not-installed pack, expands the `requires_hint` closure, and writes the
 overlay **atomically**):
 
 ```bash
-python3 -m scripts.config.session_profiles activate <name…> --json
+./scripts-run src/scripts/config/session_profiles activate <name…> --json
 ```
 
 - **Exit 0** → parse the JSON: `active_packs`, `closure_added`, `notes`.
@@ -49,7 +49,7 @@ Announce, using the helper's output:
 > surfaced: {N} commands, {M} skills ({H} hidden behind inactive packs)
 ```
 
-Get the counts from `python3 -m scripts.config.session_profiles show --json`.
+Get the counts from `./scripts-run src/scripts/config/session_profiles show --json`.
 
 ### 3. Re-bias the surface for the rest of the session
 
@@ -58,7 +58,7 @@ From now until `/profile deactivate` (or a new session), when the user asks
 set. Compute it with:
 
 ```bash
-python3 -m scripts.config.session_profiles surface --json
+./scripts-run src/scripts/config/session_profiles surface --json
 ```
 
 `shown` = surface these; `hidden` = do not list them proactively. Core /

package/dist/agent-src/commands/profile/deactivate.md

@@ -30,14 +30,14 @@ no silent session reset.
 - `/profile deactivate` (no args) → clear the whole overlay:
 
   ```bash
-  python3 -m scripts.config.session_profiles deactivate --json
+  ./scripts-run src/scripts/config/session_profiles deactivate --json
   ```
 
 - `/profile deactivate <name…>` → remove only the **named packs** from the
   active set (never their closure), so a shared dependency survives:
 
   ```bash
-  python3 -m scripts.config.session_profiles deactivate <name…> --json
+  ./scripts-run src/scripts/config/session_profiles deactivate <name…> --json
   ```
 
 Parse `active_packs` from the JSON.

package/dist/agent-src/commands/profile/show.md

@@ -28,7 +28,7 @@ from its cause.
 ### 1. Read the state
 
 ```bash
-python3 -m scripts.config.session_profiles show --json
+./scripts-run src/scripts/config/session_profiles show --json
 ```
 
 Fields: `active_packs`, `commands_shown`, `skills_shown`, `hidden_total`.
@@ -37,7 +37,7 @@ For a **non-technical employee**, render plain language instead — deterministi
 template (no LLM), the right content for an employee-facing surface:
 
 ```bash
-python3 -m scripts.config.session_profiles show --plain
+./scripts-run src/scripts/config/session_profiles show --plain
 ```
 
 Shape: [`session-profile-overlay` § Plain status surface](../../../../docs/contracts/session-profile-overlay.md#plain-status-surface).
@@ -64,7 +64,7 @@ Shape: [`session-profile-overlay` § Plain status surface](../../../../docs/cont
 If the user asks *which* artefacts are hidden, run:
 
 ```bash
-python3 -m scripts.config.session_profiles surface --json
+./scripts-run src/scripts/config/session_profiles surface --json
 ```
 
 and list `hidden[]` (name + packs). Keep it scannable; group by pack if long.

package/dist/agent-src/commands/research/deep.md

@@ -87,6 +87,11 @@ Read {fields_path} to get all field definitions.
    field names whose value contains `[uncertain]` or could not be
    sourced.
 4. All field values in English.
+5. Cite claims from fetched sources by paraphrase; verbatim quoting
+   follows `content-quoting-floor` (≤15 words, one quote per source).
+6. Fresh-lookup-class fields (current status, versions, prices, dates)
+   require a cited live source per `asking-and-brevity-examples § Volatile-fact
+   freshness` — never fill from model memory.
 
 ## Output path
 {output_path}

package/dist/agent-src/commands/research/report.md

@@ -80,7 +80,8 @@ script, no Python runtime.**
 | **List of dicts** | One row per dict, `key:value` pairs joined with ` \| `. |
 | **Plain list** | Short → comma-joined; long (> 5 items) → bullet list. |
 | **Nested dict** | Recurse; render with `;` between sibling keys or hard-break on long values. |
-| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. |
+| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. Verbatim source excerpts follow `content-quoting-floor` (≤15 words, one quote per source) — paraphrase the rest. |
+| **Freshness** | Fresh-lookup-class fields (status, version, price, date) render as reported by `/research:deep`, never re-derived from model memory at report time — see `asking-and-brevity-examples § Volatile-fact freshness`. |
 | **Extra fields** | JSON keys not declared in `fields.yaml` → group under `### Other info`. Filter `_source_file`, `uncertain`, and category-container keys. |
 | **`uncertain` array** | Render each entry on its own line under `### Uncertain fields`; never condense to a one-liner. |
 | **Skip conditions** | Field value contains `[uncertain]` · field name in `uncertain` · value is `null` / empty string. |

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

@@ -139,7 +139,20 @@ and ask (in the user's language):
 
 Only when the search is empty: save to the chosen location and show the final path.
 
-### 7. Update the progress dashboard
+### 7. Move consumed inbox file (if applicable)
+
+User pointed at a file in `agents/tmp/` as the roadmap source
+(e.g. "create a roadmap from `agents/tmp/my-idea.md`") →
+
+```bash
+mv agents/tmp/<filename> agents/tmp.old/<filename>
+```
+
+Automatic, same reply as saving — no confirmation (gitignored, local-only,
+reversible). Move ONLY files explicitly named as input. Never touch other
+`agents/tmp/` files.
+
+### 8. Update the progress dashboard
 
 Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
 
@@ -149,7 +162,7 @@ Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
 
 Mention the new overall count to the user.
 
-### 8. Offer council review (B1 hook, verbosity-gated)
+### 9. Offer council review (B1 hook, verbosity-gated)
 
 Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
 (default `false`):
@@ -181,21 +194,86 @@ If the user picks **1**:
 
 If the user picks **2** → continue.
 
-### 9. Offer execution
+### 10. Ask the execution mode — ONE question, then write frontmatter
 
-After saving (and any council review), ask the user (in their language) whether to start executing the roadmap immediately.
+Ask (in the user's language) exactly one numbered-options question:
+
+> How should this roadmap be executed later?
+>
+> 1. Fully autonomous — one run-start contract confirmation, then no
+>    interruptions except the safety floors
+> 2. Checkpoint at phase boundaries — compact status + continue prompt
+>    per phase
+> 3. Interactive — every gate fires as today
+>
+> **Recommendation:** 1
+
+Write the pick to frontmatter as `execution.mode:`
+(`autonomous` | `phase-checkpoints` | `interactive`). Rules:
+
+- Pick 3 → omit the field entirely (`interactive` is the absent-field
+  default; don't write noise).
+- Follow-up roadmaps (`parent_roadmap` set): pre-select the parent's
+  mode as the recommended option, but still ask — mode never inherits
+  silently (per template rule 18).
+- This question is about a **future** run's interaction pattern. It is
+  a declaration of intent, never a permission grant, and it does NOT
+  soften the step-11 hard stop: asking it must not morph into offering
+  execution now.
+- Semantics + contract mechanics:
+  [`templates/roadmaps.md` rule 18](../../templates/roadmaps.md) and
+  [`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
+- **Authoring check for pick 1 (`autonomous`):** scan the drafted steps
+  for vague phrasings (`improve/optimize` without a target, `make it
+  better/cleaner`, `clean up` without scope, `fix this` without a
+  symptom, `use best practices`, `handle errors properly`) and for
+  pre-existing `[~]` items. Surface each finding to the user for a
+  quick rephrase **before saving** — vagueness is cheap to resolve now
+  and expensive as a mid-run ambiguity halt; pre-existing `[~]` items
+  guarantee the archival gate interrupts the run.
+  `lint_roadmap_complexity` warns on the same patterns as a backstop.
+
+### 11. Hand back — HARD STOP, never auto-offer execution
+
+```
+ROADMAP SAVED → STOP. NEVER ASK "READY TO START?" / "BEGIN PHASE 1?"
+/ "SOFORT AUSFÜHREN?". CREATE = ARTIFACT ONLY. EXECUTION NEEDS A
+FRESH, EXPLICIT EXECUTION VERB FROM THE USER.
+```
 
-If yes → switch to [`/roadmap:process-phase`](process-phase.md) with
-the newly created file (the default execution scope of the `/roadmap`
-cluster). Offer [`process-step`](process-step.md) and
-[`process-full`](process-full.md) as alternatives. The legacy
-`/roadmap execute` command was removed — autonomous execution is the
-only path now.
+Emit a single hand-back line citing the saved path and (if regenerated)
+the new dashboard count. Then **stop the turn**.
+
+- Do **not** present numbered options for "start execution / pick
+  process-phase / pick process-step / pick process-full". The user
+  picks the next move when they're ready — silence on execution.
+- Do **not** soft-route ("*the roadmap is ready, kicking off E1.1…*").
+  That is a hand-off to execution disguised as a status line.
+- Do **not** include "Recommended next step: `/roadmap:process-phase`"
+  in the hand-back. Mentioning the command back-channels the same
+  ask.
+- The user resumes with an explicit execution verb (`implement`,
+  `build`, `start Phase A`, `arbeite die Roadmap ab`, `mach weiter
+  mit Phase 1`) on a **later turn**. That verb — not this command —
+  authorizes execution. See [`scope-mechanics § Post-artifact hard
+  stop`](../../contexts/authority/scope-mechanics.md).
+
+Failure modes covered by this hard stop:
+
+- Asking *"Soll ich jetzt mit Phase A anfangen?"* after the save line.
+- Offering *"1. Start now / 2. Review first / 3. Cancel"* — the user
+  did not ask for an execution menu, the create verb covered authoring
+  only.
+- Treating a thumbs-up / *"sieht gut aus"* / *"passt"* as authorization
+  to start. None of those are execution verbs.
 
 ### Rules
 
 - **Do NOT auto-generate content** — always ask the user for input.
 - **Do NOT commit or push.**
+- **Do NOT offer execution after save** — Step 11 is a hard stop.
+  Execution starts on a later turn with an explicit execution verb
+  ([`scope-control § Authoring vs. implementation`](../rules/scope-control.md#authoring-vs-implementation)).
 - **Do NOT include commit steps in the roadmap** unless the user explicitly
   requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
   Roadmaps plan **work**; commits are a separate delivery decision.

package/dist/agent-src/commands/roadmap/materialize.md

@@ -47,7 +47,7 @@ roadmap, writes one ticket per materialisable step into
 Run the build-readiness lint before handing back:
 
 ```bash
-python3 src/scripts/lint_ticket_buildable.py
+./scripts-run src/scripts/lint_ticket_buildable
 ```
 
 A `lite` ticket that fails the self-containedness floor is rejected or escalated

package/dist/agent-src/commands/roadmap/process-full.md

@@ -34,16 +34,29 @@ with the **scope delta below**.
 
 ## Scope delta
 
+- **Execution mode:** read `execution.mode` from frontmatter. Under
+  `autonomous` / `phase-checkpoints` the loop's § 3 pre-scan derives
+  the run-start **execution contract**
+  ([`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md));
+  ONE acceptance activates all run grants (feature branch, chunked
+  commits, push to that branch only, PR-open, batched artifact
+  drafting, council auto-enable) — no further asks until a safety
+  floor. `mode: autonomous` is the flagship pairing for this wrapper:
+  full working set + contract = uninterrupted run to the defined end
+  state.
 - **Working set:** every open step across every phase, in document
   order. Phase-internal annotations like `(deferred)` / `(optional)` /
   "gated on Phase N" do not narrow the working set.
 - **Stop after:** the entire roadmap reaches `count_open == 0`, or a
-  halt condition fires (Hard-Floor, council-off + ambiguity,
+  halt condition fires (Hard-Floor, council-off + ambiguity — the
+  latter only outside an accepted contract with council available,
   security-sensitive, scope-out-of-roadmap, test/quality red).
 - **Phase boundary handling:** at every phase boundary, run the
   per-phase quality pipeline when `quality_cadence: per_phase` (or
   `per_step`). On red → stop, surface, do **not** silently roll into
-  the next phase.
+  the next phase. Under `mode: phase-checkpoints`, additionally emit
+  the compact status + continue prompt at every boundary; under
+  `autonomous`, boundaries are silent (quality pipeline aside).
 - **Final archival:** when the roadmap is fully closed, run the
   archival check from
   [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).