@event4u/agent-config 7.5.0 → 8.0.0

package/dist/agent-src/scripts/update_roadmap_progress.ts

@@ -161,12 +161,28 @@ class RoadmapStats {
     rel: string;
     title: string;
     phases: PhaseStats[];
+    blockers: Blocker[];
 
-    constructor(p: string, rel: string, title: string, phases: PhaseStats[] = []) {
+    constructor(
+        p: string,
+        rel: string,
+        title: string,
+        phases: PhaseStats[] = [],
+        blockers: Blocker[] = [],
+    ) {
         this.path = p;
         this.rel = rel;
         this.title = title;
         this.phases = phases;
+        this.blockers = blockers;
+    }
+
+    get open_blockers(): Blocker[] {
+        return this.blockers.filter((b) => b.status !== 'resolved');
+    }
+
+    get resolved_blockers(): Blocker[] {
+        return this.blockers.filter((b) => b.status === 'resolved');
     }
 
     get done(): number {
@@ -322,6 +338,136 @@ function count_checkboxes(text: string): CheckboxCounts {
     return [done, open_, deferred, cancelled, merge_gated, prs];
 }
 
+interface Blocker {
+    id: string;
+    status: string;
+    owner: string;
+    blocks: string;
+    todo: string[];
+    resolvedWhen: string;
+}
+
+// Strip fenced code blocks before blocker detection — a roadmap that shows the
+// `## Blockers` shape as a documentation example (fenced, indented or not)
+// must not be mistaken for a live blocker on that roadmap.
+const FENCED_CODE_RE = /^[ \t]*```[^\n]*\n[\s\S]*?^[ \t]*```[ \t]*$/gm;
+const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
+const BLOCKER_HEADING_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/gim;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const LEGACY_BLOCKED_UNTIL_RE = /^>[ \t]*Blocked until:?[ \t]*(.+)$/im;
+
+function _stripFencedCode(text: string): string {
+    return text.replace(FENCED_CODE_RE, (m) => '\n'.repeat(_splitlines(m).length));
+}
+
+const BLOCKER_FIELD_RE = /^-[ \t]*\*\*(Status|Owner|Blocks|Resolved when|What to do):\*\*/i;
+
+/** Strip an inline `<!-- comment -->` and trim. */
+function _stripComment(s: string): string {
+    return _strip(s.replace(/<!--[\s\S]*?-->/g, ''));
+}
+
+/**
+ * `- **Label:** value` → trimmed `value`, joined with any wrapped
+ * continuation lines (non-bulleted text under the same field, e.g. a long
+ * "Blocks" sentence spanning two lines) up to the next `- **Field:**`
+ * marker, blank line, or heading.
+ */
+function _blockerField(slice: string, label: string): string | null {
+    const lines = _splitlines(slice);
+    const re = new RegExp(`^-[ \\t]*\\*\\*${label}:\\*\\*[ \\t]*(.*)$`, 'i');
+    const startIdx = lines.findIndex((l) => re.test(_strip(l)));
+    if (startIdx === -1) {
+        return null;
+    }
+    const m = re.exec(_strip(lines[startIdx] as string));
+    const parts: string[] = [];
+    const first = _stripComment((m?.[1] as string) ?? '');
+    if (first) {
+        parts.push(first);
+    }
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const trimmed = _strip(lines[i] as string);
+        if (trimmed === '' || BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
+            break;
+        }
+        parts.push(_stripComment(trimmed));
+    }
+    return parts.length ? parts.join(' ') : null;
+}
+
+/** Lines under `- **What to do:**` up to the next `- **Field:**` marker. */
+function _blockerTodo(slice: string): string[] {
+    const lines = _splitlines(slice);
+    const startIdx = lines.findIndex((l) => /^-[ \t]*\*\*What to do:\*\*/i.test(_strip(l)));
+    if (startIdx === -1) {
+        return [];
+    }
+    const out: string[] = [];
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const trimmed = _strip(lines[i] as string);
+        if (BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
+            break;
+        }
+        if (trimmed !== '') {
+            out.push(trimmed);
+        }
+    }
+    return out;
+}
+
+function parse_blockers(raw_text: string): Blocker[] {
+    const text = _stripFencedCode(raw_text);
+    const blockers: Blocker[] = [];
+    const sectionMatch = BLOCKERS_SECTION_RE.exec(text);
+    if (sectionMatch) {
+        const sectionStart = sectionMatch.index + sectionMatch[0].length;
+        const rest = text.slice(sectionStart);
+        const h2 = NEXT_H2_RE.exec(rest);
+        const sectionEnd = h2 ? sectionStart + h2.index : text.length;
+        const section = text.slice(sectionStart, sectionEnd);
+        BLOCKER_HEADING_RE.lastIndex = 0;
+        const heads: Array<{ start: number; end: number; id: string }> = [];
+        let hm: RegExpExecArray | null;
+        while ((hm = BLOCKER_HEADING_RE.exec(section)) !== null) {
+            heads.push({
+                start: hm.index,
+                end: hm.index + hm[0].length,
+                id: _strip(hm[1] as string),
+            });
+            if (hm.index === BLOCKER_HEADING_RE.lastIndex) {
+                BLOCKER_HEADING_RE.lastIndex++;
+            }
+        }
+        for (let i = 0; i < heads.length; i++) {
+            const cur = heads[i] as { start: number; end: number; id: string };
+            const bodyEnd =
+                i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
+            const body = section.slice(cur.end, bodyEnd);
+            blockers.push({
+                id: cur.id,
+                status: (_blockerField(body, 'Status') ?? 'open').toLowerCase(),
+                owner: _blockerField(body, 'Owner') ?? 'user',
+                blocks: _blockerField(body, 'Blocks') ?? '(unspecified)',
+                todo: _blockerTodo(body),
+                resolvedWhen: _blockerField(body, 'Resolved when') ?? '(unspecified)',
+            });
+        }
+    }
+    const legacyMatch = LEGACY_BLOCKED_UNTIL_RE.exec(text);
+    if (legacyMatch) {
+        blockers.push({
+            id: 'legacy',
+            status: 'open',
+            owner: 'user',
+            blocks: 'entire roadmap',
+            todo: [_strip(legacyMatch[1] as string)],
+            resolvedWhen: 'condition described above clears',
+        });
+    }
+    return blockers;
+}
+
 function parse_roadmap(p: string, roadmap_root: string): RoadmapStats | null {
     const text = fs.readFileSync(p, { encoding: 'utf-8' });
     const phase_matches: Array<{ start: number; end: number; g2: string; g3: string | undefined }> =
@@ -345,7 +491,7 @@ function parse_roadmap(p: string, roadmap_root: string): RoadmapStats | null {
     const title_match = TITLE_RE.exec(text);
     const title = title_match ? _strip(title_match[1] as string) : _stem(p);
     const rel = _relPosix(roadmap_root, p);
-    const stats = new RoadmapStats(p, rel, title);
+    const stats = new RoadmapStats(p, rel, title, [], parse_blockers(text));
     for (let i = 0; i < phase_matches.length; i++) {
         const cur = phase_matches[i] as { start: number; end: number; g2: string; g3: string | undefined };
         const start = cur.end;
@@ -370,6 +516,19 @@ function _relPosix(root: string, p: string): string {
     return path.relative(root, p).split(path.sep).join('/');
 }
 
+/** Deterministic anchor slug for a roadmap's blocker section — explicit
+ * anchors (rather than GitHub's auto heading-slug) survive `.md` / brackets. */
+function _blockerAnchor(rel: string): string {
+    const stem = rel.endsWith('.md') ? rel.slice(0, -3) : rel;
+    return (
+        'blockers-' +
+        stem
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+    );
+}
+
 function bar(pct: number, width = 10): string {
     const filled = _pyRound((pct * width) / 100);
     return '█'.repeat(filled) + '░'.repeat(width - filled);
@@ -512,13 +671,18 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
     const overall_pct = total_active ? _pyRound((total_done * 100) / total_active) : 0;
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
+    const total_open_blockers = roadmaps.reduce((s, r) => s + r.open_blockers.length, 0);
     const lines: string[] = [];
     lines.push('# Roadmap Progress\n');
     const header_meta =
         `> ${roadmaps.length} open roadmap` +
         `${roadmaps.length !== 1 ? 's' : ''}` +
         ' · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · ' +
-        '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)\n';
+        '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
+        (total_open_blockers > 0
+            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}`
+            : '') +
+        '\n';
     lines.push(
         // Honest provenance (road-to-roadmap-archival-robustness, gap C): name a
         // regen path that exists in EVERY install, not a hardcoded
@@ -600,13 +764,18 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         return lines.join('\n') + '\n';
     }
     lines.push('## Open roadmaps\n');
-    lines.push('| # | Roadmap | Phases | Steps | Open | Done | Deferred | Cancelled | Progress |');
-    lines.push('|---|---|---:|---:|---:|---:|---:|---:|---|');
+    lines.push(
+        '| # | Roadmap | Phases | Steps | Open | Done | Deferred | Cancelled | Blocker | Progress |',
+    );
+    lines.push('|---|---|---:|---:|---:|---:|---:|---:|---:|---|');
     roadmaps.forEach((r, idx) => {
         const i = idx + 1;
+        const openBlockers = r.open_blockers.length;
+        const blockerCell =
+            openBlockers > 0 ? `[${openBlockers}](#${_blockerAnchor(r.rel)})` : '0';
         lines.push(
             `| ${i} | [${r.rel}](roadmaps/${r.rel}) | ${r.phases.length} | ${r.total_all} | ` +
-                `${r.open_} | ${r.done} | ${r.deferred} | ${r.cancelled} | ` +
+                `${r.open_} | ${r.done} | ${r.deferred} | ${r.cancelled} | ${blockerCell} | ` +
                 `${bar(r.percent)} ${r.percent}% |`,
         );
     });
@@ -625,6 +794,26 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
             );
         }
         lines.push('');
+        const openBlockers = r.open_blockers;
+        if (openBlockers.length) {
+            lines.push(`<a id="${_blockerAnchor(r.rel)}"></a>`);
+            lines.push('**Blockers**\n');
+            for (const b of openBlockers) {
+                lines.push(`- **${b.id}** (owner: ${b.owner}) — blocks ${b.blocks}`);
+                lines.push('  - **What to do:**');
+                for (const step of b.todo) {
+                    lines.push(`    ${step}`);
+                }
+                lines.push(`  - **Resolved when:** ${b.resolvedWhen}`);
+            }
+            const resolvedCount = r.resolved_blockers.length;
+            if (resolvedCount > 0) {
+                lines.push(
+                    `\n_${resolvedCount} blocker${resolvedCount !== 1 ? 's' : ''} resolved._`,
+                );
+            }
+            lines.push('');
+        }
     }
     if (bundles && bundles.length) {
         lines.push('---\n');
@@ -855,6 +1044,7 @@ export {
     is_draft,
     is_roadmap_candidate,
     count_checkboxes,
+    parse_blockers,
     parse_roadmap,
     bar,
     collect,
@@ -866,4 +1056,4 @@ export {
     main,
     _pyRound,
 };
-export type { Bundle };
+export type { Bundle, Blocker };

package/dist/agent-src/skills/adr-create/SKILL.md

@@ -9,8 +9,8 @@ execution:
   timeout_seconds: 30
   allowed_tools: []
   command:
-    - python3
-    - scripts/adr/regenerate_index.py
+    - ./scripts-run
+    - src/scripts/adr/regenerate_index
 workspaces:
   - agent-config-maintainer
 packs:
@@ -48,16 +48,16 @@ Do NOT use when:
 
 ## Preconditions
 
-- ADR directory exists. Two layouts coexist (see
+- An ADR directory exists. Two layouts coexist (see
   [`docs/contracts/adr-layout.md`](../../../docs/contracts/adr-layout.md)):
   - **Flat** — `docs/decisions/` (or `docs/adr/` alias): cross-cutting
     governance ADRs, 3-digit numbering (`ADR-NNN-<slug>.md`).
   - **Per-area** — `docs/adrs/<area>/`: sub-area ADRs, 4-digit
-    numbering (`NNNN-<slug>.md`); `<area>` must match canonical
+    numbering (`NNNN-<slug>.md`); `<area>` must match the canonical
     inventory in [`scripts/audit_adr_coverage.py`](../../../scripts/audit_adr_coverage.py).
-- Decision **already made** — ADRs record outcomes, not run the
-  decision process. For unresolved trade-offs, run council or
-  consult `adversarial-review` first.
+- The decision is **already made** — ADRs record outcomes, they do
+  not run the decision process. For unresolved trade-offs, run the
+  council or consult `adversarial-review` first.
 
 ## Procedure
 
@@ -65,31 +65,31 @@ Do NOT use when:
 
 Ask one question only if both are plausible:
 
-1. **Flat surface** — decision constrains package's contract with
-   consumers (kernel composition, rule taxonomy, package-wide
-   architecture). Directory: `docs/decisions/` (fallback
-   `docs/adr/`). Filename: `ADR-NNN-<slug>.md`.
-2. **Per-area surface** — decision constrains code inside one area
-   folder (one runtime module, one contract group, one CLI surface).
-   Directory: `docs/adrs/<area>/`. Filename: `NNNN-<slug>.md`
-   (4-digit, no `ADR-` prefix).
-3. **Unknown area** — `<area>` not in inventory: refuse with hint
-   to add area to `AREAS` in `scripts/audit_adr_coverage.py` in
-   same PR. Do not invent.
+1. **Flat surface** — chosen when the decision constrains the
+   package's contract with consumers (kernel composition, rule
+   taxonomy, package-wide architecture). Directory: `docs/decisions/`
+   (fallback `docs/adr/`). Filename: `ADR-NNN-<slug>.md`.
+2. **Per-area surface** — chosen when the decision constrains code
+   inside one area folder (one runtime module, one contract group,
+   one CLI surface). Directory: `docs/adrs/<area>/`. Filename:
+   `NNNN-<slug>.md` (4-digit, no `ADR-` prefix).
+3. **Unknown area** — `<area>` not in the inventory: refuse with a
+   hint to add the area to `AREAS` in
+   `scripts/audit_adr_coverage.py` in the same PR. Do not invent.
 4. **In doubt** → per-area (cheaper to surface, easier to relocate).
 
 ### 2. Pick the next ADR number
 
 - **Flat surface** — scan `docs/decisions/` (or `docs/adr/`) for
-  `ADR-*.md`, parse leading 3-digit number, take `max + 1`
-  (zero-padded to 3). Empty directory → start at `001`.
+  `ADR-*.md`, parse the leading 3-digit number, take `max + 1`
+  (zero-padded to 3). For an empty directory, start at `001`.
 - **Per-area surface** — scan `docs/adrs/<area>/` for
-  `[0-9][0-9][0-9][0-9]-*.md`, parse leading 4-digit number, take
-  `max + 1` (zero-padded to 4). Empty area → start at `0001`.
-  `README.md` is **not** an ADR — skip it.
+  `[0-9][0-9][0-9][0-9]-*.md`, parse the leading 4-digit number,
+  take `max + 1` (zero-padded to 4). For an empty area, start at
+  `0001`. `README.md` is **not** an ADR — skip it.
 
-Reject re-use of existing number — index regeneration treats
-duplicates as hard failure on both surfaces.
+Reject re-use of an existing number — index regeneration treats
+duplicates as a hard failure on both surfaces.
 
 ### 3. Pick a slug
 
@@ -100,9 +100,9 @@ directory. Examples: `kernel-swap-deferred`, `flat-cluster-subs`,
 
 ### 4. Author the ADR
 
-Use surface-specific template. All sections required; "—" acceptable
-for genuinely empty Alternatives or References blocks but never for
-Status, Context, Decision, or Consequences.
+Use the surface-specific template. All sections are required; "—"
+is acceptable for genuinely empty Alternatives or References blocks
+but never for Status, Context, Decision, or Consequences.
 
 **Flat-surface template** (`docs/decisions/ADR-NNN-<slug>.md`):
 
@@ -138,7 +138,7 @@ phase: <roadmap> · <phase-id>
 ## Context / Decision / Considered alternatives / Consequences / References
 ```
 
-Per-area ADRs use quote-style header (no YAML frontmatter) so
+Per-area ADRs use a quote-style header (no YAML frontmatter) so
 `audit_adr_coverage.py`'s permissive parser can index them. Cite
 the area's contract from the README in
 [`docs/adrs/<area>/README.md`](../../../docs/adrs/).
@@ -156,11 +156,15 @@ the area's contract from the README in
 
 - Flat: `./scripts-run src/scripts/adr/regenerate_index --check` exits 0.
 - Per-area: `./scripts-run src/scripts/audit_adr_coverage --check` exits 0.
-- Project's CI / quality pipeline passes locally.
+- The project's CI / quality pipeline passes locally.
 
 ## Rubric pass (optional, surfacing-only)
 
-After drafting ADR, run [`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md) with rubric `architecture-score` to confirm alternatives, consequences, reversibility, risk present. Invoke when user asks for completeness check — not on every ADR.
+After drafting an ADR, run
+[`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md)
+with rubric `architecture-score` to confirm alternatives, consequences,
+reversibility, and risk are present. Invoke when the user asks for a
+completeness check — not on every ADR by default.
 
 ## Output format
 
@@ -172,17 +176,19 @@ After drafting ADR, run [`judge-artifact-completeness`](../judge-artifact-comple
 ## Gotchas
 
 - **Flat default path** is `docs/decisions/` in this package; some
-  projects use `docs/adr/`. Pass `--dir` when running outside default.
-- **Per-area numbering is 4-digit** (`NNNN-<slug>.md`); flat surface
-  stays 3-digit (`ADR-NNN-<slug>.md`). Do not mix.
-- **Area inventory closed** — `<area>` must already exist in `AREAS`
-  in `scripts/audit_adr_coverage.py`. Adding new area is separate
-  PR with explicit reviewer sign-off.
-- Frontmatter `adr:` (flat) is canonical number; filename prefix
-  must match. Flat regenerator fails on mismatch.
-- ADRs are append-only history. To revise, write new ADR with
-  `supersedes: ADR-MMM` (flat) or `Supersedes:` line in header
-  quote-block (per-area) and flip old one's status to `superseded`.
+  projects use `docs/adr/`. Pass `--dir` when running outside the
+  default.
+- **Per-area numbering is 4-digit** (`NNNN-<slug>.md`); the flat
+  surface stays 3-digit (`ADR-NNN-<slug>.md`). Do not mix.
+- **Area inventory is closed** — `<area>` must already exist in
+  `AREAS` in `scripts/audit_adr_coverage.py`. Adding a new area is
+  a separate PR with explicit reviewer sign-off.
+- Frontmatter `adr:` (flat) is the canonical number; the filename
+  prefix must match. The flat regenerator fails on mismatch.
+- ADRs are append-only history. To revise a decision, write a new
+  ADR with `supersedes: ADR-MMM` (flat) or a `Supersedes:` line in
+  the header quote-block (per-area) and flip the old one's status
+  to `superseded`.
 - Never delete an ADR file — supersede it. Deletion breaks
   historical links and round-trips through git history checks.
 

package/dist/agent-src/skills/agent-docs-writing/SKILL.md

@@ -253,11 +253,29 @@ to every agent-doc update you author.
    relevant rule?
 4. Is German prose present outside `DE: / EN:` anchor blocks?
 
+## User inbox workflow (agents/tmp/)
+
+Command/skill consumes `agents/tmp/` file as INPUT (roadmap created from it,
+note promoted) → move source to `agents/tmp.old/<original-name>` in the
+**same reply** as the output.
+
+```bash
+mv agents/tmp/<filename> agents/tmp.old/<filename>
+```
+
+- Move only files **explicitly named as input**. Never sweep other `tmp/` files.
+- No confirmation needed — both dirs gitignored, local-only.
+- Never write agent scratch into `agents/tmp/` — use `agents/runtime/tmp/`.
+
+See `docs/contracts/agents-layout.md § User Inbox Workflow`.
+
 ## Do NOT
 
 - Do NOT create docs unless there's a real need (new module, significant change).
 - Do NOT duplicate information already in AGENTS.md or copilot-instructions.md.
 - Do NOT write docs just to document what you did — only document things others need to know.
+- Do NOT write agent scratch into `agents/tmp/` — that is the user's inbox.
+- Regen-only outputs (`agents/evidence/analysis/*`, `agents/reports/*` script-generated): commit only with the work that consumed them; side-effect regens discard via `git checkout --` before session end. See `docs/contracts/agents-layout.md § Session-leftover discipline`.
 
 ## Auto-trigger keywords
 

package/dist/agent-src/skills/agent-security-review/SKILL.md

@@ -42,7 +42,7 @@ Inspect the config the agent loads and check each surface: instruction files
 scripts, permission/auto-approve settings, persistent memory. Static pass first:
 
 ```bash
-python3 src/scripts/security_audit_config.py --root <repo> --json
+./scripts-run src/scripts/security_audit_config --root <repo> --json
 ```
 
 ### 2. Red team (attacker lens)

package/dist/agent-src/skills/ai-council/SKILL.md

@@ -4,6 +4,7 @@ name: ai-council
 description: "Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'."
 domain: process
 meta_skill: true
+parallelizable: independent
 workspaces:
   - agent-config-maintainer
 packs:
@@ -426,7 +427,19 @@ Every council reply MUST contain, in this order:
 2. **One section per member**, titled `### <provider> · <model>`,
    containing the member's verbatim output.
 3. **Convergence / Divergence summary** — bullet list, every claim
-   attributed by provider name.
+   attributed by provider name. **When the convergence settles a
+   question as "don't relitigate" / locked / a durable disposition**,
+   the summary MUST record two additional lines, per
+   [`decision-revisit-gate`](../../rules/decision-revisit-gate.md):
+   `scope:` (exactly which mechanism or question is settled — narrow
+   enough that a superficially similar but different proposal is not
+   silently covered) and `revisit-if:` (at least one concrete condition
+   that reopens it — new evidence class, model-generation or tooling
+   change, an N-th blocked encounter, or an age threshold). A lock
+   recorded without both lines is an authoring error. Also state
+   whether the disposition is **settled-by-evidence** (an eval ran) or
+   **settled-by-decision** (a maintainer call) — the latter is cheaper
+   to reopen and should say so.
 4. **Host verdict per finding** — one row per finding with `accept`
    / `accept-with-modification` / `reject` / `needs-input` plus a
    one-line reason citing host evidence (file:line, ADR, contract).

package/dist/agent-src/skills/blameless-post-mortem/SKILL.md

@@ -2,7 +2,6 @@
 model_tier: high
 name: blameless-post-mortem
 description: "Use after an incident or outage is resolved — blame-free facilitation, root cause, corrective actions, memory write-back — even for a near-miss. Consumes the incident-commander skeleton."
-source: package
 domain: quality
 personas:
   - senior-engineer
@@ -11,11 +10,9 @@ workspaces:
   - engineering
 packs:
   - analysis-workbench
-lifecycle: active
 trust:
   level: professional
   confidence: medium
-  human_review_required: false
 install:
   default: false
   removable: true

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

@@ -52,7 +52,7 @@ Provenance: [`ATTRIBUTION.md`](ATTRIBUTION.md); manifest:
 1. **Ground or search** (paths resolve skill-relative; works from any cwd):
 
    ```bash
-   python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+   ./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
      --manifest <skills-root>/brand/data/manifest.json \
      "<brand brief: sector + intent + audience>" \
      [--domain archetype|voice|naming|color|logo|messaging|typography] \

package/dist/agent-src/skills/brand-identity/SKILL.md

@@ -35,7 +35,7 @@ Grounding + Method skill. Turns a confirmed brand strategy into an identity cons
 2. **Ground the colour story** via the brand corpus:
 
 ```bash
-python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
   --manifest <skills-root>/brand/data/manifest.json \
   "<archetype + sector>" --domain color --json
 ```
@@ -45,7 +45,7 @@ python3 <skills-root>/corpus-grounding/scripts/ground.py search \
 3. **Ground the type story** via:
 
 ```bash
-python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
   --manifest <skills-root>/brand/data/manifest.json \
   "<archetype + sector>" --domain typography --json
 ```
@@ -55,7 +55,7 @@ python3 <skills-root>/corpus-grounding/scripts/ground.py search \
 4. **Ground the logo direction** via:
 
 ```bash
-python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
   --manifest <skills-root>/brand/data/manifest.json \
   "<archetype + sector>" --domain logo --json
 ```

package/dist/agent-src/skills/brand-strategy/SKILL.md

@@ -35,7 +35,7 @@ Grounding skill. Consults the brand corpus to surface archetype, positioning, vo
 2. **Ground via the corpus.** Run the corpus engine for each required domain. Start with archetype, then voice, then messaging:
 
 ```bash
-python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
   --manifest <skills-root>/brand/data/manifest.json \
   "<sector + audience + intent>" --domain archetype --json
 ```

package/dist/agent-src/skills/brand-to-tokens/SKILL.md

@@ -49,13 +49,13 @@ execution:
 3. **Generate** CSS vars + Tailwind through the toolchain:
 
    ```bash
-   python3 <skills-root>/design-tokens/scripts/tokens.py generate \
+   ./scripts-run <skills-root>/design-tokens/scripts/tokens generate \
      --config .tokens.json -o assets/design-tokens.css
-   python3 <skills-root>/design-tokens/scripts/tokens.py generate \
+   ./scripts-run <skills-root>/design-tokens/scripts/tokens generate \
      --config .tokens.json --format tailwind
    ```
 
-4. **Validate** — `python3 <skills-root>/design-tokens/scripts/tokens.py
+4. **Validate** — `./scripts-run <skills-root>/design-tokens/scripts/tokens
    validate --dir src/` until clean (exit 0 is the evidence); convert
    hardcoded values to `var(--token)`.
 5. **Export the deck templates** — emit the locked-variable brand deck

package/dist/agent-src/skills/canvas-design/SKILL.md

@@ -145,3 +145,9 @@ Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md).
 * Skip the philosophy file — the artifact without it is just an image
 * Skip the refinement pass
 * Write binary artifacts to the repo root or to source-of-truth dirs
+
+## See also
+
+- [`html-deck`](../html-deck/SKILL.md) — multi-slide HTML presentations
+  (fixed-canvas deck with navigation); this skill owns single-frame static
+  art, not decks.

package/dist/agent-src/skills/check-refs/SKILL.md

@@ -9,12 +9,15 @@ execution:
   timeout_seconds: 60
   allowed_tools: []
   command:
-    - python3
-    - src/scripts/check_references.ts
+    - ./scripts-run
+    - src/scripts/check_references
 workspaces:
   - agent-config-maintainer
 packs:
   - meta
+gaps:
+  - description: "Only validates references to known-root paths (docs/, skills/, rules/, commands/, contexts/, personas/, …). A relative-path link such as `./sibling.md` or `../foo.md` is not matched, so a broken relative link is never reported."
+    witness: tests/scripts/witness/check_refs_relative_gap.test.ts
 ---
 
 # check-refs
@@ -52,7 +55,7 @@ this skill's frontmatter governs the call:
 ```
 
 The dispatcher resolves the request, the shell handler runs
-`python3 src/scripts/check_references.ts`, captures stdout/stderr, and returns a
+`./scripts-run src/scripts/check_references`, captures stdout/stderr, and returns a
 typed `ExecutionResult`.
 
 ### 3. Verify the result
@@ -63,7 +66,7 @@ Check the returned `ExecutionResult`:
 - `exit_code: 1` → at least one broken reference — read `stdout` for file,
   line, and the offending ref, then fix the source or update the target
 - `status: timeout` → the checker exceeded `timeout_seconds` — investigate
-- `status: error` → interpreter or script missing — confirm `python3` and
+- `status: error` → runner or script missing — confirm `./scripts-run` and
   `src/scripts/check_references.ts` are available at the repository root
 
 ## Output format

package/dist/agent-src/skills/code-review/SKILL.md

@@ -3,6 +3,7 @@ model_tier: high
 name: code-review
 description: "Use when the user says \"review this\", \"check my code\", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards."
 domain: quality
+parallelizable: files
 workspaces:
   - engineering
 packs: