@event4u/agent-config 16.2.0 → 16.3.0

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

@@ -0,0 +1,339 @@
+/**
+ * Auto-carry for the archival sweep: a finished roadmap whose only obstacle is
+ * bare `[~]` steps hands them to a follow-up roadmap and then archives.
+ *
+ * WHY. The dashboard renders a roadmap with zero open steps as 100 %, deferred
+ * steps included, while the sweep refused every bare `[~]` and waited for a
+ * human to write the `carried-to` annotation by hand. Nobody did: measured
+ * 2026-10-02, five roadmaps sat at 100 % in the active tree with fourteen
+ * unannotated deferrals between them, and `/roadmap:process-full` — which ends
+ * non-interactively — had no step that could resolve one. "Finished" and
+ * "archived" had silently come apart.
+ *
+ * The disposition this module executes is the one `roadmap-progress-sync`
+ * Iron Law 3 already routes to the council without the owner: carry the item
+ * AND its blocker into a named follow-up created in the SAME change. It keeps
+ * every criterion alive in the active estate, so it is the preserving branch of
+ * the preservation test, never a drop. The owner decided on 2026-10-02 that the
+ * sweep performs it automatically instead of waiting for a menu.
+ *
+ * What the carry does, so the archived parent and the live child agree:
+ *
+ *   - every bare `[~]` block is copied verbatim into the child as an OPEN `[ ]`
+ *     step — open, not `[~]`, because a child at 100 % on arrival would be
+ *     carried again by the next sweep, forever;
+ *   - the parent's step gets `<!-- deferred-resolution: carried-to=<child> -->`,
+ *     and the child gets `parent_roadmap: <parent>`, which is the pair
+ *     `deferralProblems` and `lint_deferral_integrity` validate from both ends;
+ *   - every OPEN blocker a carried step names via `blocked-by: <id>` moves with
+ *     it: copied verbatim into the child's `## Blockers`, and closed in the
+ *     parent with a status line naming where it went. The open-blocker count is
+ *     unchanged, it only changes file.
+ *
+ * NOT automatic when a moved blocker waits on the OWNER (owner decision
+ * 2026-10-02): the sweep then writes nothing and asks — archive with the steps
+ * parked in `later/` (`--owner-decision later`), or work them step by step with
+ * the first one on screen. The procedure lives in `roadmap-process-loop` § 6a.
+ *
+ * Refused, so nothing is written, when the parent would still not archive
+ * afterwards: an open blocker no carried step names is a decision the parent
+ * itself raised, and carrying around it would strand the child with steps that
+ * have no reason to exist apart from the parent. A human-written annotation
+ * that fails validation is also left alone — fixing someone's wrong carry is
+ * not this module's call.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * `<!-- deferred-resolution: carried-to=<slug> -->` — the resolved-deferral
+ * annotation. `merged-into=<slug>` is the second accepted form.
+ */
+export const DEFERRED_RESOLUTION_RE =
+    /<!--\s*deferred-resolution:\s*(carried-to|merged-into)\s*=\s*([A-Za-z0-9._-]+)\s*-->/;
+
+/** `- [~] …` — a deferred step, at any indent, with `-` or `*`. */
+export const DEFERRED_STEP_RE = /^[ \t]*[-*][ \t]+\[~\][ \t]*(.*)$/;
+
+/** Any other checkbox, or a heading — where a step's block ends. */
+export const BLOCK_END_RE = /^[ \t]*[-*][ \t]+\[[ xX~-]\]|^#{1,6}[ \t]/;
+
+const BLOCKED_BY_RE = /blocked-by:\s*([A-Za-z0-9._-]+)/g;
+const BLOCKER_HEAD_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/i;
+const STATUS_LINE_RE = /^([ \t]*-[ \t]+\*\*Status:\*\*[ \t]*)(.*)$/;
+const AC_HEADING_RE = /^##[ \t]+acceptance/i;
+const OWNER_LINE_RE = /^[ \t]*-[ \t]+\*\*Owner:\*\*[ \t]*`?([A-Za-z]+)/;
+
+/**
+ * Blocker owners that are NOT the human owner. Everything else — `maintainer`,
+ * `user`, `owner`, and any value this list does not name — is owner-dependent:
+ * in doubt it is the owner's decision, so an unrecognised owner fails closed.
+ */
+const AGENT_SIDE_OWNERS: ReadonlySet<string> = new Set(['implementer', 'council', 'agent', 'ai']);
+
+/**
+ * What happens to deferrals whose blockers wait on the owner.
+ *
+ * `ask` (default): nothing is written; the sweep reports the decision instead —
+ * archive with the steps parked in `later/`, or work them step by step.
+ * `later`: the owner chose to archive; the carry lands in `later/`.
+ */
+export type OwnerDecision = 'ask' | 'later';
+
+/** The lightweight cap `lint_roadmap_complexity` enforces, with margin. */
+const LIGHTWEIGHT_LINE_BUDGET = 500;
+
+const DISPOSITION_DIRS: readonly string[] = ['', 'later', 'archive', 'skipped'];
+
+interface BareStep {
+    /** Line index of the `[~]` line in the parent. */
+    line: number;
+    /** The step line plus its continuation block, dedented to the step. */
+    block: string[];
+    isAcceptance: boolean;
+    blockerIds: string[];
+}
+
+interface BlockerSpan {
+    id: string;
+    start: number;
+    end: number;
+    open: boolean;
+    ownerDependent: boolean;
+}
+
+export interface CarryPlan {
+    destSlug: string;
+    destRel: string;
+    destText: string;
+    sourceText: string;
+    carried: number;
+    movedBlockers: string[];
+    /** Moved blockers only the owner can resolve. Non-empty ⇒ the owner decides. */
+    ownerBlockers: string[];
+    /** The first carried step, verbatim, for the step-by-step offer. */
+    firstStep: string;
+    /** True when the carry targets `later/` (owner chose to archive). */
+    parked: boolean;
+}
+
+export type CarryOutcome = { plan: CarryPlan } | { refused: string };
+
+function _bareSteps(lines: readonly string[]): BareStep[] {
+    const out: BareStep[] = [];
+    let inAcceptance = false;
+    // No fence skipping, on purpose: `parseDeferredItems` does not skip fences
+    // either, and a step this module did not see but the sweep's validation does
+    // would be written, then refused.
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] as string;
+        if (/^##[ \t]/.test(line)) inAcceptance = AC_HEADING_RE.test(line);
+        const m = DEFERRED_STEP_RE.exec(line);
+        if (m === null) continue;
+        let end = i + 1;
+        while (end < lines.length && !BLOCK_END_RE.test(lines[end] as string)) end++;
+        const raw = lines.slice(i, end);
+        if (DEFERRED_RESOLUTION_RE.test(raw.join('\n'))) continue;
+        while (raw.length > 1 && (raw[raw.length - 1] as string).trim() === '') raw.pop();
+        const indent = (/^[ \t]*/.exec(line) as RegExpExecArray)[0].length;
+        const block = raw.map((l) => (l.slice(0, indent).trim() === '' ? l.slice(indent) : l));
+        const ids = new Set<string>();
+        for (const b of raw) for (const hit of b.matchAll(BLOCKED_BY_RE)) ids.add(hit[1] as string);
+        out.push({ line: i, block, isAcceptance: inAcceptance, blockerIds: [...ids] });
+    }
+    return out;
+}
+
+function _blockerSpans(lines: readonly string[]): BlockerSpan[] {
+    const start = lines.findIndex((l) => /^##[ \t]+Blockers[ \t]*$/i.test(l));
+    if (start === -1) return [];
+    let sectionEnd = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##[ \t]+\S/.test(lines[i] as string)) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    const spans: BlockerSpan[] = [];
+    for (let i = start + 1; i < sectionEnd; i++) {
+        const m = BLOCKER_HEAD_RE.exec(lines[i] as string);
+        if (m === null) continue;
+        let end = i + 1;
+        while (end < sectionEnd && !/^###?[ \t]/.test(lines[end] as string)) end++;
+        const status = lines
+            .slice(i, end)
+            .map((l) => STATUS_LINE_RE.exec(l))
+            .find((s) => s !== null);
+        const value = (status?.[2] ?? 'open').trim().toLowerCase();
+        const owner = lines
+            .slice(i, end)
+            .map((l) => OWNER_LINE_RE.exec(l))
+            .find((o) => o !== null);
+        spans.push({
+            id: (m[1] as string).trim(),
+            start: i,
+            end,
+            open: !/^resolved\b/.test(value),
+            ownerDependent: !AGENT_SIDE_OWNERS.has((owner?.[1] ?? '').toLowerCase()),
+        });
+    }
+    return spans;
+}
+
+function _plusDays(date: string, days: number): string {
+    const d = new Date(`${date}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}
+
+/** The first `<base>-carried[-N]` slug no roadmap directory already holds. */
+export function nextCarrySlug(root: string, sourceSlug: string): string {
+    const base = sourceSlug.replace(/-carried(-\d+)?$/, '');
+    for (let n = 1; ; n++) {
+        const slug = n === 1 ? `${base}-carried` : `${base}-carried-${n}`;
+        const taken = DISPOSITION_DIRS.some((d) =>
+            fs.existsSync(path.join(root, 'agents', 'roadmaps', d, `${slug}.md`)),
+        );
+        if (!taken) return slug;
+    }
+}
+
+function _title(sourceText: string, sourceSlug: string): string {
+    const h1 = /^#[ \t]+(.+?)[ \t]*$/m.exec(sourceText.replace(/^---\n[\s\S]*?\n---\n/, ''));
+    return h1 !== null ? (h1[1] as string) : sourceSlug.replace(/-/g, ' ');
+}
+
+/**
+ * Plan the carry for one roadmap. Pure apart from reading which slugs exist, so
+ * the sweep can decide before it writes anything.
+ *
+ * @param openBlockerIds every OPEN blocker the parent carries, as `collect()`
+ *   counts them — the source of truth for "would it archive afterwards".
+ */
+export function planCarry(
+    root: string,
+    rel: string,
+    text: string,
+    openBlockerIds: readonly string[],
+    date: string,
+    ownerDecision: OwnerDecision = 'ask',
+): CarryOutcome {
+    const sourceSlug = rel.replace(/\.md$/, '');
+    const lines = text.split('\n');
+    const steps = _bareSteps(lines);
+    if (steps.length === 0) return { refused: 'no bare `[~]` step to carry' };
+
+    const named = new Set(steps.flatMap((s) => s.blockerIds));
+    const stranded = openBlockerIds.filter((id) => !named.has(id));
+    if (stranded.length > 0) {
+        return {
+            refused:
+                `open blocker(s) no deferred step names (${stranded.join(', ')}) — ` +
+                'carrying around them would not let this roadmap archive',
+        };
+    }
+    const moved = _blockerSpans(lines).filter((b) => b.open && named.has(b.id));
+    const ownerBlockers = moved.filter((b) => b.ownerDependent).map((b) => b.id);
+    const parked = ownerBlockers.length > 0 && ownerDecision === 'later';
+
+    const destSlug = nextCarrySlug(root, sourceSlug);
+    const annotation = `<!-- deferred-resolution: carried-to=${destSlug} -->`;
+
+    const out = [...lines];
+    for (const b of moved) {
+        for (let i = b.start; i < b.end; i++) {
+            const s = STATUS_LINE_RE.exec(out[i] as string);
+            if (s === null) continue;
+            out[i] =
+                `${s[1] as string}resolved — carried, still open, to \`${destSlug}\` ` +
+                `with the steps it blocks (was: ${(s[2] as string).trim()})`;
+            break;
+        }
+    }
+    for (const s of steps) out[s.line] = `${out[s.line] as string} ${annotation}`;
+
+    const toOpen = (block: readonly string[]): string =>
+        block.map((l, i) => (i === 0 ? l.replace(/\[~\]/, '[ ]') : l)).join('\n');
+    const phaseSteps = steps.filter((s) => !s.isAcceptance).map((s) => toOpen(s.block));
+    const acSteps = steps.filter((s) => s.isAcceptance).map((s) => toOpen(s.block));
+    const phaseName = `Deferred steps carried from ${sourceSlug}`;
+    const blockerText = moved.map((b) => lines.slice(b.start, b.end).join('\n').trimEnd());
+
+    const body = [
+        `# ${_title(text, sourceSlug)} — carried`,
+        '',
+        `> **Source:** carried by the archival sweep on ${date} from`,
+        `> [\`${sourceSlug}\`](${parked ? '../' : ''}archive/${sourceSlug}.md), which closed every other step.`,
+        '> Each step below was `[~]` there and is restated verbatim as open work, so',
+        '> archiving the parent buried nothing. Blockers the steps name moved with them.',
+        '',
+        '## Goal',
+        '',
+        `Every step ${sourceSlug} deferred is either done here or explicitly disposed`,
+        'of — a step that still cannot run is re-deferred with its reason, never',
+        'left to read as finished.',
+        '',
+        `## Phase 1 — ${phaseName}`,
+        '',
+        phaseSteps.length > 0
+            ? phaseSteps.join('\n')
+            : '- [ ] **1.1 Close the carried acceptance criteria below.** The parent deferred\n' +
+              '      only acceptance criteria; this step is done when each is checked or disposed of.\n' +
+              '      verify: every criterion under `## Acceptance Criteria` is `[x]` or `[-]`',
+        '',
+        ...(blockerText.length > 0 ? ['## Blockers', '', blockerText.join('\n\n'), ''] : []),
+        '## Risk Register',
+        `<!-- risk-review: v1 | reviewed: ${date} | reviewer: archive-sweep/auto-carry -->`,
+        '',
+        '| Rank | Item | Risk type | Description | Mitigation | Anchored under |',
+        '|------|------|-----------|-------------|------------|----------------|',
+        '| 1 | Carried steps stay blocked indefinitely | implementation | A step deferred ' +
+            'once for elapsed time or a decision can sit here as long as it sat in the parent | ' +
+            'It now counts as open work in the dashboard instead of as 100 %, and its blocker ' +
+            `is listed where the estate gates count it | Phase 1 — ${phaseName} |`,
+        '',
+        '## Acceptance Criteria',
+        '',
+        acSteps.length > 0
+            ? acSteps.join('\n')
+            : `- [ ] AC-1 — No step carried from \`${sourceSlug}\` is still \`[ ]\` without a recorded disposition.`,
+        '',
+    ].join('\n');
+    const complexity = body.split('\n').length > LIGHTWEIGHT_LINE_BUDGET ? 'structural' : 'lightweight';
+    // Parked: `status: later` plus the three-part `entry_condition:` mapping
+    // `lint_roadmap_later_disposition` requires, and the growth claim the
+    // `later_roadmaps` count needs — a new file in `later/` is not a parking
+    // move, so no allowance covers it otherwise.
+    const ids = ownerBlockers.join(', ');
+    const parkedKeys = parked
+        ? 'entry_condition:\n' +
+          `  what: the owner resolves blocker(s) ${ids}\n` +
+          '  when: whenever the owner takes the next step\n' +
+          '  who: owner\n' +
+          // `lint_roadmap_later_disposition` rule C: a park with no review date
+          // reads exactly like an abandonment.
+          `review_by: ${_plusDays(date, 90)}\n` +
+          `estate_growth_exempt: >-\n  Owner-chosen archive of ${sourceSlug}: its deferred steps wait on owner\n` +
+          `  blocker(s) ${ids} and are parked here instead of left active. The parent\n` +
+          '  is archived in the same change, so the active count drops by one.\n'
+        : '';
+    const destText =
+        `---\ncomplexity: ${complexity}\nstatus: ${parked ? 'later' : 'ready'}\nexecution:\n  mode: phase-checkpoints\n` +
+        `parent_roadmap: ${sourceSlug}\n${parkedKeys}---\n${body}`;
+    const destRel = parked ? `agents/roadmaps/later/${destSlug}.md` : `agents/roadmaps/${destSlug}.md`;
+
+    return {
+        plan: {
+            destSlug,
+            destRel,
+            destText,
+            sourceText: out.join('\n'),
+            carried: steps.length,
+            movedBlockers: moved.map((b) => b.id),
+            ownerBlockers,
+            firstStep: (steps[0] as BareStep).block.join('\n'),
+            parked,
+        },
+    };
+}

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

