@event4u/agent-config 7.5.0 → 8.1.0

package/dist/agent-src/skills/release-comms/SKILL.md

@@ -21,77 +21,77 @@ install:
 
 ## When to use
 
-- Release shipping with user-facing change, team about to send feature-list email.
-- Changelog draft reads like commit log — engineering-honest, unparseable for user.
-- Multiple comms surfaces (in-app, email, social, docs) about to be written by different people from same release.
+- A release is shipping that contains user-facing change and the team is about to send a feature-list email.
+- A changelog draft reads like a commit log — engineering-honest, but unparseable for the user.
+- Multiple comms surfaces (in-app, email, social, docs) are about to be written by different people from the same release.
 
 Do NOT use for incident comms (see `incident-commander`),
-deprecation announcements needing legal sign-off, or pre-release
-discovery — this skill assumes change is **shipped**.
+deprecation announcements that need legal sign-off, or pre-release
+discovery — this skill assumes the change is **shipped**.
 
 ## Cognition cluster
 
-- **Mental model 16 — Leading vs. lagging indicators.** Release note
-  is lagging artifact; leading version = in-app prompt that fired
-  before user found change-log. See
+- **Mental model 16 — Leading vs. lagging indicators.** A release
+  note is the lagging artifact; the leading version is the in-app
+  prompt that fired before the user found the change-log. See
   [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 16.
-- **Value-not-feature heuristic.** Every paragraph passes *"so the
-  user can ___"* completion. Failing rows go back for re-write.
+- **Value-not-feature heuristic.** Every paragraph passes the *"so
+  the user can ___"* completion. Failing rows go back for re-write.
 
 ## Procedure
 
 ### Step 0: Ground the release
 
-1. Read merged PR list / changelog block / release branch diff. Release = **what**; comms = **so what**. Conflate the two → ship marketing.
-2. Read **product** and **team** slots of [context-spine](../../../docs/contracts/context-spine.md) (if consumer filled them) for bounded scope and cadence — surface choice depends on cadence (weekly: in-app + log; quarterly: email + post; major: all four).
-3. Identify **single dominant change** the release ships. Three "headliners" reads as three half-announcements.
+1. Read the merged PR list / changelog block / release branch diff. The release is the **what**; comms is the **so what**. Conflate the two and you ship marketing.
+2. Read the **product** and **team** slots of the [context-spine](../../../docs/contracts/context-spine.md) (if the consumer project has filled them) for bounded scope and release cadence — surface choice depends on cadence (weekly: in-app + log; quarterly: email + post; major: all four).
+3. Identify the **single dominant change** the release ships. A release with three "headliners" reads as three half-announcements.
 
 ### Step 1: Audience-segment
 
-1. Three audiences max: **active user**, **at-risk / lapsed user**, **prospect**. More fragments message; fewer hides routing.
-2. Per audience, write one sentence: *"After this release, you can …"* completing with user-side verb, not product-side feature.
-3. If two audiences end up with same sentence, collapse — segmentation that does not change message = theatre.
+1. Three audiences max: **active user**, **at-risk / lapsed user**, **prospect**. More segments fragment the message; fewer hides the routing.
+2. Per audience, write one sentence: *"After this release, you can …"* completing with a user-side verb, not a product-side feature.
+3. If two audiences end up with the same sentence, collapse them — segmentation that does not change the message is theatre.
 
 ### Step 2: Map surfaces to audiences
 
 1. **Changelog** (always) — engineers + power users; truthful, dense, link-heavy. Source of truth — every other surface points back here.
 2. **In-app prompt** — active users; ≤ 1 sentence + 1 CTA; fires for users whose past behaviour predicts they'll touch the new path.
 3. **Email** — at-risk / lapsed; one headline value, one CTA, one paragraph of context. No feature lists.
-4. **Social / blog** — prospect; the **why**, not the **what** — frame against user job (cite [`customer-research`](../customer-research/SKILL.md) if switch-event surfaced).
+4. **Social / blog** — prospect; the **why**, not the **what** — frame against the user job (cite [`customer-research`](../customer-research/SKILL.md) if a switch-event surfaced).
 
-Cut surfaces aggressively. Weekly release does not need blog post.
+Cut surfaces aggressively. A weekly release does not need a blog post.
 
 ### Step 3: Draft each surface from the changelog
 
-1. Open changelog. Per surface, copy dominant change line, then **rewrite verb subject** from "we" to "you".
-2. Strip qualifiers ("now", "even better", "lightning-fast"). Noise, not signal.
-3. Run *"so the user can ___"* completion on every paragraph. Failing paragraphs cut, not edited.
+1. Open the changelog. Per surface, copy the dominant change line, then **rewrite the verb subject** from "we" to "you".
+2. Strip qualifiers ("now", "even better", "lightning-fast"). They are noise, not signal.
+3. Run the *"so the user can ___"* completion on every paragraph. Failing paragraphs are cut, not edited.
 
 ### Step 4: Truth-check
 
-1. Every claim links back to changelog row or doc URL. Unsourced claim → cut.
-2. No tense games — past for shipped, future for coming-soon (and only if date is committed). "Roadmap" lives outside this skill.
-3. Names match product surface. In-app says "Reports" and email says "Insights" → user fires lookup tax.
+1. Every claim links back to a changelog row or a doc URL. Unsourced claim → cut.
+2. No tense games — past for shipped, future for coming-soon (and only if the date is committed). "Roadmap" lives outside this skill.
+3. Names match the product surface. If the in-app says "Reports" and the email says "Insights", the user fires the lookup tax.
 
 ### Step 5: Hand off
 
-1. Produce four artifacts (see `## Output`).
-2. Hand to whoever owns send. Do not embed scheduling or A/B test plans here — that is RevOps.
+1. Produce the four artifacts (see `## Output`).
+2. Hand to whoever owns the send. Do not embed scheduling or A/B test plans here — that is RevOps.
 
 ## Related Skills
 
 **WHEN to use this**
 
-- Change is **shipped** and needs to reach existing users.
-- Multiple comms surfaces written by different people from same source.
-- Team about to default to feature-list email.
+- The change is **shipped** and needs to reach existing users.
+- Multiple comms surfaces will be written by different people from the same source.
+- The team is about to default to a feature-list email.
 
 **WHEN NOT to use this**
 
-- Production incident comms → [`incident-commander`](../incident-commander/SKILL.md).
-- Pre-release discovery / validation → [`customer-research`](../customer-research/SKILL.md).
-- Funnel-stage diagnostics post-release → [`funnel-analysis`](../funnel-analysis/SKILL.md).
-- Ranking which release to comms next → [`rice-prioritization`](../rice-prioritization/SKILL.md).
+- Production incident comms — route to [`incident-commander`](../incident-commander/SKILL.md).
+- Pre-release discovery / validation — route to [`customer-research`](../customer-research/SKILL.md).
+- Funnel-stage diagnostics post-release — route to [`funnel-analysis`](../funnel-analysis/SKILL.md).
+- Ranking which release to comms next — route to [`rice-prioritization`](../rice-prioritization/SKILL.md).
 
 ## When the agent should load this
 
@@ -104,29 +104,30 @@ Cut surfaces aggressively. Weekly release does not need blog post.
 ## Output
 
 1. **`release-narrative.md`** — single source of truth: dominant change, audiences (1–3), per-audience *"After this release, you can …"* sentence, links to source changelog rows.
-2. **`changelog-entry.md`** — engineer-honest, dense, link-heavy block ready to paste into project's changelog.
-3. **`comms-pack.md`** — per-surface drafts (in-app prompt, email, optional social/blog), each ≤ surface's hard cap, each pointing back to `changelog-entry.md`.
-4. **`comms-checklist.md`** — pre-send checks: every claim sourced, names consistent across surfaces, audience match, "so the user can …" completion passing on every paragraph. Hand-off artifact for senior PO ([`product-owner`](../../personas/product-owner.md)).
+2. **`changelog-entry.md`** — engineer-honest, dense, link-heavy block ready to paste into the project's changelog.
+3. **`comms-pack.md`** — per-surface drafts (in-app prompt, email, optional social/blog), each ≤ the surface's hard cap, each pointing back to `changelog-entry.md`.
+4. **`comms-checklist.md`** — pre-send checks: every claim sourced, names consistent across surfaces, audience match, "so the user can …" completion passing on every paragraph. Hand-off artifact for the senior PO ([`product-owner`](../../personas/product-owner.md); senior persona shipping in next plate).
 
 ## Gotcha
 
-- Default failure mode = feature-list email — written to make engineering feel seen, not to help user.
-- Marketing puffery ("revolutionary", "delightful") fails source check; cut on sight.
-- Two surfaces using different names for same thing = highest-frequency support-ticket trigger after release.
+- The default failure mode is feature-list email — written to make engineering feel seen, not to help the user.
+- Marketing puffery ("revolutionary", "delightful") fails the source check; cut on sight.
+- Two surfaces using different names for the same thing is the highest-frequency support-ticket trigger after a release.
 - Hidden coming-soon claims in past-tense paragraphs erode trust faster than missing the comms entirely.
 
 ## Do NOT
 
-- Do NOT promote coming-soon item alongside shipped items — user cannot tell which is which and stops trusting next note.
-- Do NOT let long-tail change steal the headline — dominant change earns headline, long tail goes in changelog.
-- Do NOT ship surfaces without truth-check pass; unsourced claim survives in social longer than release does.
+- Do NOT promote a coming-soon item alongside shipped items — the user cannot tell which is which and stops trusting the next note.
+- Do NOT let a long-tail change steal the headline — the dominant change earns the headline, the long tail goes in the changelog.
+- Do NOT ship surfaces without the truth-check pass; an unsourced claim survives in social longer than the release does.
+- Do NOT paste more than a short excerpt from a linked source (commit message, PR body, issue thread) — `content-quoting-floor` caps verbatim quotes at 15 words, one per source; paraphrase the rest.
 
 ## Runnable example
 
 Sprint 47 ships a one-click monthly export and three small bug fixes:
 
 - Dominant change: one-click export. Bug fixes go in changelog only.
-- Audiences: active user (will use it), at-risk (export friction was churn trigger per [`customer-research`](../customer-research/SKILL.md) evidence-log).
+- Audiences: active user (will use it), at-risk (export friction was a churn trigger per [`customer-research`](../customer-research/SKILL.md) evidence-log).
 - "After this release, you can pull a board-ready monthly report in one click." (active, at-risk — same sentence ⇒ collapse to one).
-- Surfaces: changelog (full), in-app prompt to active users on next month-end, email to at-risk cohort with same sentence and one CTA. No social.
-- Truth-check: claim links to export PR; "one click" is literal — verified against shipped UI.
+- Surfaces: changelog (full), in-app prompt to active users on next month-end, email to at-risk cohort with the same sentence and one CTA. No social.
+- Truth-check: claim links to the export PR; "one click" is literal — verified against the shipped UI.

package/dist/agent-src/skills/roadmap-management/SKILL.md

@@ -212,6 +212,16 @@ unfamiliar codebases.
 
 ### Executing a roadmap
 
+0. Read `execution.mode` from the roadmap frontmatter
+   (`autonomous` | `phase-checkpoints` | `interactive`; absent =
+   `interactive`). Under `/roadmap:process-*` the mode selects the
+   interaction pattern via the run-start execution contract — see
+   [`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
+   The manual flow below describes `interactive`; under `autonomous`
+   / `phase-checkpoints` step 4's per-step ask is replaced by the
+   accepted contract. **Mode never changes archival semantics** —
+   glyph counting, the closure decision table, and the Iron Law 3
+   deferred-resolution gate below apply identically in every mode.
 1. Read the full roadmap.
 2. Find the next unchecked step (`- [ ]`).
 3. Summarize what needs to be done.
@@ -455,6 +465,17 @@ No global tooling required.
 
 The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate it.
 
+### Blockers on the dashboard
+
+Overview table's `Blocker` column counts each roadmap's open
+`## Blockers` entries (or legacy `> Blocked until` note), links to
+per-roadmap breakdown, which lists every open blocker with owner,
+blocked scope, full instructions. Authoring shape:
+[`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md);
+authoring guidance: [`roadmap-writing § 5b`](../roadmap-writing/SKILL.md).
+Clearing a blocker flips `Status: resolved`, regenerates dashboard in
+same reply — same cadence as a checkbox flip.
+
 ## Rubric pass (optional, surfacing-only)
 
 After producing roadmap, run [`judge-artifact-completeness`](../judge-artifact-completeness/SKILL.md) with rubric `roadmap-score` to surface missing dimensions (risk, tests, migration, maintainability). Score is a recommendation; never blocks shipping. Invoke only when user wants completeness check — not by default.

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

@@ -84,6 +84,25 @@ and council-pass notes capture the *why*; checkboxes capture the
 [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
 Iron Law #2.
 
+### 4b. Declare the execution mode (frontmatter)
+
+Every new roadmap declares how a later `/roadmap:process-*` run should
+interact, via `execution.mode:` in frontmatter — `autonomous` (one
+run-start execution-contract confirmation, then uninterrupted except
+safety floors), `phase-checkpoints` (halt + compact status per phase
+boundary), or `interactive` (absent-field default; omit field).
+Semantics: [`templates/roadmaps.md` rule 19](../../templates/roadmaps.md);
+run mechanics:
+[`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
+Field is intent, never a permission grant — grants happen only at the
+run-start contract. `/roadmap:create` asks this as one question; when
+authoring a roadmap directly, ask it too (follow-ups pre-select the
+parent's mode but always re-ask). **Authoring duty for `autonomous`:**
+steps must be precise enough to clear `ask-when-uncertain` vague-
+trigger patterns — vagueness resolved at authoring time, not mid-run;
+pre-existing `[~]` items in an `autonomous` roadmap draw a lint
+warning (they guarantee the archival gate fires later).
+
 ### 5. Exit & rollback per phase
 
 Each phase declares **exit criteria** (decidable signals that the
@@ -91,6 +110,17 @@ phase is done) and **rollback** (what to revert if the phase fails).
 A phase without exit criteria is open-ended; a phase without
 rollback assumes success.
 
+### 5b. Blockers are structured, not free prose
+
+Gate only user or maintainer can clear — decision, external
+dependency, evidence threshold, kernel-budget soak window — records
+as `## Blockers` entry (`### blocker: <id>` with `Status` / `Owner` /
+`Blocks` / `What to do` / `Resolved when`), never a stray "blocked on
+X" sentence. Dashboard generator parses these into overview's
+`Blocker` column and per-roadmap breakdown. Full shape:
+[`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md).
+Omit section entirely when roadmap has no such gate.
+
 ### 6. Step-marker semantics — pick `[~]` (defer) vs `[-]` (cancel) honestly
 
 Difference carries load when authoring (and especially when rewriting
@@ -166,7 +196,7 @@ capabilities into the suite:
 
 Ordinary internally-originated roadmap → **skip this section**; §§ 0–7
 are the whole job. Don't bolt a Provenance block or gap-table onto a
-plan needing neither (template rule 18).
+plan needing neither (template rule 19).
 
 When it fires, add four moves to §§ 0–7:
 
@@ -282,7 +312,7 @@ to every roadmap you author.
   skill dump, not integration.
 * Add a `## Provenance` block (or gap-table) to an **internally
   originated** roadmap — § 8 is conditional; an empty Provenance section
-  is noise (template rule 18).
+  is noise (template rule 19).
 * Name the raw competitor / tool in a tracked roadmap, or paste a raw
   source link — anonymize + `ENC1:`-encrypt
   ([`source-confidentiality`](../../rules/source-confidentiality.md)).

package/dist/agent-src/skills/root-cause-frameworks/SKILL.md

@@ -1,18 +1,15 @@
 ---
 name: root-cause-frameworks
 description: "Use when tracing the root cause of a resolved incident or recurring bug — 5-whys chain, fishbone categorisation, contributing-factors split — even if the user says 'why does this keep breaking?'."
-source: package
 domain: quality
 model_tier: high
 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/security-audit/SKILL.md

@@ -3,6 +3,7 @@ model_tier: high
 name: security-audit
 description: "ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work."
 domain: quality
+parallelizable: files
 workspaces:
   - engineering
 packs:

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -116,6 +116,10 @@ After creation:
 2. Copy to `.augment/`
 3. Mark hash: `./scripts-run src/scripts/condense --mark-done "{relative_path}"`
 4. Regenerate tools: `./scripts-run src/scripts/condense --generate-tools`
+5. **If from a knowledge page** (`agents/knowledge/procedures/skill-candidates.md`
+   or any `agents/knowledge/` page) — degrade the source to a pointer;
+   promotion isn't complete otherwise (double-maintenance risk):
+   `./scripts-run src/scripts/degrade_to_pointer --source "<knowledge-path>[#<anchor>]" --artifact "{relative_path}" --date "<YYYY-MM-DD>"`
 
 ### Step 5: Decide scope
 

package/dist/agent-src/skills/source-discovery/SKILL.md

@@ -38,9 +38,9 @@ discover the real source  →  Evidence Report (Verified / Assumed / Gaps)  →
 Scaffold the report cheaply so it never gets skipped:
 
 ```bash
-python3 src/scripts/evidence_report.py git-state            # fail-fast: abort if a rebase/merge/cherry-pick is in progress
-python3 src/scripts/evidence_report.py init --task "<task>" # writes the gitignored session report
-python3 src/scripts/evidence_report.py add --bucket verified --claim "users.email is unique" --source "db/schema/users.sql:23"
+./scripts-run src/scripts/evidence_report git-state            # fail-fast: abort if a rebase/merge/cherry-pick is in progress
+./scripts-run src/scripts/evidence_report init --task "<task>" # writes the gitignored session report
+./scripts-run src/scripts/evidence_report add --bucket verified --claim "users.email is unique" --source "db/schema/users.sql:23"
 ```
 
 **Provenance on every item** (`observed_at` / `source` / `version`). Within a
@@ -165,6 +165,25 @@ signal, never silently commit); trust and commit are always human-gated. Full mo
 the three classes + memory tiers:
 [`project-intelligence`](../../agent-src/contexts/execution/project-intelligence.md).
 
+## Knowledge capture (`api_shape_learned` / `convention_detected` events)
+
+A confirmed API/GraphQL shape (§B) or an observed coding convention with
+≥ 2 supporting locations is worth persisting for the team, distinct
+from the per-session Evidence Report above. Append to the knowledge
+intake — never write a tracked page mid-task:
+
+```bash
+./scripts-run src/scripts/emit_knowledge_event --type api_shape_learned \
+    --endpoint "<path>" --method "<verb>" --request-schema '<json>' --response-schema '<json>'
+
+./scripts-run src/scripts/emit_knowledge_event --type convention_detected \
+    --pattern "<pattern>" --evidence "file:line" --sample-size <N> --scope project
+```
+
+`/team-knowledge consolidate` turns accumulated events into
+`agents/knowledge/concepts/` pages as a reviewed batch — see
+[`knowledge-pages`](../../templates/contexts/knowledge-pages.md).
+
 ## Gotchas
 
 - A card's positive structure is **never** "Verified" on the card alone — it is

package/dist/agent-src/skills/subagent-orchestration/SKILL.md

@@ -307,22 +307,41 @@ prefer the cheaper one (`do-and-judge` < `do-and-judge-two-stage` <
 
 ### 4. Dispatch
 
-Hand off to the matching command:
-
-* `do-and-judge` → [`/do-and-judge`](../../commands/do-and-judge.md)
-* `do-in-steps` → [`/do-in-steps`](../../commands/do-in-steps.md)
-* `judge` (standalone) → [`/judge`](../../commands/judge.md)
-
-Modes without a dedicated command (`do-in-parallel`,
-`do-competitively`, `judge-with-debate`) are orchestrated inline via
-the skill — describe the dispatch explicitly in chat so the user can
-follow it.
+Use the matching dispatch prompt and orchestrate inline via this skill.
+Describe each dispatch step explicitly in chat so the user can follow it.
+
+* `do-and-judge` → [`prompts/do-and-judge.md`](prompts/do-and-judge.md)
+* `do-and-judge-two-stage` → [`prompts/do-and-judge-two-stage.md`](prompts/do-and-judge-two-stage.md)
+* `do-in-steps` → [`prompts/do-in-steps.md`](prompts/do-in-steps.md)
+* `do-in-parallel` → [`prompts/do-in-parallel.md`](prompts/do-in-parallel.md)
+* `do-competitively` → [`prompts/do-competitively.md`](prompts/do-competitively.md)
+* `judge-with-debate` → [`prompts/judge-with-debate.md`](prompts/judge-with-debate.md)
+* `do-in-worktrees` → [`prompts/do-in-worktrees.md`](prompts/do-in-worktrees.md)
+* Standalone judge → judge prompt in [`prompts/do-and-judge.md`](prompts/do-and-judge.md)
 
 ### 5. Report
 
 Follow the output format below. Never merge a diff without reporting
 the judge verdict.
 
+### 6. Emit telemetry
+
+After every auto-dispatched run, write one telemetry line to
+`agents/runtime/state/audit/YYYY-MM.jsonl` (current UTC month — use
+`new Date().toISOString().slice(0, 7)` for the filename). Standard
+audit-log-v1 object with `input_kind: "orchestration"` and an
+`orchestration` sub-object per
+[`orchestration-telemetry.md`](../../agent-src/contexts/execution/orchestration-telemetry.md).
+
+Minimal emit (fill what is observable; `token_delta_provenance: "estimated"` if
+host usage metadata is unavailable):
+
+```json
+{"schema_version":1,"id":"<ulid>","ts":"<iso>","work_id":"<work_id>","phase":"implement","outcome":"success","confidence_band":"high","risk_class":"low","input_kind":"orchestration","type":"phase","orchestration":{"task_size_estimate":<int>,"spawn_count":<int>,"tiers":[...],"token_delta":<int>,"token_delta_provenance":"estimated","wall_clock_ms":<int>,"outcome":"DONE","verify_mode":"deterministic"}}
+```
+
+Skip emit when `subagents.enabled: false` or `spawn_count == 0` (in-session run).
+
 ## Gotcha
 
 * **Identical model both sides** — same blind spots. The Iron Law
@@ -358,10 +377,10 @@ the judge verdict.
 
 | Task                                 | Skill / command                      |
 |--------------------------------------|--------------------------------------|
-| Configuration reference              | [`subagent-configuration`](../../contexts/subagent-configuration.md) |
-| Do-and-judge loop                    | [`/do-and-judge`](../../commands/do-and-judge.md) |
-| Stepwise plan with judge gates       | [`/do-in-steps`](../../commands/do-in-steps.md) |
-| Standalone judge on an existing diff | [`/judge`](../../commands/judge.md)  |
+| Configuration reference              | [`subagent-configuration`](../../agent-src/contexts/execution/subagent-configuration.md) |
+| Do-and-judge loop                    | Inline — see [`prompts/do-and-judge.md`](prompts/do-and-judge.md) |
+| Stepwise plan with judge gates       | Inline — see [`prompts/do-in-steps.md`](prompts/do-in-steps.md) |
+| Standalone judge on an existing diff | Inline — see judge prompt in [`prompts/do-and-judge.md`](prompts/do-and-judge.md) |
 | External / networked second opinion  | [`ai-council`](../ai-council/SKILL.md) |
 | Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |
 | What a subagent owns vs never owns   | [`subagent-boundary`](../../../docs/contracts/subagent-boundary.md) |

package/dist/agent-src/skills/subagent-orchestration/prompts/README.md

@@ -22,6 +22,17 @@ Every prompt cites the status taxonomy in
 ends with the **return-envelope** instruction so the subagent's reply
 validates against `tests/test_subagent_status_schema.py`.
 
+## Prompt-cache discipline
+
+When dispatching sibling subagents (e.g. `do-in-parallel` with N independent
+slices), **reuse a stable system-prompt prefix** across all siblings. Keep
+task-invariant text (role declaration, constraints, status enum, return-envelope
+instruction) in the prefix; put only the slice-specific `TASK:` and
+`CONTEXT FILES:` in the variable section. This maximises host-side prompt-cache
+hits (Anthropic `cache_control: ephemeral`) across the cohort — the prefix is
+cached after the first sibling and served from cache for the rest, cutting
+input-token cost proportionally to cohort size.
+
 ## Loading
 
 `tests/test_subagent_prompt_loading.py` asserts that every mode named

package/dist/agent-src/skills/subagent-orchestration/prompts/do-in-steps.md

@@ -60,3 +60,11 @@ already mitigated, DONE. Otherwise DONE_WITH_CONCERNS.
 A step that returns BLOCKED stops the chain. The orchestrator does not
 "jump ahead" or re-order — it surfaces the BLOCKED envelope to the user
 and waits.
+
+## Dependency gate
+
+Every step after the first declares its parent (the preceding step). A
+step MUST NOT dispatch before its parent's return passed the judge —
+deterministic reference: `sliceDispatchAllowed()` in
+`src/scripts/_lib/subagent_steering.ts`, contract in
+[`subagent-steering § Ordered-slice dependency gate`](../../../contexts/execution/subagent-steering.md).

package/dist/agent-src/skills/systematic-debugging/SKILL.md

@@ -258,6 +258,35 @@ When reporting debug findings to the user:
 5. **Fix** — the minimal change
 6. **Regression test** — the test that catches this bug returning
 
+## Knowledge capture (`mistake_made` event)
+
+Root cause traces to a `agents/knowledge/` page followed while
+implementing (documented convention wrong, API-shape page stale,
+procedure incomplete) → append a `mistake_made` event to the
+knowledge intake — never rewrite the page mid-task (see
+[`knowledge-pages`](../../templates/contexts/knowledge-pages.md)):
+
+```bash
+./scripts-run src/scripts/emit_knowledge_event \
+    --type mistake_made \
+    --error-category "<one or two words>" \
+    --context-source "<agents/knowledge/... path, or 'null' if no page was followed>" \
+    --correction "<what the fix actually was>" \
+    --recurrence-key "<stable slug for this class of mistake>"
+```
+
+Verify the append landed: check the command's exit code (0 =
+appended), then `grep <recurrenceKey> agents/knowledge/intake/events-*.jsonl`
+finds the new line.
+
+**Live contradiction exception.** Followed page DEMONSTRABLY wrong
+right now (observed ≠ documented, not a one-off) → hybrid immediate-fix
+case instead — surface the correction, ask before continuing (see
+[`knowledge-pages`](../../templates/contexts/knowledge-pages.md) §
+Contested entries). Approved → isolated fix commit. Declined →
+`./scripts-run src/scripts/append_contested` on that page, then still
+emit the `context_stale` event above for the consolidation pass.
+
 ## Gotchas
 
 * Reading half a stack trace and jumping to a fix — the actual cause is

package/dist/agent-src/skills/threat-modeling/SKILL.md

@@ -16,8 +16,8 @@ packs:
 
 
 > **Grounded corpus (Tier-1 consultation):** ground surface → threats →
-> controls before enumerating from memory — `python3
-> <skills-root>/corpus-grounding/scripts/ground.py ground --manifest
+> controls before enumerating from memory — `./scripts-run
+> <skills-root>/corpus-grounding/scripts/ground ground --manifest
 > <skills-root>/threat-modeling/data/manifest.json "<surface description>"`
 > returns surface class, ATT&CK/CWE-cited threats, required controls, and
 > negative tests, with confidence + evidence-gap. Propose grounded

package/dist/agent-src/skills/typography-system/SKILL.md

@@ -54,7 +54,7 @@ degrades gracefully: with no brand layer, only stage 1 runs.
    `fontSize`, `fontWeight`, `lineHeight`.
 5. **Verify** — confirm both chosen fonts exist on Google Fonts (check the
    `Google Fonts URL` column in the CSV); run
-   `python3 <skills-root>/design-tokens/scripts/tokens.py validate --dir src/`
+   `./scripts-run <skills-root>/design-tokens/scripts/tokens validate --dir src/`
    to confirm no hardcoded font-size or font-family values remain outside the
    token file; exit code 0 is the evidence.
 
@@ -72,7 +72,7 @@ style, not the other way around.
    evidence gap):
 
    ```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
    ```

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

@@ -2,6 +2,8 @@
 model_tier: medium
 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."
+personas:
+  - production-validator
 domain: quality
 workspaces:
   - engineering

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

@@ -0,0 +1,118 @@
+---
+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."
+domain: product
+personas: []
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+trust:
+  level: professional
+install:
+  removable: true
+execution:
+  type: manual
+---
+
+# Wireframe
+
+Produce low-fidelity wireframes or storyboards to explore a flow, layout, or
+information hierarchy before committing to hi-fi design. Wireframes are
+**disposable** — their value is the breadth of options and the decision they
+produce, not the fidelity of any one artifact.
+
+## When to use
+
+- The user wants to "explore options", "sketch something out", "see a few
+  directions" for a screen, flow, navigation pattern, or hierarchy.
+- The design problem is open enough that hi-fi work would be wasted — the
+  structure question is not yet settled.
+
+**When NOT to use:** styled, production-viable alternatives on a settled
+structure → [`design-variations`](../design-variations/SKILL.md) (hi-fi,
+branded, recommendation-bearing). A single refined implementation →
+[`fe-design`](../fe-design/SKILL.md) + stack executor.
+
+## Procedure
+
+1. **Confirm the goal.** What is explored (screen / multi-screen flow /
+   navigation / hierarchy / interaction model), the imagined user's goal,
+   constraints (mobile/desktop, non-negotiable elements), the count
+   (3 minimum, 5–6 ceiling), and the **axis of variation**. If the axis is
+   open, propose 2–3 (e.g. single-page form vs multi-step wizard vs
+   progressive disclosure) and ask which to explore.
+2. **Hold the lo-fi conventions** so the output reads as wireframe, not as
+   broken hi-fi:
+   - greyscale only — black, white, 2–3 grays; no brand color;
+   - system sans-serif — no type personality yet;
+   - labeled boxes for content areas ("headline", "image", "feature card");
+   - striped placeholders with monospace size labels for imagery (the
+     honest-placeholder pattern in
+     [`fe-design § Craft details`](../fe-design/SKILL.md));
+   - short label-style skeleton copy ("Headline goes here / one sentence on
+     the value prop") — never Lorem ipsum (per `output-discipline`), never
+     final copy.
+3. **Sketch ≥3 variations** on the named axis — layout (centered / split /
+   grid), information density, flow structure (single page / multi-step /
+   progressive disclosure), CTA placement, navigation pattern. Write each
+   variation's distinguishing structure down BEFORE sketching it — left
+   unspecified, variations converge on near-identical layouts. Order
+   by-the-book → off-distribution; at least one genuinely novel bet.
+4. **Annotate** — 2–4 numbered callouts per variation naming what is
+   interesting and its trade-off ("fastest path, but heavy first
+   impression"), placed next to the variation, not in a separate doc.
+5. **Capture the decision** after the user picks: chosen variation (or
+   hybrid), what attracted them, what they explicitly rejected, new
+   constraints surfaced. This capture is the brief for the hi-fi follow-up.
+6. **Hand off** — [`design-variations`](../design-variations/SKILL.md) for
+   styled options on the chosen structure, or
+   [`design-intelligence`](../design-intelligence/SKILL.md) +
+   [`fe-design`](../fe-design/SKILL.md) for a single hi-fi direction. In an
+   existing codebase the hi-fi step still passes `existing-ui-audit` per the
+   `ui-audit-gate` rule.
+
+## Output format
+
+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.
+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,
+   attractions, explicit rejections, new constraints; framed as the hi-fi
+   brief.
+4. **No recommendation ranking** — wireframes surface trade-offs; the pick
+   belongs to the user (contrast: `design-variations` closes with a
+   recommendation).
+
+## Do NOT
+
+- Do NOT apply brand color, brand type, or real imagery — that pulls focus to
+  aesthetics before structure is settled.
+- Do NOT polish — wireframes are disposable thinking artifacts.
+- Do NOT write final copy or Lorem ipsum — label-style skeleton copy only.
+- Do NOT let variations converge — write each variation's structure down
+  before sketching.
+- Do NOT skip decision capture — an exploration round without a recorded
+  decision has to be re-litigated in the hi-fi round.
+- Do NOT embed system internals (paths, skill/tool names) in the artifact —
+  Q13 in [`design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md).
+
+## Gotcha
+
+- This is the one context where rough, hand-drawn-feeling shapes (rectangles,
+  lines, simple icons) are acceptable — everything sits at the same low
+  fidelity, so nothing reads as a failed asset (the V4/imagery antipatterns
+  apply to hi-fi, not here).
+- The wireframe file tends to get promoted into hi-fi by incremental edits —
+  don't. Start the hi-fi artifact fresh from the decision capture; the
+  wireframe's greyscale skeleton hard-codes non-decisions.
+
+## See also
+
+- [`design-variations`](../design-variations/SKILL.md) — hi-fi options on the chosen structure.
+- [`design-intelligence`](../design-intelligence/SKILL.md) — grounded direction selection for the hi-fi follow-up.
+- [`fe-design`](../fe-design/SKILL.md) — production heuristics + honest-placeholder pattern.
+- [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — mandatory pre-step once hi-fi work lands in a codebase.