@event4u/agent-config 2.25.0 → 3.0.0

package/.agent-src/skills/verify-completion-evidence/SKILL.md

@@ -3,6 +3,18 @@ name: verify-completion-evidence
 description: "Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs."
 source: package
 domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # verify-completion-evidence
@@ -50,9 +62,9 @@ mapping before running anything:
 | Claim | Evidence command |
 |---|---|
 | "tests pass" | full or targeted test suite |
-| "no static errors" | PHPStan / TypeScript / mypy on changed scope |
-| "style is clean" | ECS / Prettier / ESLint |
-| "no automated refactor pending" | Rector --dry-run clean |
+| "no static errors" | project's type-checker on changed scope (PHPStan, `tsc --noEmit`, mypy / pyright, `go vet`, `cargo check`) |
+| "style is clean" | project's linter + formatter (ECS / Prettier / ESLint / Ruff / Black / gofmt / rustfmt) |
+| "no automated refactor pending" | project's auto-refactor dry-run if one exists (Rector for PHP — otherwise skip this row) |
 | "endpoint works" | curl / Postman / integration test output |
 | "UI renders" | Playwright snapshot or manual browser check |
 | "bug is fixed" | regression test passes |
@@ -60,8 +72,7 @@ mapping before running anything:
 ### 2. Run the command fresh
 
 * Run against the current working tree, not a cached summary.
-* For PHP projects inside Docker: run inside the container (see
-  [`docker`](../docker/SKILL.md) and [`tests-execute`](../tests-execute/SKILL.md)).
+* If the project runs commands inside a container or VM (Docker, Devcontainer, Vagrant), run them there — not on the host. See [`docker`](../docker/SKILL.md) and [`tests-execute`](../tests-execute/SKILL.md).
 * Use targeted runs during iteration (`--filter=`, `--testNamePattern`).
   Run the full suite only in the final verification pass.
 
@@ -77,40 +88,38 @@ mapping before running anything:
 Ask: *"Does this output actually support what I am about to say?"*
 
 * 248/250 tests passed with 2 skipped → do not say "all green"; name the skips.
-* PHPStan exit 0 but only analyzed one file → do not say "no static
+* Type-checker exit 0 but only analyzed one file → do not say "no static
   errors"; name the scope that was checked.
 * `curl` returned 200 → check the body, not just the status.
 
 ### 5. Only then make the claim
 
-Reference the evidence: *"Tests: 250/250 passed. PHPStan: level 8, 0
-errors on `app/Services/`."* — not *"everything looks good"*.
+Reference the evidence: *"Tests: 250/250 passed. Type-checker: 0 errors
+on the changed scope."* — not *"everything looks good"*.
 
-## The end-of-work sequence (PHP projects)
+## The end-of-work sequence
 
 When all code changes are done and you are ready to report completion:
 
-1. **Targeted tests** — the test(s) covering the changed code pass
-2. **Full test suite** — only after targeted pass is green
-3. **PHPStan** → **Rector --dry-run** → **ECS** → **PHPStan** (second pass
-   catches issues Rector / ECS may have introduced)
-4. Fix any output from steps 1–3 and restart the sequence
-5. Only then: claim completion or suggest `/commit`, push, or PR
+1. **Targeted tests** — the test(s) covering the changed code pass.
+2. **Full test suite** — only after targeted pass is green.
+3. **Static analysis pipeline** — run the project's type-checker → auto-refactor dry-run (if any) → linter / formatter → type-checker (second pass catches issues the refactor / formatter may have introduced).
+4. Fix any output from steps 1–3 and restart the sequence.
+5. Only then: claim completion or suggest `/commit`, push, or PR.
 
-Do not run the full quality pipeline between intermediate edits — it
-burns time and tokens. Use it once, at the end.
+Do not run the full quality pipeline between intermediate edits — it burns time and tokens. Use it once, at the end.
 
-See [`quality-tools`](../quality-tools/SKILL.md) for the exact commands
-per tool.
+→ For the **exact PHP commands** (PHPStan → Rector → ECS → PHPStan): see [`quality-tools`](../quality-tools/SKILL.md).
+→ For TS / JS, Python, Go, Rust pipelines: the project's `Taskfile.yml` / `package.json scripts` / `Makefile` is the source of truth — read it before improvising.
 
 ## Minimum evidence per task type
 
 | Task type | Required evidence |
 |---|---|
-| Code change (logic) | Targeted tests + PHPStan on changed scope |
-| New feature | Tests (new + suite) + PHPStan + smoke check (curl/UI) |
+| Code change (logic) | Targeted tests + project's type-checker on changed scope |
+| New feature | Tests (new + suite) + type-checker + smoke check (curl / UI / integration probe) |
 | Bug fix | Regression test (RED → GREEN) + full suite |
-| Refactoring | Full suite + PHPStan + Rector dry-run |
+| Refactoring | Full suite + type-checker + auto-refactor dry-run if available |
 | Config / env change | Relevant command or service output (not just file diff) |
 | Migration | Migration run output + rollback dry-run + tests |
 | API endpoint | HTTP response body + status + content-type |
@@ -140,7 +149,7 @@ When reporting completion to the user:
 
 * A "no output" result from a linter is not proof it ran — check the
   exit code and the analyzed-file count.
-* Silencing a warning with `@phpstan-ignore-next-line` or `// @ts-expect-error`
+* Silencing a warning with `@phpstan-ignore-next-line`, `// @ts-expect-error`, `# type: ignore`, or `//nolint`
   without a reason code passes the linter but defers the real problem.
 * Running tests with `--stop-on-failure` then reporting "passed" — it
   only ran until the first failure; the green streak after it is
@@ -150,7 +159,7 @@ When reporting completion to the user:
   change is large.
 * Running the test suite on the wrong branch (forgot to switch or
   rebase) — verify `git status` and `git log -1` before the final gate.
-* A previously green PHPStan run in the same conversation is stale as
+* A previously green static-analysis run in the same conversation is stale as
   soon as any edit lands. Run it again.
 
 ## Red flags — STOP and run the gate
@@ -159,7 +168,7 @@ When reporting completion to the user:
   command-output reference in the same message
 * About to suggest `/commit` / push / PR without a verification block
 * Relying on an earlier-in-conversation test run
-* Partial evidence (tests green, PHPStan not run — or vice versa)
+* Partial evidence (tests green, type-checker / linter not run — or vice versa)
 * "The failing test is unrelated, let me skip it" — verify first, then
   decide
 * Reporting a green run by paraphrasing instead of quoting exit code
@@ -177,8 +186,8 @@ When reporting completion to the user:
 
 ## When to hand over to another skill
 
-* Exact PHPStan / Rector / ECS commands → [`quality-tools`](../quality-tools/SKILL.md)
-* Running tests inside Docker → [`tests-execute`](../tests-execute/SKILL.md)
+* Exact PHP quality commands (PHPStan / Rector / ECS) → [`quality-tools`](../quality-tools/SKILL.md)
+* Running tests inside a container / VM → [`tests-execute`](../tests-execute/SKILL.md)
 * Writing the regression test that the gate requires →
   [`test-driven-development`](../test-driven-development/SKILL.md)
 * Diagnosing why the gate failed → [`systematic-debugging`](../systematic-debugging/SKILL.md)

package/.agent-src/skills/video-director/SKILL.md

@@ -5,6 +5,18 @@ personas:
   - hollywood-director
 source: package
 domain: product
+workspaces:
+  - small-business
+packs:
+  - ai-video
+lifecycle: experimental
+trust:
+  level: experimental
+  confidence: high
+  human_review_required: false
+install:
+  default: false
+  removable: true
 ---
 
 # video-director
@@ -37,7 +49,7 @@ Do NOT use when:
 ### Step 0: Inspect
 
 1. Confirm the input is a live-action / photoreal beat (not animation).
-2. If a `character.json` exists under `agents/ai-video/<project>/characters/`,
+2. If a `character.json` exists under `agents/reference/ai-video/<project>/characters/`,
    read the identity tokens — they are reused verbatim.
 3. Read the scene's intent in one sentence — what is the camera
    witnessing, and why now?
