archgen-skill 0.0.1

package/vendor/skills/archgen/references/artifact-templates.md

@@ -0,0 +1,105 @@
+# Artifact templates — copy, fill, never invent structure
+
+## architecture.yaml (LARGE scope)
+
+```yaml
+name: Acme Shop
+slug: acme-shop            # becomes .archgen/acme-shop/
+stack:
+  language: typescript
+  runtime: node20
+  framework: nextjs
+  database: postgres
+structure:                 # planned folder tree — planned BEFORE code exists
+  - path: src/features/<feature>/
+    purpose: feature modules (api, internal, tests colocated)
+  - path: src/shared/
+    purpose: cross-feature utilities, no feature imports
+  - path: src/config/
+    purpose: env parsing + constants
+modules:
+  - name: catalog
+    responsibility: product browsing + search
+    owns: ["src/features/catalog/**"]
+  - name: checkout
+    responsibility: cart → payment orchestration
+    owns: ["src/features/checkout/**"]
+decisions:                 # ADR-lite; full ADRs live in decisions/
+  - id: D1
+    title: Postgres over MongoDB
+    context: transactional orders + reporting queries
+    decision: Postgres 16 with Prisma
+    consequences: schema migrations required per release
+```
+
+## tasks.yaml (canonical shape)
+
+```yaml
+# comment lines are preserved by set-status.mjs — annotate freely
+tasks:
+  # Core pipeline — do first
+  - id: C
+    title: Scaffold project skeleton + config loading
+    depends_on: []
+    file_ownership: ["src/config/**", "package.json"]
+    acceptance:
+      - "npm run build exits 0"
+      - "config loads from env with typed schema"
+  - id: B
+    title: Catalog API endpoints
+    depends_on: [C]
+    file_ownership: ["src/features/catalog/**"]
+    acceptance:
+      - "GET /products returns seeded list"
+  - id: A
+    title: Checkout flow wired to catalog
+    depends_on: [B]
+    parallel_group: wave-final
+    file_ownership: ["src/features/checkout/**"]
+    artifacts: ["docs/checkout-flow.md"]
+    acceptance:
+      - "e2e test completes purchase with stub payment"
+```
+
+Rules encoded above: depends_on = prerequisites; ownership globs disjoint
+within a wave; acceptance = objectively checkable statements.
+
+## SMALL-scope plan note (plans/<feature>.md)
+
+```markdown
+# <feature> — plan note (SMALL)
+Intent: <one paragraph>
+Tasks: see tasks.yaml entries <ids>
+Risks: <bullets or none>
+```
+
+## ADR template (decisions/NNNN-title.md)
+
+```markdown
+# NNNN. <decision title>
+Date: YYYY-MM-DD · Status: accepted
+## Context
+<forces at play>
+## Decision
+<what we chose>
+## Consequences
+<positive / negative / neutral>
+```
+
+## Mermaid snippets
+
+C4 context:
+```mermaid
+graph TB
+  user([Customer]) --> sys[Acme Shop]
+  sys --> pay[Stripe]
+  sys --> mail[Email Service]
+```
+
+Container:
+```mermaid
+graph LR
+  web[Next.js App] --> api[API Routes]
+  api --> db[(Postgres)]
+  api --> cache[(Redis)]
+```

package/vendor/skills/archgen/references/code-standards.md

