@event4u/agent-config 16.4.0 → 17.0.0

package/dist/agent-src/skills/wireframe/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: wireframe
-description: "Explore a flow or layout with 3+ disposable lo-fi greyscale wireframes on a named axis, before any hi-fi work. Use when the user wants to sketch directions or explore structure."
+description: "Explore a flow or layout with 3+ disposable lo-fi greyscale wireframes on a named axis. Use when the user wants to sketch directions or explore structure."
 domain: product
 personas: []
 workspaces:
@@ -80,7 +80,10 @@ branded, recommendation-bearing). A single refined implementation →
 
 1. **One file** (HTML or annotated markdown/SVG canvas) with ≥3 greyscale
    variations side-by-side — flows as small storyboards (3–5 screens each);
-   no brand color, no styled typography, no real imagery.
+   no brand color, no styled typography, no real imagery. An SVG canvas is
+   authored under [`svg-authoring`](../svg-authoring/SKILL.md); its grays are
+   the wireframe's own non-decisions, so the fidelity floor does not reproduce
+   them as choices.
 2. **Per-variation annotations** — 2–4 callouts naming the structural bet and
    its trade-off, inline next to the variation.
 3. **Decision-capture block** (after user pick) — chosen direction,

package/dist/agent-src/skills/worktree-lifecycle/SKILL.md

@@ -101,12 +101,12 @@ A worktree is **merge-ready** only when ALL hold:
 
 ### 4. Cleanup discipline
 
-Removal is gated by the deterministic helper (edge-case-tested: detached
-HEAD, branch without remote, tag-only reachability, deleted remote
-branch, untracked files, paths with spaces):
+Removal is gated by the deterministic helper (tested on detached HEAD,
+no remote, tag-only reachability, deleted remote branch, untracked
+files, paths with spaces):
 
 ```bash
-npx tsx node_modules/@event4u/agent-config/src/scripts/worktree_cleanup_check.ts check <worktree-path>
+agent-config worktree:cleanup check <worktree-path>
 ```
 
 Exit `0` → removal allowed; exit `1` → refuse, gates in order:
@@ -128,15 +128,18 @@ step (`scope-control`); never force-delete (`-D`) as part of cleanup.
 Cross-worktree scope-lock overlaps are scanned via
 `worktree_cleanup_check scope-overlap` (surfaced by `/worktree status`).
 
-**Whole-checkout sweeps.** Worktrees accumulate one per branch and are never
-removed on merge; `git worktree prune` only clears registrations whose
-directory is already gone, so it does nothing for the live ones. Classify the
-whole set in one pass rather than gate-checking by hand:
+**Whole-checkout sweeps.** Under `worktrees.cleanup: auto` the proven set leaves
+at `/pr:merge` and daily (ADR-295). `git worktree prune` only clears registrations whose
+directory is gone. Classify the whole set in one pass:
 
 ```bash
-npx tsx node_modules/@event4u/agent-config/src/scripts/worktree_cleanup_check.ts inventory [repo] [--json|--plan]
+agent-config worktree:cleanup inventory [repo] [--json|--plan]
+agent-config worktree:cleanup apply [repo]   # removes the safe set only
 ```
 
+`apply` runs only on the user's ask (`/worktree cleanup --apply`) or under
+the user-set `worktrees.cleanup: auto` — never on the agent's initiative.
+
 `safe` requires all of: on a branch, merged into the trunk, clean, inside a
 conventional worktree root (`.claude/worktrees/` or `.worktrees/`), and no git
 activity for 48 h. `review` keeps its disqualifying reason so the next sweep
@@ -168,15 +171,14 @@ merge-ready checklist, and cleanup gates are host-independent.
 * **`git log <branch> --not --all` is always empty** — `--all` includes
   the branch itself, so the naive check never fires. The
   `--exclude="refs/heads/<branch>" --all` variant is also unreliable