@@ -116,11 +128,11 @@ Any "no" → revise that block before handing off.
 
 11-block cinematic prompt is live-action shape — real-person + brand-impersonation risks highest in cluster. Before emitting:
 
-- [`agents/policies/media/likeness.md`](../../../agents/policies/media/likeness.md) — prompt names / visually identifies real person on camera.
-- [`agents/policies/media/public-figures.md`](../../../agents/policies/media/public-figures.md) — subject is recognised public figure.
-- [`agents/policies/media/brand-impersonation.md`](../../../agents/policies/media/brand-impersonation.md) — prompt copies journalism / broadcaster / regulated-industry visual identity.
-- [`agents/policies/media/style.md`](../../../agents/policies/media/style.md) — LIGHT / LENS anchored to named living cinematographer's signature.
-- [`agents/policies/media/disclosure.md`](../../../agents/policies/media/disclosure.md) — every distributed live-action AI clip carries non-removable AI-generation disclosure.
+- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — prompt names / visually identifies real person on camera.
+- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — subject is recognised public figure.
+- [`agents/settings/policies/media/brand-impersonation.md`](../../../agents/settings/policies/media/brand-impersonation.md) — prompt copies journalism / broadcaster / regulated-industry visual identity.
+- [`agents/settings/policies/media/style.md`](../../../agents/settings/policies/media/style.md) — LIGHT / LENS anchored to named living cinematographer's signature.
+- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every distributed live-action AI clip carries non-removable AI-generation disclosure.
 
 Refuse-and-surface at directorial layer; live-action realism amplifies every downstream policy gap.
 

package/.agent-src/skills/vision-articulation/SKILL.md

@@ -6,6 +6,18 @@ tier: senior
 source: package
 domain: process
 context_spine: [org-stage, product, customer-segment]
+workspaces:
+  - founder
+packs:
+  - founder-strategy
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: true
 ---
 
 # vision-articulation

package/.agent-src/skills/voc-extract/SKILL.md

@@ -7,8 +7,18 @@ source: package
 domain: product
 context_spine: [product]
 recommended_for_user_types: [gtm, creator]
-
-
+workspaces:
+  - product
+packs:
+  - product-discovery
+lifecycle: active
+trust:
+  level: professional
+  confidence: high
+  human_review_required: false
+install:
+  default: false
+  removable: true
 ---
 
 # voc-extract

package/.agent-src/skills/voice-and-tone-design/SKILL.md

@@ -7,8 +7,18 @@ source: package
 domain: product
 context_spine: [product, customer-segment]
 recommended_for_user_types: [creator, consultant, gtm]
-
-
+workspaces:
+  - gtm
+packs:
+  - gtm-marketing
+lifecycle: active
+trust:
+  level: professional
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: true
 ---
 
 # voice-and-tone-design

package/.agent-src/templates/agent-settings.md

@@ -127,7 +127,7 @@ eloquent:
 
 # --- Chat history (crash recovery) ---
 #
-# Persistent JSONL log at agents/.agent-chat-history (project root, git-ignored).
+# Persistent JSONL log at agents/runtime/.agent-chat-history (git-ignored under /agents/runtime/).
 # Keeps a durable record of the conversation so a crashed or switched
 # agent session can be resumed. See scripts/chat_history.py for the API.
 #
@@ -152,7 +152,7 @@ chat_history:
 # (scripts/work_engine/). Hooks observe, validate, or persist around the
 # six CLI events (before_load, after_load, before_dispatch,
 # after_dispatch, before_save, after_save) and the dispatcher events
-# (before_step, after_step, on_halt). See agents/contexts/
+# (before_step, after_step, on_halt). See agents/settings/contexts/
 # work-engine-hooks.md for the full lifecycle and registration contract.
 #
 # Default-off by construction: when the `hooks:` block is absent the
@@ -182,7 +182,7 @@ hooks:
   # routing drift.
   directive_set_guard: true
 
-  # Chat-history hooks — populate agents/.agent-chat-history structurally from
+  # Chat-history hooks — populate agents/runtime/.agent-chat-history structurally from
   # the engine. Gated by BOTH this block AND the global
   # chat_history.enabled above; either off → no chat-history hook
   # registers. Keep both on for the HOOK path; flip either off to fall
@@ -450,12 +450,12 @@ the canonical narrative lives in
 | `project.improvement_pr_branch_prefix` | string | `improve/agent-` | Branch prefix for agent improvement PRs. |
 | `github.pr_reply_method` | `replies_endpoint`, `create_review_comment`, `auto` | `create_review_comment` | GitHub API method for replying to PR review comments. `auto` detects on first use. |
 | `eloquent.access_style` | `getters_setters`, `get_attribute`, `magic_properties` | `getters_setters` | How to access Eloquent model attributes. See `eloquent` skill for details. |
-| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `agents/.agent-chat-history` (JSONL) for crash recovery. |
+| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `agents/runtime/.agent-chat-history` (JSONL) for crash recovery. |
 | `chat_history.frequency` | `per_turn`, `per_phase`, `per_tool` | per profile | Logging granularity. Defaults: `minimal`→`per_turn`, `balanced`→`per_phase`, `full`→`per_tool`. |
 | `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
 | `chat_history.on_overflow` | `rotate`, `compress` | per profile | On overflow: `rotate` drops oldest entries; `compress` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`compress`. |
 | `chat_history.text_limits.{user,agent,tool,phase}` | integer (chars) | `user=0`, `agent=5000`, `tool=200`, `phase=200` | Per-entry-type text-length cap. `0` = verbatim, no slice. `N > 0` = collapse whitespace, slice to N chars, append `" … [+K chars]"` so the log self-reports truncation. Defaults match `DEFAULT_TEXT_LIMITS` in `scripts/chat_history.py`. |
-| `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md). |
+| `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/settings/contexts/work-engine-hooks.md`](../../../agents/settings/contexts/work-engine-hooks.md). |
 | `hooks.trace` | `true`, `false` | `false` | Emit per-event trace lines on stderr. Useful for debugging; off by default because it is noisy. |
 | `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
 | `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "2.24.0"
+agent_config_version: "2.26.0"
 
 # --- Project identity ---
 project:

package/.agent-src/templates/agents/memory/ownership.example.yml

@@ -61,7 +61,7 @@ entries:
     rotation_policy: >
       Infra changes require two platform-team reviews in business
       hours. After-hours hotfixes follow the break-glass policy in
-      `agents/contexts/deployment-order.md`.
+      `agents/settings/contexts/deployment-order.md`.
 
 # --- How to add an entry ---
 #

package/.agent-src/templates/agents/proposal.example.md

@@ -21,6 +21,18 @@ target_artifact: ""                # .agent-src/<type>/<name>.md (for upstream s
 author: ""                         # name or team slug
 created: 2026-01-01                # ISO date
 last_updated: 2026-01-01
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Proposal: <short title>

package/.agent-src/templates/command.md

@@ -35,7 +35,7 @@ suggestion:
   - suggestion: REQUIRED — drives the in-host command suggester
     - eligible: true  → set trigger_description + trigger_context
     - eligible: false → set rationale (why never auto-suggested)
-    See agents/contexts/command-suggestion-eligibility.md for guidance.
+    See agents/settings/contexts/command-suggestion-eligibility.md for guidance.
   - council_depth: optional — only `deep` is accepted. **Omit the key
     for default depth** (`standard` is the implicit default and is
     rejected by the schema — every frontmatter byte counts). Set `deep`

package/.agent-src/templates/contexts/auth-model.md

@@ -2,7 +2,7 @@
 
 <!--
   Template shipped by event4u/agent-config.
-  Copy to `agents/contexts/auth-model.md` in the consumer project and
+  Copy to `agents/settings/contexts/auth-model.md` in the consumer project and
   fill in. This file is consumed by the Waves 2-3 security skills (see
   `road-to-defensive-agent.md`) — an agent asked to review auth logic
   starts by reading this.