@@ -0,0 +1,70 @@
+# Code standards — contractual, verifier-enforced
+
+Workers and planners follow these. The verifier rejects tasks whose plan or
+output violates them. Every rule exists because its absence produced real
+production incidents somewhere.
+
+## Typing (TypeScript projects)
+
+- NO ANY: `any` is BANNED — including implicit anys and `as any` casts. Enable `"strict": true` plus
+  `noImplicitAny`, `strictNullChecks`, `noUncheckedIndexedAccess`.
+- No unhandled `undefined`/null: validate at boundaries (env parsing, API
+  input) with a schema; inside the codebase use non-optional types + explicit
+  result objects for fallible operations.
+- Prefer discriminated unions over boolean-flag parameters.
+- Generated Python/Rust/Go equivalents: type hints mandatory / no `unwrap()` on
+  fallibles / handle errors explicitly — same discipline per language.
+
+## File & module limits
+
+- HARD CEILING: files < 1000 LOC. Split well before — when a file gains a
+  second responsibility, that IS the split signal.
+- One public purpose per module. If the docstring needs "and", split.
+
+## Folder structure (planned in architecture.yaml BEFORE coding)
+
+```
+src/
+  features/<name>/        # feature-first: everything a feature owns
+    api/                  #   inbound contracts (routes/handlers)
+    internal/             #   private implementation
+    tests/                #   colocated tests mirror structure
+  shared/                 # cross-feature ONLY; may not import features/
+  config/                 # typed env + constants
+```
+
+- Feature modules may import `shared/`; `shared/` imports NOTHING from features.
+- Tests live beside code (mirrored path), never a distant `/tests` desert.
+
+## File naming
+
+Per-language conventions (professional, descriptive, consistent):
+
+| Language | Source files | Components/classes | Tests |
+|---|---|---|---|
+| TypeScript | `kebab-case.ts` | `PascalCase.tsx` components, `PascalCase` classes | `<subject>.test.ts` colocated |
+| Python | `snake_case.py` modules | `PascalCase` classes, `snake_case` functions | `test_<subject>.py` mirrored |
+| Rust | `snake_case.rs` modules | `PascalCase` types/traits | `#[cfg(test)] mod tests` inline or `tests/` |
+| Go | `snake_case.go` packages | `PascalCase` exported / `camelCase` internal | `<subject>_test.go` same dir |
+
+- Descriptive > clever: `rate-limiter.ts` not `rl.ts`; `parse-config.ts` not
+  `utils2.ts`.
+- BANNED names: `utils.ts`, `misc.ts`, `helpers.ts`, `temp*`, `final*`,
+  `copy*`, numbered duplicates (`auth2.ts`) — split by responsibility instead.
+
+## Comments
+
+- WHY at decision points: tradeoffs taken, non-obvious constraints, links to
+  decisions ("see ADR D3"). 
+- Public APIs get doc comments: purpose, params, failure modes.
+- NO noise: no `// increment i`, no commented-out code, no change-log comments
+  (git remembers).
+
+## Enforcement hooks
+
+- tasks.yaml acceptance criteria MUST include at least one objectively
+  checkable statement (command exit, observable output).
+- The verifier runs verify-plan.mjs AND reads plans against this file;
+  violations = ISSUES, not warnings.
+- Workers receive this reference in their prompt contract; "I didn't know" is
+  not available to them.

package/vendor/skills/archgen/references/interview.md

@@ -0,0 +1,66 @@
+# Interview playbook — requirement elicitation
+
+Goal: complete, conflict-free requirements in the FEWEST round-trips.
+Batch 3–5 questions per message. Never ask what you can infer.
+
+## Round 1 — business frame (ask the user)
+
+1. What problem does this solve, and for whom? (one sentence is enough)
+2. What does success look like — measurable if possible?
+3. Hard constraints: deadline, budget, must-keep systems?
+
+## Round 2 — technical frame (infer first, confirm second)
+
+Draft answers from context (existing repo, stated stack), then confirm:
+4. Stack + hosting target correct? (state your inference)
+5. Scale expectation: users/reqs/day, data growth?
+6. Integration surfaces: auth, payments, email, existing APIs?
+
+## Round 3 — constraints & risks
+
+7. Compliance needs? (GDPR/HIPAA/PCI — checklist level only)
+8. What must NOT change?
+9. Top 2 risks the user already knows about?
+
+## Conflict detection
+
+While collecting, watch for and surface immediately:
+- Scale vs budget contradictions ("1M users" + "cheapest VPS")
+- Feature vs constraint collisions ("real-time" + "no websockets allowed")
+- Requirement vs existing-architecture conflicts (brownfield: check codebase-map)
+
+Format: "I see a tension between X and Y. Which wins?" — one per message,
+resolve before proceeding. [wait for user]
+
+## Answers-file format (machine-readable, enables non-interactive runs)
+
+For scripted E2E or re-runs, requirements may come from a file instead of
+conversation — `.archgen/<slug>/answers.yaml`:
+
+```yaml
+scope_class: MEDIUM        # SMALL | MEDIUM | LARGE
+problem: one-line problem statement
+success_criteria:
+  - measurable outcome
+constraints:
+  - must-not-change items
+stack:
+  language: typescript
+  runtime: node
+  hosting: vercel
+integrations: [auth0, stripe]
+compliance: []             # checklist placeholders only
+risks:
+  - known risk text
+```
+
+The orchestrator treats answers.yaml as authoritative user input and skips
+the conversational rounds when it exists and parses cleanly.
+
+## Completion test
+
+Requirements are done when ALL hold:
+- Every ROUND-1 question answered
+- All drafted inferences confirmed or corrected
+- Zero unresolved conflicts
+- Scope class agreed (SMALL/MEDIUM/LARGE) — this gates artifact generation

package/vendor/skills/archgen/references/mcp-and-skills.md

@@ -0,0 +1,46 @@
+# MCP installation and skill fetching
+
+## INSTALL-MCP procedure (approval-gated)
+
+1. **Identify** the platform (SKILL.md Step 0), load its row from
+   references/platforms.md section MCP: config file, top-level key, quirks.
+2. **Prefer the platform CLI** where the table lists one. It handles scope and
+   file selection correctly:
+   - `claude mcp add --scope project --transport http <name> <url>`
+   - `codex mcp add <name> --url <url>` or `codex mcp add <n> -- cmd args`
+   - `gemini mcp add -s project -t http <name> <url>`
+3. No CLI available: draft the exact config diff against the platform's real
+   shape (see assets/mcp-template.json for annotated canonical forms) and SHOW
+   it to the user. **USER APPROVAL GATE** — wait for an explicit yes before any
+   write; approval is never inferred from earlier steps.
+4. Apply, then apply the restart semantics from the platforms table.
+5. Verify the tool is visible after reload; report failure modes honestly.
+
+Never write MCP configs silently. Never invent config shapes — the four known
+top-level keys are mcpServers / servers / mcp / context_servers; remote URL
+fields vary (url vs serverUrl vs httpUrl) per the platforms table.
+
+## FETCH-SKILL procedure
+
+1. Read assets/skill-registry.json. Match the current task domain against
+   entry `matches` patterns (e.g. frontend/UI work matches ui-skills).
+2. Install into the CURRENT platform's skill dir (platforms.md paths):
+   - Generic: `npx skills add <owner>/<repo>` (writes correct path for 75+
+     harnesses; `-g` for global).
+   - Entry-specific command when present (e.g. `npx ui-skills get baseline-ui`).
+3. Confirm files landed where expected; then FOLLOW the fetched skill's own
+   instructions for the task domain.
+4. Missing capability: web-search reputable skill repos, propose to user,
+   on approval append an entry to the registry (PR or local edit).
+
+## Registry entry shape
+
+```json
+{
+  "name": "short-name",
+  "purpose": "when to reach for it",
+  "repo": "owner/repo",
+  "install": "npx skills add owner/repo",
+  "matches": ["frontend", "ui", "design"]
+}
+```

package/vendor/skills/archgen/references/orchestration.md