-  when combined with `--not` (observed on git 2.39). Use the
-  `for-each-ref` expansion above — it enumerates every ref except the
-  branch explicitly.
+  when combined with `--not` (observed on git 2.39). The cleanup
+  helper above excludes the branch explicitly.
 * **Scope note committed by accident** — `.worktree-scope.md` must be
   in `.git/info/exclude`; `.gitignore` would be a tracked change
   outside the scope lock.
 * **"Unchanged worktree" ≠ "no unique commits"** — a host auto-clean
-  only covers worktrees with no changes; a worktree with committed but
-  unmerged work still needs the unique-commit gate.
+  only covers worktrees with no changes; committed but unmerged work
+  still needs the unique-commit gate.
 * **Stale ahead/behind** — always `git fetch` before the
   `rev-list --left-right` count; a cached view reports merge-ready on
   a diverged branch.

package/dist/agent-src/templates/AGENTS.md

@@ -14,7 +14,7 @@
 ## Pointers
 
 - **Filling out this AGENTS.md** — section templates, capability bullets, multi-agent entry flow, monorepo layout: [`consumer-agents-md-guide`](.augment/contexts/contracts/consumer-agents-md-guide.md).
-- **Behavior rules** (9 always-on; rest routed) — [`.augment/rules/`](.augment/rules/). Kernel rules change only by a ratified edit; overrides may tighten.
+- **Behavior rules** (9 always-on; rest routed) — [`.augment/rules/`](.augment/rules/). Kernel rules change upstream only, by ratified edit; overrides tighten.
 - **Skills (on-demand expertise)** — domain skills surfaced by description, invoked on trigger match: [`.augment/skills/`](.augment/skills/).
 - **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).
 - **Project-specific docs** — your own architecture notes, roadmaps, sessions, contexts: [`agents/`](agents/).

package/dist/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.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "16.4.0"
+agent_config_version: "17.0.0"
 
 # --- Project identity ---
 project:

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

@@ -15,7 +15,7 @@ proposal_id: ""                    # stable kebab-case slug, unique per repo
 type: ""                           # rule | skill | command | guideline
 scope: ""                          # project | package
 stage: proposed                    # captured | classified | proposed | gated | upstream
-source_learning: ""                # agents/learnings/<date>-<slug>.md
+source_learning: ""                # agents/memory/intake/signals-<YYYY-MM>.jsonl#<signal id>
 target_artifact: ""                # dist/agent-src/<type>/<name>.md (for upstream scope)
                                    # or agents/overrides/<...> (for project scope)
 author: ""                         # name or team slug

package/dist/agent-src/templates/github-workflows/advisories-daily.yml