@@ -53,7 +53,7 @@
 
 ## See also
 
-- `agents/contexts/tenant-boundaries.md` — tenancy scope, multi-tenant
+- `agents/settings/contexts/tenant-boundaries.md` — tenancy scope, multi-tenant
   rules that sit on top of the role model
 - `../../../docs/guidelines/agent-infra/*` — reviewer skills that read this
   file

package/.agent-src/templates/contexts/data-sensitivity.md

@@ -2,7 +2,7 @@
 
 <!--
   Template shipped by event4u/agent-config.
-  Copy to `agents/contexts/data-sensitivity.md` in the consumer project
+  Copy to `agents/settings/contexts/data-sensitivity.md` in the consumer project
   and fill in. This is the canonical reference for what data leaves the
   system (logs, error reports, analytics, third-party APIs) and what
   MUST be masked.
@@ -56,5 +56,5 @@
 
 ## See also
 
-- `agents/contexts/auth-model.md` — who can see what
-- `agents/contexts/observability.md` — how logs are routed
+- `agents/settings/contexts/auth-model.md` — who can see what
+- `agents/settings/contexts/observability.md` — how logs are routed

package/.agent-src/templates/contexts/deployment-order.md

@@ -2,7 +2,7 @@
 
 <!--
   Template shipped by event4u/agent-config.
-  Copy to `agents/contexts/deployment-order.md` in the consumer project
+  Copy to `agents/settings/contexts/deployment-order.md` in the consumer project
   and fill in. Required reading for any change involving schema
   migrations, feature flags, or multi-service deploys. Without this,
   "breaking change" reviews are guesswork.
@@ -68,5 +68,5 @@
 
 ## See also
 
-- `agents/contexts/observability.md` — what to watch during a deploy
+- `agents/settings/contexts/observability.md` — what to watch during a deploy
 - `.augment/skills/migration-safety/SKILL.md` <!-- if installed --> — reviewer

package/.agent-src/templates/contexts/observability.md

@@ -2,7 +2,7 @@
 
 <!--
   Template shipped by event4u/agent-config.
-  Copy to `agents/contexts/observability.md` in the consumer project and
+  Copy to `agents/settings/contexts/observability.md` in the consumer project and
   fill in. A reviewer reads this before approving changes to loggers,
   error handlers, metrics, or alert rules.
 
@@ -59,6 +59,6 @@
 
 ## See also
 
-- `agents/contexts/data-sensitivity.md` — what must NOT appear in logs
+- `agents/settings/contexts/data-sensitivity.md` — what must NOT appear in logs
   or error reports
-- `agents/contexts/deployment-order.md` — what to watch during a deploy
+- `agents/settings/contexts/deployment-order.md` — what to watch during a deploy

package/.agent-src/templates/contexts/tenant-boundaries.md

@@ -2,7 +2,7 @@
 
 <!--
   Template shipped by event4u/agent-config.
-  Copy to `agents/contexts/tenant-boundaries.md` in the consumer project
+  Copy to `agents/settings/contexts/tenant-boundaries.md` in the consumer project
   and fill in. Required reading for any review that touches data access,
   queries, or public endpoints in a multi-tenant system.
 
@@ -64,5 +64,5 @@
 
 ## See also
 
-- `agents/contexts/auth-model.md` — roles that sit on top of tenants
-- `agents/contexts/data-sensitivity.md` — tenant-scoped vs. shared data
+- `agents/settings/contexts/auth-model.md` — roles that sit on top of tenants
+- `agents/settings/contexts/data-sensitivity.md` — tenant-scoped vs. shared data

package/.agent-src/templates/contexts.md

@@ -1,6 +1,6 @@
 # Context Template
 
-Templates for context documents stored in `agents/contexts/` or `app/Modules/{Module}/agents/contexts/`.
+Templates for context documents stored in `agents/settings/contexts/` or `app/Modules/{Module}/agents/settings/contexts/`.
 
 A **context document** captures the architectural understanding of a codebase area — its structure,
 key classes, patterns, dependencies, and conventions. It's a snapshot of knowledge that helps