@@ -0,0 +1,106 @@
+# Orchestration playbook — survey, verify, dispatch
+
+Sub-agent briefs and the wave-execution mechanics. The orchestrator (SKILL.md)
+calls into these sections; workers never read this file.
+
+## §survey — brownfield codebase analysis brief
+
+Dispatch 1–2 sub-agents with this prompt shape:
+
+```
+TASK: Survey this repository to prepare a feature plan for: <feature request>
+DELIVERABLE: write .archgen/<slug>/codebase-map.md containing EXACTLY these
+sections:
+  ## Structure      — top-2-levels folder tree w/ one-line purpose each
+  ## Modules        — table: module | responsibility | key entry points
+  ## Conventions    — naming, error-handling, test layout actually observed
+  ## Affected       — files/modules the feature will touch, with evidence paths
+SCOPE: read-only. Use codegraph MCP tools when available
+(codegraph_explore / codegraph_files); otherwise Glob+Grep systematically.
+VERIFY: every claim cites a real path; no guessed APIs.
+```
+
+Accept the map only if every section is present and non-empty.
+
+## §verifier — plan review brief
+
+Dispatch AFTER artifacts exist and validate.mjs passes. The verifier:
+
+1. Runs `node <skill>/scripts/verify-plan.mjs .archgen/<slug>/tasks.yaml --plan .archgen/<slug>/plans`
+   — deterministic floor: cycles, dangling refs, same-wave ownership overlap,
+   missing acceptance criteria, plan↔task coverage.
+2. Reads plans + tasks.yaml and judges what scripts cannot:
+   - Are wave boundaries sensible (no artificial serialization)?
+   - Do acceptance criteria objectively verify (command or observable)?
+   - Edge cases covered per SKILL.md right-sizing class?
+   - Code-standards compliance plausible for the planned structure?
+3. Returns EXACTLY one line verdict: `APPROVE` or `ISSUES:` + numbered list.
+
+Orchestrator fixes issues (edits artifacts) and re-dispatches. Loop until
+APPROVE — never present to the user before verifier approval.
+
+## §dispatch — wave execution
+
+### Tier 1: native sub-agents (preferred where strong)
+
+- Claude Code: background Agent tool per task; add worktree isolation for
+  tasks whose ownership might brush shared files.
+- Cursor: background subagents; request isolation when >2 parallel workers.
+- Antigravity: invoke_subagent async.
+- Codex: spawn_agent works but children can't nest — flatten the plan instead.
+- Gemini CLI: parallel @agents are hub-and-spoke only AND have no isolation →
+  use them ONLY for read-only/research waves unless wrapping in worktrees.
+
+### Tier 2: bash fallback workers (universal floor)
+
+```bash
+#!/usr/bin/env bash
+set -uo pipefail
+SLUG="<slug>"; ROOT="$(pwd)"; SKILL="<abs-path-to-skills/archgen>"
+run_task() { # $1=id  $2=prompt-file
+  local id="$1" pf="$2" log=".archgen/$SLUG/results/$id.log"
+  mkdir -p "$(dirname "$log")"
+  local body; body="$(cat "$pf")
+
+You own exactly the file_ownership globs listed for this task in tasks.yaml. Follow archgen code-standards. On success run: node \"$SKILL/scripts/set-status.mjs\" .archgen/$SLUG/tasks.yaml \"$id\" done ; on failure set-status failed."
+  case "$ARCHGEN_HARNESS" in
+    claude)    claude -p "$body" --output-format json --permission-mode acceptEdits > "$log" 2>&1 ;;
+    opencode)  opencode run "$body" --auto --format json > "$log" 2>&1 ;;
+    codex)     codex exec --sandbox workspace-write --json -o "$log.final" "$body" > "$log" 2>&1 ;;
+    gemini)    gemini --output-format json "$body" > "$log" 2>&1 ;;
+    agy)       agy -p --output-format json --print-timeout 15m "$body" > "$log" 2>&1 ;;
+    *) echo "unknown harness: $ARCHGEN_HARNESS" >&2; return 9 ;;
+  esac
+
+You own exactly: $(node "$SKILL/scripts/impact.mjs" .archgen/$SLUG/tasks.yaml "$id" >/dev/null 2>&1 && echo 'see tasks.yaml file_ownership'). Follow archgen code-standards. On success run: node "$SKILL/scripts/set-status.mjs" .archgen/$SLUG/tasks.yaml "$id" done ; on failure set-status failed." \
+}
+# Wave N: launch all frontier tasks in parallel…
+for t in $(node "$SKILL/scripts/next-tasks.mjs" .archgen/$SLUG/tasks.yaml \
+           | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).waves[0].map(t=>t.id).join(" ")))'); do
+  run_task "$t" ".archgen/$SLUG/results/$t.prompt" & pids="$pids $!"
+done
+fail=0; for p in $pids; do wait "$p" || fail=1; done
+exit $fail   # orchestrator inspects statuses before next wave
+```
+
+Isolation upgrade for Tier 2 when ownership borders are tight:
+
+```bash
+git worktree add ".worktrees/$id" -b "task-$id"
+# run worker with cwd=.worktrees/$id, then merge task-$id on success
+```
+
+### Worker prompt contract (both tiers)
+
+Every worker receives: task id+title, its acceptance criteria verbatim, its
+file_ownership globs ("edit NOTHING outside these"), the code-standards
+reference, and the done/failed status-update command. Workers do NOT talk to
+each other; coordination happens only through tasks.yaml state.
+
+## Failure policy
+
+- Worker exit ≠ 0 OR status=failed → leave it failed. NEVER auto-retry.
+- Downstream tasks stay blocked by the resolver (blockedByFailure).
+- Report to user: failed id, log path, proposed fix-task description.
+  [wait for user] A fix task gets fresh id, depends_on=[], ownership of the
+  failed task's globs.