@@ -0,0 +1,85 @@
+# Advisories, daily — template shipped by agent-config
+#
+# Copy this file to `.github/workflows/advisories-daily.yml` in the consumer
+# project. It is the opt-in out-of-band runner of
+# road-to-advisories-heard-the-same-day (5.3): on days nobody opens a session,
+# a critical advisory for something this project runs still becomes an issue.
+#
+# What it does: `agent-config audit:deps refresh` (public package names and
+# versions to api.osv.dev, runtime lifecycle from endoflife.date, the PHP and
+# Node release feeds, the whole CISA known-exploited catalog from www.cisa.gov
+# matched locally; private package names are never sent), then opens or
+# updates ONE issue for T0 findings — malware, a critical runtime
+# pre-announcement, a critical fix for a direct dependency, a high finding that
+# is known-exploited (KEV raises one tier).
+#
+# What it never does: merge, push, open a PR, change a dependency, or run a
+# package manager's install. Carrying a finding to a fix is `/audit deps fix
+# <id>` in a session, where a person decides.
+#
+# Permissions: `issues: write` to open the issue; nothing else is written.
+#
+# Private repositories only. On a public repository the issue, and this job's
+# log, would advertise which unpatched components the project runs before they
+# are fixed; the first step checks visibility and every later step is skipped
+# unless the repository is private.
+#
+# Pin the package to the major you run (`@16` below) and keep the actions pinned
+# the way the rest of your workflows are; a security job that installs `latest`
+# with a write token is a supply-chain path of its own.
+
+name: Advisories (daily)
+
+on:
+  schedule:
+    - cron: '17 5 * * *'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  advisories:
+    name: audit:deps refresh → T0 issue
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run on a private repository only
+        id: visibility
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          private="$(gh api "repos/$REPO" -q .private)"
+          echo "private=$private" >> "$GITHUB_OUTPUT"
+          [ "$private" = "true" ] || echo "not a private repository: nothing is refreshed or published here"
+      - if: steps.visibility.outputs.private == 'true'
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - if: steps.visibility.outputs.private == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Refresh advisories
+        if: steps.visibility.outputs.private == 'true'
+        run: npx --yes @event4u/agent-config@16 audit:deps refresh --force
+      - name: Open or update the T0 issue (only when the list changed)
+        if: steps.visibility.outputs.private == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          body="$(npx --yes @event4u/agent-config@16 audit:deps issue-body)"
+          [ -z "$body" ] && { echo "no T0 finding today"; exit 0; }
+          # The `Checked <time>` line changes on every run; the list is what counts.
+          digest="$(printf '%s' "$body" | grep -v '^Checked ' | sha256sum | cut -c1-16)"
+          marker="<!-- advisories-digest: $digest -->"
+          title="Security advisories needing action today"
+          existing="$(gh issue list --state open --search "in:title \"$title\"" --json number -q '.[0].number')"
+          if [ -z "$existing" ]; then
+            gh issue create --title "$title" --body "$body"$'\n\n'"$marker"
+          elif ! gh issue view "$existing" --json body,comments -q '.body, .comments[].body' | grep -qF "$marker"; then
+            gh issue comment "$existing" --body "$body"$'\n\n'"$marker"
+          else
+            echo "the T0 list is unchanged since the last report"
+          fi

package/dist/agent-src/templates/roadmaps.md

@@ -148,6 +148,13 @@ that was never a judgement call.
     scope laundering. Only an item that **cannot** be executed now qualifies.
     Contract: `agents/roadmaps/*` · `src/agent-src/scripts/archive_completed_roadmaps.ts`
     § `deferralProblems` · `tests/scripts/archive_deferral_resolution.test.ts`.
+17c. **A step that waits on a date is written as a stub, not as a step.**
+    A measurement window, a soak, "four weeks after X lands" — work that
+    needs elapsed time rather than effort — goes into a `stubs/` entry with
+    its trigger when the roadmap is authored, not into the roadmap's phases.
+    Left inside, it holds a roadmap whose work is done at `count_open > 0`,
+    and a drain can never close it. `lint_roadmap_complexity` warns on an
+    open step whose block pairs a wait word with a date after today.
 17. **Follow-up roadmaps from deferred items carry `parent_roadmap`.**
     When a roadmap closes with `[~]` deferred items, the
     [`roadmap-management`](../skills/roadmap-management/SKILL.md) skill
@@ -241,6 +248,18 @@ that was never a judgement call.
     edge source stays the single one already defined above; `relates:` never
     becomes a second dependency source.
 
+    A step that waits on another roadmap says so in both places: an inline
+    `<!-- blocked-by: road-to-X#… -->` marker fails the roadmap lint unless a
+    `relates:` row names X with `relation: depends`. A `depends` row naming a
+    file under `archive/` fails the same lint, because an archived file lands
+    nothing — turn it into `extends` or depend on the successor.
+
+    **Optional — `renewed: <YYYY-MM-DD> — <reason>`.** The dashboard's `## Age`
+    section lists, from `git log`, days since each active file landed and since
+    its last ticked step, and proposes parking a file with no ticked step 21
+    days after landing. The proposal is text, never an action; this one line
+    clears it for 21 days from its date.
+
     **Sibling block, same frontmatter — `delivery:`.** Optional, and unlike
     `execution:` it describes what happens to the BRANCH rather than to the
     run's interaction pattern:
@@ -310,7 +329,8 @@ that was never a judgement call.
 
     ### blocker: <kebab-id>
     - **Status:** open            <!-- open | resolved -->