@@ -1351,7 +1351,10 @@ function main(argv?: readonly string[]): number {
     // leaves behind rather than the one it found. `--check` never archives: a
     // gate that mutates the tree it is checking cannot be trusted by CI.
     let sweep_out = '';
-    if (!args.check && args.archive && unarchived_complete(collect(roadmap_root)).length > 0) {
+    // `pending_iron_law_3` too: a 100 % roadmap with bare `[~]` steps is what the
+    // sweep's carry exists for, and gating on `deferred === 0` never spawned it.
+    const before = collect(roadmap_root);
+    if (!args.check && args.archive && unarchived_complete(before).length + pending_iron_law_3(before).length > 0) {
         const swept = run_archival_sweep(repo_root);
         sweep_out = swept.stdout;
         if (swept.stderr) {

package/dist/agent-src/skills/api-design/data/manifest.json

@@ -28,7 +28,7 @@
   "refresh_cadence": "quarterly",
   "upstream": {
     "repo": "derived: RFC 9110/9457/7396/8288 + httpapi WG drafts",
-    "sha": "RFC 9110 (STD 97) / 9457 / 7396 / 8288 \u2014 verified 2026-09-18: 9110 neither obsoleted nor updated; 9457 current and obsoletes 7807",
-    "last_checked": "2026-09-18"
+    "sha": "RFC 9110 (STD 97, 2022-06) / 9457 (2023-07, obsoletes 7807) / 7396 (2014-10) / 8288 (2017-10) \u2014 all Standards Track",
+    "last_checked": "2026-10-04"
   }
 }

package/dist/agent-src/skills/api-testing/SKILL.md

@@ -234,3 +234,20 @@ When a test fails, do not retry blindly with tweaked assertions until something
 ## Clarification guard — ambiguous contract → ask
 
 If the endpoint contract is ambiguous (unclear status code, optional fields, error envelope shape), do not assume. Ask the user or check the OpenAPI spec / route definition before writing assertions — never guess the response shape from the route name.
+
+## The HTTP-assertion idiom, per ecosystem
+
+The examples above are Laravel's. The *shape* they teach — assert the status,
+then the body contract, then the side effect, and keep one behavior per test —
+transfers unchanged; the API does not. Resolve the runner with
+`resolve_toolchain` and read its `ecosystems`:
+
+| `ecosystems` | Request + assertion surface |
+|---|---|
+| `php` | `$this->getJson(...)` / `assertStatus` / `assertJsonPath` |
+| `js` | `supertest` or the framework's own test client, with `expect(res.status)` |
+| `python` | `httpx.AsyncClient` / framework `TestClient`; `assert res.status_code` |
+| `go` | `httptest.NewServer` + `net/http`, or the router's own `ServeHTTP` |
+
+Whatever the surface, the negative tests are not optional: unauthenticated,
+not-owner and cross-tenant each get their own case, per `broken-access-control`.

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

@@ -245,14 +245,26 @@ paragraph claiming "the same five answers" directly after a list of four:
 | `graph_dead` | `dead` |
 | `graph_query` | `query` |
 | `graph_path` | `path` |
+| `graph_node` | no CLI verb — one symbol's location, in-edges, out-edges and degree |
 
 `untested` has no tool of its own; it is a flag on `graph_impact`, because the
-two answer the same question over the same diff and a sixth tool would have cost
-standing context for a boolean. `graph_impact` is the only one that is not
+two answer the same question over the same diff and a separate tool would have
+cost standing context for a boolean. `graph_impact` is the only one that is not
 read-only — it runs `git diff --name-only` to resolve its rev — and
 `graph_dead`'s refusal arrives as `status: "refused"`, never as `status: "ok"`
 with an empty list.
 
+`graph_node` is the one entry with no CLI verb behind it, and the one that
+REFUSES a seed it cannot resolve exactly. Every other reader answers about a
+neighbourhood or a set, where a best-guess seed costs the caller one wrong line
+among several; a node view's every field — the location, the degree, both edge
+lists — is a statement about ONE node, so a guess is wrong in all of them at
+once. It resolves on the exact tiers of the same seed ladder (node id, then
+label) and returns `status: "refused"` naming the candidates when a label is
+ambiguous, rather than scoring free text — which is the retrieval class the
+measured null covers (`docs/CLAIMS.md`, `code-graph-retrieval-null`). Use
+`graph_query` when a best-guess match is what you want.
+
 **No ordering claim is added here, and no measurement claim either.** These
 verbs are cheaper than reconstructing the same relationship by hand — that is a
 claim about the ALTERNATIVE being a manual reconstruction, not about grep.

package/dist/agent-src/skills/design-system-capture/references/import-procedure.md

@@ -38,7 +38,7 @@ what this skill owns.
    imported observation.
 5. On the human's accept, persist the chosen fields into `DESIGN.md`. Where the
    consumer wants a token source of truth, hand the mapped DTCG fields to
-   [`brand-to-tokens`](../../brand-to-tokens/SKILL.md) / `design-tokens` to
+   `brand-to-tokens` / `design-tokens` to
    materialise `.tokens.json` — do not invent a parallel token format.
 
 **Two sources, one shape:**

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -228,7 +228,7 @@ this component satisfy the artifact"* — which is a different question with a
 different answer, because a candidate can be an excellent name-and-props match
 and still use the wrong type scale, the wrong control, or a colour the artifact
 never states. Until this step existed nothing anywhere asked the second
-question, while [`ui-audit-gate`](../../rules/ui-audit-gate.md) carried *"reuse
+question, while `ui-audit-gate` carried *"reuse
 beats duplication"* as unqualified prose. Reused on an artifact port, an
 unconforming candidate is a fidelity deviation dressed as good hygiene.
 
@@ -364,7 +364,7 @@ Load on demand once the audit needs the pitfall catalog:
 **Design-system export (current-repo source):** when the goal is to seed
 `DESIGN.md` from *this* repo, emit the inventory as a `design-system.json`
 artifact (the import contract in
-[`design-system-capture`](../design-system-capture/references/design-system-json.md))
+`design-system-capture`)
 and hand it to `design-system-capture` — the same shape an external extraction
 tool produces, so the import path is uniform.
 

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

@@ -29,7 +29,7 @@ machinery that already exists: `search_stack` in
 [`corpus-grounding`](../corpus-grounding/SKILL.md)
 (`scripts/decision_engine.ts`), whose stack corpus carries `threejs.csv` among
 its stacks, read beside the register in
-[`design-intelligence`](../design-intelligence/references/context-and-registers.md)
+`design-intelligence`
 § Register. No second frontend executor is declared, and none is needed: a
 renderer changes what you ground against, never who writes the UI.
 

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

@@ -42,7 +42,7 @@ execution:
    is the anti-pattern [`icon-consistency`](../../rules/icon-consistency.md)
    § What this gates names by name. Stop at the first rung that answers.
    1. **A brand token or brand guide that names an icon set** — authoritative,
-      stop here ([`brand-source-of-truth`](../../rules/brand-source-of-truth.md)).
+      stop here (`brand-source-of-truth`).
    2. **The set already in use in this project** — detected at the Inspect step
       of the Iconography floor below. One icon system per project; a second
       visual language is the defect, not a preference.

package/dist/agent-src/skills/js-library-packaging/SKILL.md

@@ -17,7 +17,7 @@ packs:
 > A React or TypeScript consumer receives this skill through `engineering-base`, which both
 > of those packs require.
 
-The JavaScript twin of [`composer-packages`](../composer-packages/SKILL.md). A component is
+The JavaScript twin of `composer-packages`. A component is
 a file; a **library** is a package with a public surface, and that surface is declared in
 `package.json` rather than inferred. Most of the failures below are silent at author time
 and loud at the consumer's — which is why the surface is read, not assumed.
@@ -167,7 +167,7 @@ declared cost — never here.
 
 ## See also
 
-- [`composer-packages`](../composer-packages/SKILL.md) — the PHP twin; same surface discipline, different manifest.
+- `composer-packages` — the PHP twin; same surface discipline, different manifest.
 - [`standards-from-config`](../standards-from-config/SKILL.md) — the Class-A rule the § Release branch follows.
 - [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md) — the `!` marker a release tool reads.
 - [`ui-component-architect`](../ui-component-architect/SKILL.md) — the component inside the library; this skill is the package around it.

package/dist/agent-src/skills/monorepo-workspace/SKILL.md

@@ -104,7 +104,7 @@ for `workspace:`-linked packages.
 
 State plainly that the listing came from manifests rather than the runner — an
 inferred target list can miss runner-inferred targets. This is the posture
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) already takes for the shadcn
+`react-shadcn-ui` already takes for the shadcn
 CLI; the stop condition is `missing-tool-handling` (never install it silently,
 never fake the output).
 

package/dist/agent-src/skills/quality-tools/SKILL.md

@@ -27,6 +27,8 @@ Use this skill whenever running or configuring code quality tools:
 
 - **PHP**: PHPStan (static analysis), Rector (automated refactoring), ECS (coding standards)
 - **JS/TS**: Biome (linting + formatting), TypeScript compiler (type checking), Jest/Vitest (tests)
+- **Python**: Ruff (linting + formatting), mypy (type checking), pytest (tests)
+- **Go**: `gofmt`, `go vet`, optionally golangci-lint, `go test`
 
 ## Modes
 
@@ -39,8 +41,16 @@ stack calls for.
 |---|---|---|
 | PHP (`.php` changed) | [`references/php-tools.md`](references/php-tools.md) | Tool detection, PHPStan / ECS / Rector commands and flags, combined pipeline, config files, baseline policy, PHPStan error handling, testing framework, git-aware execution |
 | JS/TS (`.js` / `.ts` / `.tsx` changed) | [`references/js-ts-tools.md`](references/js-ts-tools.md) | Detection, Biome, TypeScript type checking, Jest / Vitest, the JS/TS workflow sequence |
+| Python (`.py` changed, or `pyproject.toml`) | [`references/python-tools.md`](references/python-tools.md) | Detection from `pyproject.toml`, Ruff, mypy, pytest, the workflow sequence, virtualenv and `setup.cfg` gotchas |
+| Go (`.go` changed, or `go.mod`) | [`references/go-tools.md`](references/go-tools.md) | `gofmt`, `go vet`, golangci-lint where present, `go test`, the workflow sequence, vendor and build-tag gotchas |
 
-Both stacks changed → load both mode bodies and run both pipelines.
+More than one stack changed → load each mode body and run each pipeline.
+
+**The resolver decides which row applies, not the file extension alone.**
+`resolve_toolchain` returns the ecosystems it found and the quality commands
+per ecosystem; the rows above name what those commands are. A TypeScript
+repository resolves the ecosystem `js`, never `typescript` — the pack name and
+the ecosystem label are different vocabularies.
 
 ## Execution policy — on demand only, never proactive
 

package/dist/agent-src/skills/quality-tools/references/go-tools.md

@@ -0,0 +1,76 @@
+# quality-tools — Go quality tools
+
+> Mode body of the [`quality-tools`](../SKILL.md) skill. Load this file when
+> the mode table in SKILL.md routes here. The cross-mode material — execution
+> policy, environment, output discipline — stays in SKILL.md and is NOT
+> repeated here.
+
+# Go Quality Tools
+
+## Detection
+
+`resolve_toolchain` (`work_engine/stack/runner.ts`) keys the Go ecosystem on
+`go.mod` and resolves exactly one quality command, `go vet ./...`, plus the
+test command `go test ./...`. It does **not** detect `golangci-lint`, so a
+repository that uses one will show a `quality` list shorter than what its CI
+runs. Read the repository's CI workflow before concluding the resolver's list
+is the whole gate.
+
+| Signal | Tool | What it does |
+|---|---|---|
+| `go.mod` present | **`go vet`** | The toolchain's own correctness checks — printf verbs, struct tags, unreachable code, lost cancel |
+| `go.mod` present | **`gofmt`** | Canonical formatting; not resolved as a command because it is not optional in Go |
+| `.golangci.yml` / `.golangci.yaml` | **golangci-lint** | Meta-linter; the resolver does not detect it |
+
+## The toolchain's own commands
+
+```bash
+gofmt -l .                # list files whose formatting differs — empty is the pass
+gofmt -w .                # rewrite them
+go vet ./...              # the resolver's quality command
+go build ./...            # compiles; the cheapest proof the tree is coherent
+go test ./...             # the resolver's test command
+go test -run '<regexp>' ./pkg/...   # the targeted probe
+go test -race ./...       # the race detector — slow, and the only thing that finds a data race
+```
+
+**`gofmt -l .` with empty output is the pass.** It exits 0 whether or not it
+listed files, so a pipeline that checks only the exit code never fails on
+formatting. Check the output, not the status.
+
+## golangci-lint, where a project has it
+
+```bash
+golangci-lint run         # the whole configured set
+golangci-lint run ./pkg/...   # scoped to a package
+```
+
+It wraps `go vet` among others, so a project with `.golangci.yml` does not
+need `go vet` run separately — and running both doubles the report rather than
+widening it.
+
+## Workflow sequence
+
+1. `gofmt -l .` — read the output, not the exit code.
+2. `go build ./...` — a compile error makes every later step meaningless.
+3. `go vet ./...`, or `golangci-lint run` where the project has it.
+4. `go test -run '<the thing you changed>' ./pkg/...` — targeted.
+5. `go test ./...`, once, at the end; `-race` where concurrency changed.
+
+## Gotchas
+
+- **`./...` from the wrong directory.** The pattern is relative to the working
+  directory, not to the module root. Run it from the directory holding
+  `go.mod`, or name the module path.
+- **A vendored tree.** With `vendor/` present the toolchain defaults to
+  `-mod=vendor`; a dependency added to `go.mod` but not vendored fails to build
+  with an error that names the package, not the mode. `go mod vendor` after any
+  dependency change.
+- **Build tags hide packages.** `go vet ./...` and `go test ./...` skip files
+  excluded by build constraints, so a green run says nothing about a
+  `//go:build integration` file. Name the tag (`-tags integration`) to reach it.
+- **No `go` pack exists in this suite yet.** Go artifacts route through
+  `engineering-base` and this reference; `src/packs/go/pack.yaml` <!-- ref-ignore --> is created by
+  `road-to-stacks-beyond-php` step 2.3, which is blocked on the programme's
+  skill-growth question. Until then this file is the whole of the Go quality
+  surface, by design rather than by omission.