package/vendor/skills/archgen/references/platforms.md

@@ -0,0 +1,79 @@
+# Platform capability matrix (August 2026)
+
+Facts verified against official vendor docs; cells marked UNVERIFIED could not be
+confirmed. The orchestrator loads ONLY the row matching Step-0 detection.
+
+## Skill install paths
+
+| Platform | Project path | Global path | Notes |
+|---|---|---|---|
+| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` | Plugin marketplace: `/plugin install x@mkt`; skills hot-reload |
+| OpenCode | `.opencode/skills/` (+ reads `.claude/`, `.agents/`) | `~/.config/opencode/skills/` (+ `~/.claude/`, `~/.agents/`) | Walks up to git root |
+| Cursor | `.agents/skills/`, `.cursor/skills/` | `~/.agents/skills/`, `~/.cursor/skills/` | ≥2.4 native; also scans `.claude/`, `.codex/`; nesting OK |
+| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | Enterprise system paths also read |
+| VS Code + Copilot | `.github/skills/` (+ `.claude/`, `.agents/`) | `~/.copilot/skills/` (+ `~/.claude/`, `~/.agents/`) | Extra dirs via chat.agentSkillsLocations |
+| Codex CLI | `.agents/skills/` (crawls up to repo root) | `~/.agents/skills/` (legacy `~/.codex/skills/`) | `$skill-installer` built in |
+| Gemini CLI | `.gemini/skills/` or `.agents/skills/` | `~/.gemini/skills/` or `~/.agents/skills/` | `gemini skills install <git-url> --consent` |
+| Antigravity | `<ws>/.agents/skills/` | `~/.gemini/config/skills/` | Backward-supports `.agent/skills`; name frontmatter OPTIONAL here |
+| Zed | `<project>/.agents/skills/` ONLY | `~/.agents/skills/` ONLY | FLAT layout — no nesting; worktree-trust gate on project skills |
+| Kiro | `.kiro/skills/` | `~/.kiro/skills/` | Custom agents need explicit `resources: ["skill://.kiro/skills/**/SKILL.md"]` |
+| Trae | `.trae/skills/` (opt-in `.agents/`) | `~/.trae/skills/` | `.trae` wins collisions; CN variant separate |
+| Claude Desktop | — (account-scoped) | GUI ZIP upload only | Scripts run sandboxed, NOT local shell |
+
+Universal fallback: `.agents/skills/` project + `~/.agents/skills/` user works
+across most harnesses. Primary distribution: `npx skills add <repo>` (75+ agents).
+
+## MCP configuration
+
+Four different top-level keys exist — NEVER assume `mcpServers`:
+
+| Platform | File(s) | Key | stdio fields | Remote URL field | CLI add? |
+|---|---|---|---|---|---|
+| Claude Code | `.mcp.json` (project) / `~/.claude.json` (local/user) | `mcpServers` | command,args[,env] type:"stdio" | `url`+headers type:"http"/"sse" | `claude mcp add --scope project\|local\|user --transport stdio\|http\|sse` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\` (Win) / `~/.config/Claude/` (Linux) | `mcpServers` | command,args,env | UI Connectors preferred; file `url` UNVERIFIED | none |
+| OpenCode | `opencode.json(c)` / `~/.config/opencode/opencode.json(c)` | **`mcp`** | type:"local", **command:[array]**, environment{} | type:"remote", `url`, headers | `opencode mcp add` (interactive only) |
+| Cursor | `.cursor/mcp.json` / `~/.cursor/mcp.json` | `mcpServers` | command,args,env,cwd | `url`+headers (`${env:VAR}` interp.) | none (deep-links UNVERIFIED) |
+| VS Code Copilot | `.vscode/mcp.json` / profile mcp.json / portable `.mcp.json` | **`servers`** (+inputs[]) | type:"stdio",command,args,env | type:"http"/"sse", url, headers | `copilot mcp add`; palette "MCP: Add Server" |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` (global only) | `mcpServers` | command,args,env | **`serverUrl`** OR `url` + headers | none (Marketplace UI/deeplink) |
+| Codex CLI | `~/.codex/config.toml` / project `.codex/config.toml` (trust-gated) | `[mcp_servers.<id>]` TOML | command,args,env,cwd | `url`, bearer_token_env_var, http_headers | `codex mcp add <n> --url \| -- cmd args` |
+| Gemini CLI | `~/.gemini/settings.json` / `.gemini/settings.json` | `mcpServers` | command,args,env,cwd,trust | `httpUrl`(HTTP)/`url`(SSE)+headers | `gemini mcp add -s user\|project -t stdio\|sse\|http` |
+| Antigravity | `~/.gemini/config/mcp_config.json` / `.agents/mcp_config.json` | `mcpServers` | command,args,env,cwd | **`serverUrl` MANDATORY — `url` rejected** + headers/oauth | none (`/mcp` overlay manager) |
+| Zed | `~/.config/zed/settings.json` / `.zed/settings.json` | **`context_servers`** | command,args,env | `url`+headers (OAuth auto-prompt) | none (Settings UI writes file) |
+| Kiro | `.kiro/settings/mcp.json` / `~/.kiro/settings/mcp.json` | `mcpServers` | command,args,env,disabled,autoApprove | `url`+headers+oauth | `/mcp add` (CLI session) |
+| Trae IDE | `.trae/mcp.json` | `mcpServers` | command,args,env | url + type:"sse"/"http" | none (UI manual add) |
+
+Restart semantics: full restart needed = Claude Desktop, Windsurf, Zed.
+Hot-reload = Kiro, Gemini, Codex. Approval prompt on first detection =
+Claude Code project-scope servers.
+
+## Sub-agent dispatch capability
+
+| Harness | Native mechanism | Parallel background | Isolation for parallel edits |
+|---|---|---|---|
+| Claude Code | `Agent` tool + subagent_type; `.claude/agents/*.md` | Yes (default since v2.1.198; cap ~20) | BEST: `isolation: worktree` frontmatter; `/batch` |
+| OpenCode | task/subagent tool + subagent_type | Yes (fg + background) | None in core → use file-ownership discipline or team-mode plugin worktrees |
+| Codex CLI | model-mediated `spawn_agent`; max_depth=1 | Yes but children can't nest | None → prefer top-level parallel `codex exec` + manual git worktrees |
+| Gemini CLI | subagents-as-tools; `@agent-name` | Yes BUT strictly hub-and-spoke (no nested calls) | None → restrict parallel workers to read-only roles unless given external worktrees |
+| Cursor | Subagents w/ `is_background` frontmatter; `/multitask` | Yes | Opt-in per-subagent worktree or cloud VM |
+| Antigravity | `invoke_subagent` (async by design); `/fork` | Yes | `/fork` workspace separation; per-subagent worktrees UNVERIFIED |
+
+## Headless invocation templates (fallback workers)
+
+```
+claude    claude -p "<prompt>" --output-format json --permission-mode acceptEdits
+opencode  opencode run "<prompt>" --auto --format json
+codex     codex exec --sandbox workspace-write --json -o <out-file> "<prompt>"
+gemini    gemini --output-format json "<prompt>"
+agy       agy -p --output-format json --print-timeout 15m "<prompt>"
+```
+
+Completion signal = process exit (Claude documents 0/non-zero contract).
+NEVER pass secrets as arguments. Feature-detect old binaries via `--version`.
+
+## Unknown platform procedure
+
+1. WEB SEARCH: `<platform> official docs MCP configuration` and
+   `<platform> agent skills install path`.
+2. Prefer official vendor domains over blog posts; note the date of sources.
+3. Present findings + proposed config diff to the user. [approval gate]
+4. Apply, verify, and offer to append findings to this table upstream.