-    - **Owner:** user             <!-- user | maintainer | external -->
+    - **Owner:** user             <!-- user | maintainer | owner | external | council | implementer -->
+    - **Routed:** council 2026-10-20 ESCALATE — {reserved row}   <!-- human Owner only; or: pending — {why the council was unreachable} -->
     - **Blocks:** Phase N — {phase name}
     - **Question:** {optional — the one line saying what is being decided.}
     <!-- Class is optional and absent means 3. Add Run: ONLY with Class 0 or 1,
@@ -342,6 +362,17 @@ that was never a judgement call.
     must name an OPEN blocker — once it resolves, remove the marker — and
     `lint_roadmap_blockers` reads it on a continuation line too.
 
+    **Route before you file.** A human `Owner:` (user, maintainer, owner)
+    is a routing verdict, not a first impression: put the transition to the
+    council with the owner-reserved table of
+    [`decision-revisit-gate`](../rules/decision-revisit-gate.md) attached,
+    and file it here only on `ESCALATE`, recording the verdict and the
+    reserved row it crosses in `Routed:`. A `DECIDE` is a `## Decisions`
+    row, not a blocker. An unreachable council writes `Routed: pending —
+    <reason>` and the entry goes to the next council pass, never to the
+    owner by default. `lint_roadmap_blockers:routing` ratchets entries
+    without the field.
+
     **A blocker stops execution; a hold stops publication.** The two are not
     interchangeable and never substitute for one another. A blocker says the work
     cannot proceed and is cleared by a person; a release hold (rule 28) says the
@@ -796,6 +827,13 @@ that was never a judgement call.
     `## Release holds` exactly as it does everywhere else. A hold names a *state*
     and its clearing *checkbox*; it never names a version, a tag, or a date.
 
+29. **A step is at most 150 words, and its Done note is one line.** The
+    checkbox line plus its indented continuation counts; HTML comments (a
+    receipt, a skip marker) do not. Evidence goes to the commit and, for an
+    R2/R3 change, to the artefact — not into the step. `lint_roadmap_complexity`
+    refuses a new step over the cap; steps already over it when the cap landed
+    sit in a baseline that only shrinks.
+
 ---
 
 ## Quality Gates (remote CI by default)

package/dist/agent-src/templates/scripts/check_memory.ts

@@ -132,7 +132,7 @@ const _TYPE_COUNTS: Record<string, number> = {};
 // Redaction heuristics — plain-regex, deliberately conservative.
 // False positives are fixed by quoting the line differently; false
 // negatives are a curator responsibility.