package/.agent-src/templates/copilot-instructions.md

@@ -119,8 +119,8 @@ resolve at agent runtime. The patterns below are correct by design:
 - **`path_prefix:` triggers containing `.agent-src.uncompressed/`**
   in YAML frontmatter. This is a literal match pattern for the
   host's router, **not** a file reference — source-of-truth meta-rules
-  (`augment-source-of-truth`, `augment-portability`, `skill-quality`,
-  `docs-sync`, `rule-type-governance`) legitimately match against the
+  (`augment-source-of-truth`, `augment-edit-discipline`, `skill-quality`,
+  `rule-type-governance`) legitimately match against the
   authoring tree.
 - **Symlinked rule / skill / command files** under `.claude/`,
   `.cursor/`, `.clinerules/`. Targets resolve into `.augment/rules/`,

package/.agent-src/templates/rule.md

@@ -31,7 +31,7 @@ both reject the legacy prefix.
 |---|---|
 | `contexts/execution/verification-mechanics.md` | `.agent-src.uncompressed/contexts/execution/verification-mechanics.md` |
 | `contexts/authority/commit-mechanics.md` | `.agent-src.uncompressed/contexts/authority/commit-mechanics.md` |
-| `agents/contexts/local.md` (project-local) | `.agent-src.uncompressed/contexts/...` for project-only material |
+| `agents/settings/contexts/local.md` (project-local) | `.agent-src.uncompressed/contexts/...` for project-only material |
 
 ### `triggers[].path_prefix:` — literal match pattern, not a file path
 
@@ -39,8 +39,8 @@ both reject the legacy prefix.
 the file the agent is editing — it is **not** a file reference and is
 **not rewritten**. Rules that fire when the agent edits source-of-truth
 files legitimately keep the `.agent-src.uncompressed/` prefix (see
-`skill-quality`, `docs-sync`, `rule-type-governance`,
-`augment-portability`). Rules that fire on consumer-project paths use
+`skill-quality`, `rule-type-governance`,
+`augment-edit-discipline`). Rules that fire on consumer-project paths use
 `agents/`, `lang/`, `.augment/`, etc.
 
 | Use case | Example `path_prefix:` |

package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py

@@ -22,7 +22,7 @@ Step 7 the anchor set is (closest-leaf wins; tiebreaker
 ``.agent-settings.yml`` > ``agents/`` > ``.git``):
 
 * ``.agent-settings.yml`` file,
-* ``agents/`` directory containing ``roadmaps/``, ``.ai-council.yml``,
+* ``agents/`` directory containing ``roadmaps/``, ``settings/.ai-council.yml``,
   or ``roadmaps-progress.md`` (bare ``agents/`` does **not** anchor),
 * ``.git`` file or directory (submodule support).
 
@@ -102,7 +102,7 @@ ANCHOR_GIT = "git"
 #: is **not** an anchor.
 _AGENTS_DIR_MARKERS: tuple[str, ...] = (
     "roadmaps",
-    ".ai-council.yml",
+    "settings/.ai-council.yml",
     "roadmaps-progress.md",
 )
 
@@ -148,7 +148,7 @@ def find_project_root_with_anchor(start: Path) -> tuple[Path, str] | None:
        a boundary anchor wins:
 
        * ``agents/`` containing **any** of ``roadmaps/``,
-         ``.ai-council.yml``, or ``roadmaps-progress.md`` (D1) →
+         ``settings/.ai-council.yml``, or ``roadmaps-progress.md`` (D1) →
          ``"agents-dir"``
        * ``.git`` (file or directory; submodule support) → ``"git"``
 

package/.agent-src/templates/scripts/work_engine/cli.py

@@ -99,7 +99,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(state_file=state_file, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, state_file=state_file, event="BEFORE_LOAD")
 
     try:
         work, fmt = _load_or_build(state_file, args)
@@ -112,7 +112,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(state_file=state_file, work=work, fmt=fmt, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="AFTER_LOAD")
 
     try:
         set_name = select_directive_set(work)