package/vendor/skills/archgen/scripts/impact.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// impact.mjs — reverse-dependency query: what is affected if <target> changes?
+// Usage: node impact.mjs <tasks.yaml> <taskId-or-artifactPath>
+// stdout: JSON {direct:[taskIds], transitive:[taskIds], artifacts:[paths]}
+import { readFileSync } from 'node:fs';
+import { parseYaml } from './lib/yaml.mjs';
+
+const [, , file, target] = process.argv;
+if (!file || !target) { console.error('usage: impact.mjs <tasks.yaml> <taskId-or-artifactPath>'); process.exit(4); }
+
+const { data } = parseYaml(readFileSync(file, 'utf8'), { filename: file });
+const tasks = data?.tasks;
+if (!Array.isArray(tasks)) { console.error(`${file}: missing 'tasks:' sequence`); process.exit(4); }
+
+// Resolve target to a seed set of task ids.
+const byId = new Map(tasks.map((t) => [t.id, t]));
+let seeds;
+if (byId.has(target)) {
+  seeds = [target];
+} else {
+  // Artifact-path mode: any task whose artifacts[] or file_ownership[] covers it.
+  seeds = tasks
+    .filter((t) => (t.artifacts ?? []).includes(target) || (t.file_ownership ?? []).includes(target))
+    .map((t) => t.id);
+  if (seeds.length === 0) { console.error(`no task claims '${target}' (not an id, artifact, or ownership glob)`); process.exit(4); }
+}
+
+// Reverse edges: dependents[prereq] = tasks that depend on it.
+const dependents = new Map();
+for (const t of tasks) {
+  for (const dep of t.depends_on ?? []) {
+    if (!dependents.has(dep)) dependents.set(dep, new Set());
+    dependents.get(dep).add(t.id);
+  }
+}
+
+// Direct = immediate dependents of seeds; transitive = everything beyond.
+const direct = new Set();
+const transitive = new Set();
+for (const s of seeds) for (const d of dependents.get(s) ?? []) direct.add(d);
+transitive.clear();
+{
+  const seen = new Set([...seeds, ...direct]);
+  const f = [...direct];
+  while (f.length) {
+    const cur = f.pop();
+    for (const d of dependents.get(cur) ?? []) {
+      if (seen.has(d)) continue;
+      seen.add(d); transitive.add(d); f.push(d);
+    }
+  }
+}
+
+// Artifacts owned by affected tasks (what files the ripple touches).
+const artifacts = new Set();
+for (const id of [...direct, ...transitive]) {
+  for (const a of byId.get(id)?.artifacts ?? []) artifacts.add(a);
+}
+
+console.log(JSON.stringify({
+  direct: [...direct].sort(),
+  transitive: [...transitive].sort(),
+  artifacts: [...artifacts].sort(),
+}, null, 2));