-const REDACTION_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+export const REDACTION_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
     // Key=value secret with a clear credential-word prefix. The value must
     // be a single token (no spaces, no "/" — skips filepaths and URLs).
     [
@@ -897,7 +897,7 @@ function _isCliEntry(): boolean {
 const _isMain =
     _isCliEntry();
 if (_isMain) {
-    process.exit(main());
+    process.exitCode = main();
 }
 
 export { main };

package/dist/agent-src/templates/scripts/historical-bug-patterns.example.yml

@@ -9,7 +9,7 @@
 # `paths` globs. Routing severity is the max of matched pattern severities.
 
 version: 1
-updated: 2026-04-21
+updated: 2026-10-13
 
 patterns:
   - id: n-plus-one-tenant-listing
@@ -76,6 +76,18 @@ patterns:
       - "app/api/**webhook**"
     required_test: "negative test: unsigned payload returns 401"
 
+  - id: auth-response-discloses-account-existence
+    label: "Auth response answers differently for a known and an unknown account"
+    severity: high
+    paths:
+      - "app/Http/Controllers/Auth/**"
+      - "app/Http/Controllers/**Login*.php"
+      - "app/Http/Controllers/**Password*.php"
+      - "app/Http/Controllers/**Registration*.php"
+      - "routes/auth.php"
+      - "src/Controller/Security/**"
+    required_test: "equivalence case: a known and an unknown address produce the same status, body category, redirect and cookies"
+
   - id: migration-no-rollback
     label: "Migration with destructive up() and empty down()"
     severity: medium

package/dist/agent-src/templates/scripts/work_engine/cli.ts

@@ -65,6 +65,7 @@ import {
     _to_delivery,
     _to_v0_dict,
 } from './state_io.js';
+import { run_procedure } from './procedure/run.js';
 import type { WorkState } from './state.js';
 
 /**
@@ -90,6 +91,22 @@ export function main(argv: string[] | null = null): number {
     }
     const state_file: string = args.state_file;
 
+    if (args.procedure !== undefined) {
+        const r = run_procedure({
+            skill: args.procedure,
+            projectRoot: process.cwd(),
+            stateFile: state_file,
+            confirm: args.procedure_confirm ?? null,
+            restart: args.procedure_restart === true,
+        });
+        (r.code === 2 ? process.stderr : process.stdout).write(`${r.output}\n`);
+        return r.code;
+    }
+    if (args.procedure_confirm !== undefined || args.procedure_restart === true) {
+        process.stderr.write('error: --procedure-confirm and --procedure-restart need --procedure <skill>\n');
+        return 2;
+    }
+
     const runner = new HookRunner(_build_hook_registry(args));
 
     let halt = runner.emit(

package/dist/agent-src/templates/scripts/work_engine/cli_args.ts

@@ -61,6 +61,13 @@ export interface ParsedArgs {
     persona: string | null;
     no_hooks: boolean;
     hooks_config: string | null;
+    /**
+     * The procedure cursor (road-to-steps-the-skill-cannot-skip 5.5). Set only
+     * when passed, so every existing invocation parses to the namespace it did.
+     */
+    procedure?: string;
+    procedure_confirm?: string;
+    procedure_restart?: boolean;
 }
 
 /** Thrown internally to mirror argparse's exit-2 error path. */
@@ -93,6 +100,9 @@ const OPTIONS: OptionSpec[] = [
     { flag: '--persona', dest: 'persona', takesValue: true },
     { flag: '--no-hooks', dest: 'no_hooks', takesValue: false },
     { flag: '--hooks-config', dest: 'hooks_config', takesValue: true },
+    { flag: '--procedure', dest: 'procedure', takesValue: true },
+    { flag: '--procedure-confirm', dest: 'procedure_confirm', takesValue: true },
+    { flag: '--procedure-restart', dest: 'procedure_restart', takesValue: false },
 ];
 
 // `-h` / `--help` is an implicit argparse optional; included as a prefix

package/dist/agent-src/templates/scripts/work_engine/directives/ui/scaffold.ts

@@ -52,13 +52,16 @@ import { GRANULARITY_CONVENTION } from '../../state.js';
  * anti-generic moat that makes a generated multi-page app coherent rather than
  * default-shadcn. Absent → sane defaults. The dependency is acyclic and
  * degrades gracefully: scaffold never *requires* `pack-brand`.
+ *
+ * Re-exported, not declared: the list has three readers across two trees and
+ * `shared/brandTokenPaths.ts` is the one home both reach at runtime. The
+ * specifier below resolves to `src/shared/` under tsx and to `dist/shared/` in
+ * the projected copy, which is why it is six hops and not an alias.
  */
-export const BRAND_TOKEN_PATHS: ReadonlyArray<string> = [
-    'tokens.json',
-    'assets/tokens.json',
-    'resources/tokens.json',
-    'agents/settings/brand/tokens.json',
-];
+import { BRAND_TOKEN_PATHS } from '../../../../../../shared/brandTokenPaths.js';
+import { tokenDocumentError } from '../../../../../../shared/brandTokenDocument.js';
+
+export { BRAND_TOKEN_PATHS };
 
 /**
  * Conventional location of the project's `Playbook` contexts (ADR-244).
@@ -404,20 +407,26 @@ function _resolve_build_directive(state: DeliveryState): string {
 }
 
 /**
- * Return the relative path to a present `tokens.json`, or `null`.
+ * Return the relative path to a VALID `tokens.json`, or `null`.
  *
  * Checks {@link BRAND_TOKEN_PATHS} under `root` (default: the current working
  * directory, which is the consumer project root when the engine runs). The
- * first existing file wins. Absent → `null` so the caller degrades to default
- * tokens — the acyclic, graceful-degradation contract.
+ * first file that parses as a DTCG document wins — the same predicate
+ * `brand:status` reports with, so the plan and the resolver cannot name
+ * different files as the brand. A file that merely exists is not a brand: a
+ * malformed `tokens.json` at the first path used to beat a valid
+ * `assets/tokens.json` at the second and seed the plan from a document nothing
+ * can read. Absent or unreadable → `null` so the caller degrades to default
+ * tokens — the acyclic, graceful-degradation contract is unchanged.
  */
-function _brand_token_source(root: string | null = null): string | null {
+export function _brand_token_source(root: string | null = null): string | null {
     const base = root !== null ? root : process.cwd();
     for (const rel of BRAND_TOKEN_PATHS) {
         try {
-            if (fs.statSync(path.join(base, rel)).isFile()) {
-                return rel;
-            }
+            const abs = path.join(base, rel);
+            if (!fs.statSync(abs).isFile()) continue;
+            if (tokenDocumentError(fs.readFileSync(abs, 'utf-8')) !== null) continue;
+            return rel;
         } catch {
             continue;
         }

package/dist/agent-src/templates/scripts/work_engine/dispatcher.ts

@@ -65,6 +65,9 @@ const _NOOP_RUNNER: HookRunner = new HookRunner();
  *
  * Changing this order is a roadmap-level decision — not a PR rider — per the
  * surface-growth guardrails in `agents/roadmaps/road-to-implement-ticket.md`.
+ * `dispatch` may be handed another order for another input kind
+ * (road-to-steps-the-skill-cannot-skip 5.1); this default stays the order every
+ * existing directive set runs.
  */
 export const STEP_ORDER: ReadonlyArray<string> = [
     'refine',
@@ -115,6 +118,9 @@ const _DIRECTIVE_SET_MODULES: Record<string, DirectiveSetModule> = {
  * rather than silently skipping, so incomplete wiring surfaces as a hard
  * failure.
  *
+ * `order` defaults to {@link STEP_ORDER}; a caller that runs another input kind
+ * passes its own linear order, which must be non-empty and free of repeats.
+ *
  * `hooks` is an optional {@link HookRunner}. `null` preserves every existing
  * call site verbatim — internally `dispatch` falls back to a shared
  * empty-registry runner so hook bookkeeping stays uniform without a per-emit
@@ -127,8 +133,10 @@ export function dispatch(
     state: DeliveryState,
     steps: Map<string, Step>,
     hooks: HookRunner | null = null,
+    order: ReadonlyArray<string> = STEP_ORDER,
 ): [Outcome, string | null] {
-    _assert_all_steps_present(steps);
+    _assert_order_valid(order);
+    _assert_all_steps_present(steps, order);
 
     // Clear stale questions from a previous halt before we resume so the caller
     // never mistakes old options for fresh ones.
@@ -136,7 +144,7 @@ export function dispatch(
 
     const runner = hooks !== null ? hooks : _NOOP_RUNNER;
 
-    for (const name of STEP_ORDER) {
+    for (const name of order) {
         if (_get(state.outcomes, name) === Outcome.SUCCESS) {
             // Already completed on an earlier invocation — skip per the resume
             // contract. The caller is responsible for keeping `state.outcomes`
@@ -245,8 +253,14 @@ function _emit_on_halt(
  * inside the dispatch loop after partial state mutation, which makes debugging
  * the wiring harder than it needs to be.
  */
-function _assert_all_steps_present(steps: Map<string, Step>): void {
-    const missing = STEP_ORDER.filter((name) => !steps.has(name));
+function _assert_order_valid(order: ReadonlyArray<string>): void {
+    if (order.length === 0 || new Set(order).size !== order.length) {
+        throw new ValueError('Step order must be non-empty and name each step once: ' + order.join(', '));
+    }
+}
+
+function _assert_all_steps_present(steps: Map<string, Step>, order: ReadonlyArray<string>): void {
+    const missing = order.filter((name) => !steps.has(name));
     if (missing.length > 0) {
         throw new KeyError('Step mapping is missing handlers for: ' + missing.join(', '));
     }