@@ -129,7 +129,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(work=work, delivery=delivery, set_name=set_name, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="BEFORE_DISPATCH")
 
     final, halting = dispatch(delivery, steps, hooks=runner)
 
@@ -144,7 +144,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         ),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="AFTER_DISPATCH")
 
     _sync_back(work, delivery)
 
@@ -153,7 +153,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(work=work, delivery=delivery, fmt=fmt, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="BEFORE_SAVE")
 
     _save(state_file, work, fmt)
 
@@ -163,7 +163,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     if halt is not None:
         # State is already on disk; exit 2 still per the P3 branch table.
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="AFTER_SAVE")
 
     _emit(work, final, halting)
     return 0 if final is Outcome.SUCCESS else 1

package/.agent-src/templates/scripts/work_engine/emitters.py

@@ -8,10 +8,12 @@ on stdout, and the lifecycle-hook halt surface printed on stderr.
 from __future__ import annotations
 
 import sys
+from datetime import datetime, timezone
+from pathlib import Path
 
 from .delivery_state import Outcome
 from .hooks import HookHalt
-from .state import WorkState
+from .state import WorkState, dump
 
 
 def _emit(work: WorkState, final: Outcome, halting: str | None) -> None:
@@ -23,20 +25,43 @@ def _emit(work: WorkState, final: Outcome, halting: str | None) -> None:
         print(line)
 
 
-def _emit_halt(halt: HookHalt) -> int:
+def _emit_halt(
+    halt: HookHalt,
+    *,
+    work: WorkState | None = None,
+    state_file: Path | None = None,
+    event: str | None = None,
+) -> int:
     """Render a :class:`HookHalt` surface to stderr and return exit 2.
 
     Per the P3 halt branch table, every CLI-layer halt yields exit code
     ``2`` regardless of which event fired it. State persistence is
     governed by *where* in ``main`` the halt is detected: the call site
-    decides whether ``_save`` already ran. This helper is the single
-    place that formats the surface so the wire output stays consistent.
+    decides whether ``_save`` already ran.
+
+    When ``work`` + ``state_file`` are provided AND the state file
+    already exists on disk, the halt is appended to ``work.halts[]``
+    and the state is re-saved. This lets ``agent-config explain last``
+    surface the halt reason later. Fresh-run halts before the first
+    ``_save`` (state file absent) still leave no state on disk — the
+    pre-explain-v2 contract is preserved.
     """
     if halt.surface:
         for line in halt.surface:
             print(line, file=sys.stderr)
     else:
         print(f"halt: {halt.reason}", file=sys.stderr)
+    if work is not None and state_file is not None and state_file.exists():
+        work.halts.append({
+            "reason": halt.reason,
+            "step": event or "",
+            "surface": list(halt.surface),
+            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+        })
+        try:
+            dump(work, state_file)
+        except Exception:  # never let halt persistence mask the halt
+            pass
     return 2
 
 

package/.agent-src/templates/scripts/work_engine/hooks/builtin/decision_trace.py

@@ -13,7 +13,7 @@ Trace layout (matches the contract):
 
 * ``schema_version: 1``
 * ``work_id`` — derived from the state-file directory name when the
-  caller follows the ``agents/state/work/<id>/state.json`` convention,
+  caller follows the ``agents/runtime/state/work/<id>/state.json`` convention,
   else from the state-file stem.
 * ``phase`` — engine ``step_name`` (refine/memory/.../report).
 * ``started_at`` / ``ended_at`` — ISO-8601 UTC timestamps captured on
@@ -56,8 +56,8 @@ class DecisionTraceHook:
     output_dir:
         Optional override for the trace destination. When ``None`` the
         hook writes alongside the WorkState file: if the state file
-        sits under ``agents/state/work/<id>/state.json`` the trace
-        lands at ``agents/state/work/<id>/decision-trace-<phase>.json``;
+        sits under ``agents/runtime/state/work/<id>/state.json`` the trace
+        lands at ``agents/runtime/state/work/<id>/decision-trace-<phase>.json``;
         otherwise the trace lands next to the state file as
         ``<stem>.decision-trace-<phase>.json``.
     """