package/vendor/skills/archgen/scripts/lib/graph.mjs

@@ -0,0 +1,128 @@
+// graph.mjs — shared dependency-graph utilities for archgen scripts.
+// WHY a lib: validate.mjs, next-tasks.mjs and verify-plan.mjs must agree on
+// cycle detection and wave semantics; three copies would drift (Metis finding).
+
+/** Build adjacency (prerequisite → dependents) + reverse maps from tasks.
+ * Normative semantics: depends_on lists PREREQUISITE ids; a task is ready iff
+ * every prerequisite is done; wave 1 = empty depends_on. */
+export function buildGraph(tasks) {
+  /** @type {Map<string, string[]>} prereq -> [dependent ids] */
+  const dependents = new Map();
+  /** @type {Map<string, string[]>} id -> prerequisite ids */
+  const prerequisites = new Map();
+  const byId = new Map();
+  for (const t of tasks) {
+    if (byId.has(t.id)) throw new GraphError(`duplicate task id: ${t.id}`);
+    byId.set(t.id, t);
+    prerequisites.set(t.id, Array.isArray(t.depends_on) ? t.depends_on : []);
+  }
+  for (const t of tasks) {
+    for (const dep of prerequisites.get(t.id)) {
+      if (!byId.has(dep)) throw new GraphError(`dangling depends_on reference: '${t.id}' depends on unknown task '${dep}'`);
+      if (!dependents.has(dep)) dependents.set(dep, []);
+      dependents.get(dep).push(t.id);
+    }
+  }
+  return { byId, prerequisites, dependents };
+}
+
+export class GraphError extends Error {}
+
+/** Return an array of ids forming a cycle (empty if acyclic). Iterative DFS. */
+export function findCycle(prerequisites) {
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map();
+  const parent = new Map();
+  for (const id of prerequisites.keys()) color.set(id, WHITE);
+
+  for (const start of prerequisites.keys()) {
+    if (color.get(start) !== WHITE) continue;
+    const stack = [[start, 0]];
+    color.set(start, GRAY);
+    while (stack.length) {
+      const [id, pi] = stack[stack.length - 1];
+      const deps = prerequisites.get(id);
+      if (pi < deps.length) {
+        stack[stack.length - 1] = [id, pi + 1];
+        const d = deps[pi];
+        if (!color.has(d)) continue; // dangling handled elsewhere
+        if (color.get(d) === GRAY) {
+          // Found a back-edge: reconstruct the cycle path d ← id ← … ← d
+          const cycle = [d];
+          let cur = id;
+          while (cur !== d) { cycle.push(cur); cur = parent.get(cur); }
+          cycle.push(d);
+          return cycle.reverse();
+        }
+        if (color.get(d) === WHITE) { color.set(d, GRAY); parent.set(d, id); stack.push([d, 0]); }
+      } else {
+        color.set(id, BLACK);
+        stack.pop();
+      }
+    }
+  }
+  return [];
+}
+
+/** Topological waves over NOT-DONE tasks.
+ * @param {Map<string,any>} byId
+ * @param {Map<string,string[]>} prerequisites
+ * @returns {{waves: Array<Array<any>>, blockedByFailure: string[]}}
+ * Wave membership: every prerequisite is done. Tasks whose TRANSITIVE
+ * prerequisites include any failed task are excluded entirely and reported in
+ * blockedByFailure (no silent cascades — orchestrator re-plans around them). */
+export function computeWaves(byId, prerequisites) {
+  const done = new Set();
+  const failed = new Set();
+  for (const [id, t] of byId) {
+    if (t.status === 'done') done.add(id);
+    if (t.status === 'failed') failed.add(id);
+  }
+  // Propagate failure transitively.
+  const blockedByFailure = new Set();
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [id, deps] of prerequisites) {
+      if (blockedByFailure.has(id) || failed.has(id)) continue;
+      if (deps.some((d) => failed.has(d) || blockedByFailure.has(d))) {
+        blockedByFailure.add(id); changed = true;
+      }
+    }
+  }
+
+  const remaining = [...byId.keys()].filter((id) =>
+    !done.has(id) && !failed.has(id) && !blockedByFailure.has(id));
+  const waves = [];
+  const satisfied = new Set(done);
+  let frontier = remaining.filter((id) => prerequisites.get(id).every((d) => satisfied.has(d)));
+  const queued = new Set();
+
+  while (frontier.length) {
+    frontier.sort(); // deterministic output for identical inputs
+    waves.push(frontier.map((id) => byId.get(id)));
+    for (const id of frontier) { satisfied.add(id); queued.add(id); }
+    const next = [];
+    for (const id of remaining) {
+      if (queued.has(id) || satisfied.has(id)) continue;
+      if (prerequisites.get(id).every((d) => satisfied.has(d))) next.push(id);
+    }
+    frontier = next;
+  }
+  return { waves, blockedByFailure: [...blockedByFailure].sort() };
+}
+
+/** First ownership conflict inside a single wave, or null.
+ * Ownership globs are treated as opaque strings for equality here — two tasks
+ * in the same wave must not claim the SAME literal glob (conservative rule that
+ * needs no glob-engine dependency). */
+export function findOwnershipConflict(wave) {
+  const seen = new Map();
+  for (const t of wave) {
+    for (const g of t.file_ownership ?? []) {
+      if (seen.has(g)) return { glob: g, a: seen.get(g), b: t.id };
+      seen.set(g, t.id);
+    }
+  }
+  return null;
+}