archgen-skill 0.0.4 → 0.0.5

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

@@ -96,6 +96,63 @@ shrinking LARGE hallucinates.
   per-task edge-case matrices + per-module diagrams + MEDIUM-grade plan
   sections. Every diagram ≤15 nodes.
 
+## Structural correctness — verifier-enforced authoring rules
+
+- **Waves derive from `depends_on`.** Declared wave / `parallel_group` labels
+  MUST match the dependency-derived topological order — never hand-label a
+  task into a wave that contradicts its `depends_on`. A dependent task may not
+  sit in an earlier (or parallel) wave than its prerequisite.
+  `plan-graph.mjs --mermaid` is the ground truth for wave order.
+- **artifacts ⊆ file_ownership.** Every path a task lists in `artifacts` must
+  fall inside that task's `file_ownership` globs — workers can write ONLY
+  owned paths. Listing a doc the task doesn't own is a verifier-blocking
+  defect.
+- **Verification commands**: repo-root-relative (no `../`, no `--plan .`),
+  fully specific — exact commands, versions, sample sizes, thresholds — the
+  same form a worker would actually run. Generic "run the tests" or
+  wrong-root-resolved paths fail.
+- **YAML subset**: emit only the parser's supported subset — block mappings
+  and block sequences only. Avoid flow mappings (`{...}`), block scalars
+  (`|` / `>`), duplicate keys, and comma-heavy inline values, which the
+  strict parser rejects (these caused format-repair loops).
+- **tasks.yaml edits**: make small targeted edits or one clean full
+  regeneration — never large multi-region patches (they corrupted tasks.yaml
+  in the field).
+
+## Agent workspace & artifact location — the two-tier rule
+
+Location follows LIFETIME + AUDIENCE: the plan (and its rationale) travels as
+ONE self-contained, reviewable, git-versioned unit; the product's deliverables
+travel with the product.
+
+INSIDE `.archgen/<slug>/` — the plan + everything needed to execute/review it:
+- tasks.yaml, plans/, architecture.yaml, answers.yaml, codebase-map.md.
+- `docs/prd.md` — a PLANNING artifact (defines the FR-ids tasks cite), not a
+  shipped doc — stays inside so doc-index can validate FR references.
+- `decisions/NNNN-title.md` — the plan's formal ADRs (its rationale). Inside
+  keeps the feature folder self-contained and ADR↔task↔plan references valid.
+- `.agent/` — ALL agent/sub-agent working state. The leading dot keeps it out
+  of doc-index scans (process state, not a validated artifact):
+  - `.agent/decisions/NNNN-<slug>.md` — EXECUTION-time decisions a sub-agent
+    takes while working (distinct from the plan's formal ADRs in `decisions/`).
+  - `.agent/learnings.md` — conventions/patterns discovered (append-only).
+  - `.agent/notes/<task-id-or-topic>.md` — worker/survey/investigator notes.
+  - `.agent/reports/<verifier|reviewer|investigate>-<round>.md` — persisted
+    verifier/reviewer/investigation findings.
+
+OUTSIDE `.archgen/` — project DELIVERABLES an approved task produces, written
+to the task's `file_ownership` paths at the repo root (never into `.archgen/`):
+- source code (`src/...`), and
+- shipped documentation: README, API reference, deployment/runbooks, user
+  guides — the docs the running software ships to users/operators.
+
+Enterprise refinement — durable ADRs: a decision that outlives this feature
+(project-wide, e.g. "Postgres over MongoDB") SHOULD also be promoted to the
+project's canonical ADR register (`docs/adr/` or the team's equivalent) so
+future features discover it. `.archgen/<slug>/decisions/` is the working
+record; the register is the durable project-wide copy. Never delete or
+re-number an accepted ADR — supersede it.
+
 ## architecture.yaml (LARGE scope)
 
 The four contract blocks below (`naming_conventions`, `data_contracts`,

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

@@ -1,20 +1,53 @@
 # 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.
+Batch 3–5 questions per message. Never ask what you can infer — ask only
+decision-forks, state everything else as a veto-able decision (§ How to ask).
+
+## How to ask
+
+- **Tool-first, options-fallback.** Use your harness's ask-question /
+  interactive multiple-choice tool when one exists; no such tool → ask inline
+  with labeled options. Same content either way.
+- **Recommendation-first.** Every option set leads with YOUR best judgment
+  tagged `(recommended)`, then alternatives. The user accepts the
+  recommendation by default and may override — never present bare options
+  without a recommendation.
+- **Ask forks, state decisions.** Ask ONLY the few decision-forks that
+  materially branch the plan. Everything derivative: DECIDE autonomously and
+  announce — "I'll use X because Y — say so if you'd rather Z" — so the user
+  can veto without being interrogated.
+- **Volume scales with scope.** Round caps (§ Step 1) are MAXIMA, not targets:
+  SMALL/simple prompt → at most 1–2 core questions, decide the rest; MEDIUM →
+  the targeted set; LARGE — or an experienced engineer signaling they want
+  control → the fuller discovery set.
+
+Worked example (recommendation-first, inline fallback form):
+
+> Rollout strategy?
+> 1. Feature flag + staged rollout **(recommended)** — existing users unaffected
+> 2. Immediate cutover — simpler, riskier
+> 3. Versioned API alongside — only if existing clients break
+> Reply 1–3, or just "ok" to accept the recommendation.
 
 ## Round 0 — calibration exchange (skippable)
 
-Two or three rapid questions, asked once at the very start:
+Two or three rapid items, asked once at the very start — each INFERRED first
+(§ How to ask), asked only when genuinely ambiguous:
 
-1. Rough scale: prototype, MVP, or production-bound?
+1. Rough scale: prototype, MVP, or production-bound? INFER from the opening
+   message + repo context; state the inference + one line of reasoning and
+   let the user confirm or correct. Ask open-ended ONLY when genuinely
+   ambiguous.
 2. Team size + convention constraints? (solo? existing lint/CI/style guides?)
 3. Deadline pressure: none, moderate, crunch?
 
 Purpose is ONLY to pick question-set depth and right-size later verification
 rigor — never to collect requirements. SKIP the whole exchange when the user's
-opening message already answers these items (e.g. "quick prototype by Friday").
-Record whatever was captured under `calibration:` in answers.yaml.
+opening message already answers these items (e.g. "quick prototype by
+Friday"); SMALL/simple prompts skip calibration entirely and go straight to
+their 1–2 core forks (§ How to ask). Record whatever was captured under
+`calibration:` in answers.yaml.
 
 ## Step 1 — classify intent (decide during round 1)
 
@@ -31,6 +64,17 @@ the user in one sentence, and record it as `intent_class` in answers.yaml:
 Never interrogate a BROWNFIELD-FEATURE with PRD-grade questions — token waste,
 user annoyance. Round caps INCLUDE round 0 when it runs.
 
+Default `scope_class` from the intent class (user's choice wins — scope_class
+is agreed in GENERATE step 1 and recorded in answers.yaml):
+GREENFIELD-SYSTEM→LARGE, GREENFIELD-MODULE→MEDIUM,
+BROWNFIELD-FEATURE→MEDIUM/SMALL, BROWNFIELD-CHANGE→SMALL.
+
+Scale is INFERRED, not asked: derive scope_class from the opening message +
+repo context + the class above, state it with one line of reasoning, and let
+the user confirm or correct. Ask about scale ONLY when genuinely
+ambiguous/confused. Small/simple prompts: skip heavy calibration, ask only
+the 1–2 core forks (§ How to ask), decide the rest.
+
 ## GREENFIELD-SYSTEM — professional discovery (≤6 rounds)
 
 Creating a system from scratch demands PRD-grade inputs. Each round below
@@ -158,7 +202,8 @@ resolve before proceeding. [wait for user]
 ## Token discipline
 
 - Batch 3–5 questions per message; never ping-pong one-per-message.
-- Hard round caps: GREENFIELD-SYSTEM ≤6 rounds, every other class ≤3
+- Hard round caps — MAXIMA, not targets (small prompts ask far fewer;
+  § How to ask): GREENFIELD-SYSTEM ≤6 rounds, every other class ≤3
   (round 0 counts when it runs).
 - Skip any question already answered by the opening message, calibration, or
   survey artifacts.

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

@@ -24,29 +24,127 @@ 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:
+Dispatch AFTER artifacts exist and validate.mjs passes.
+
+### Agent tier — EVERY verifier dispatch
+
+Verification is judgment-heavy: a weak verifier misses real defects AND raises
+false positives — costing MORE rounds, not fewer. Dispatch on the strongest
+reasoning agent the harness offers (best agent present), or a mid/high-tier
+sub-agent scaled to plan complexity:
+
+- SMALL/MEDIUM plan → one strong (mid/high-tier) agent.
+- LARGE plan → the stronger/highest tier available.
+- NEVER an explore / research / quick / small / cheap / fast sub-agent,
+  whatever the harness calls its low-end tiers.
+
+### Verification pass — FULL-DEPTH, every run
+
+Each verifier run executes ALL four steps:
 
 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:
+2. When markdown artifacts exist under `.archgen/<slug>/`, runs
+   `node <skill>/scripts/doc-index.mjs .archgen/<slug> --validate` — must be
+   clean (zero broken references, exit 0) alongside verify-plan APPROVE;
+   broken references block APPROVAL.
+3. 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.
+   - CONTRACT-COMPLETENESS sweep — round 1 must confirm OR flag-as-missing
+     every APPLICABLE dimension (later discovery = the round-1 sweep failed,
+     not a gap). Apply a dimension only where the system actually has that
+     concern — skip what genuinely doesn't apply, but NEVER skip a dimension
+     the system touches:
+     - **Functional coverage**: every stated requirement/feature has tasks +
+       objectively verifiable acceptance.
+     - **Security & data protection** (if it authenticates, authorizes,
+       encrypts, or handles sensitive data): authn/authz flows, session &
+       credential lifecycle, replay/CSRF protection, encryption & privacy
+       boundaries, input validation — each fully specified, not named-and-
+       skipped.
+     - **Data integrity**: schemas, relationships, validation, and migration /
+       back-compat for any persisted state.
+     - **State, lifecycle & recovery** (if any operation is stateful,
+       long-running, or multi-step): checkpointing/resume, idempotency,
+       cleanup, expiry, compensation/rollback semantics.
+     - **Resource limits & abuse** (if it exposes shared or anonymous
+       resources): quotas, rate limits, retention/deletion, anonymous-abuse
+       controls.
+     - **Operational entrypoints**: every stack-required build/deploy/test/
+       bootstrap entrypoint is OWNED by some task (no orphan entrypoint).
+     - **Metric traceability**: every PRD success metric maps to a task
+       acceptance criterion with a reproducible command / sample size / data
+       source.
+     - **Consistency**: actively check cross-contract claims for internal
+       contradiction (a claim in one artifact that another artifact violates).
+     These failure classes are the TOP cause of multi-round loops — round 1
+     MUST sweep the applicable dimensions exhaustively.
+4. Returns EXACTLY one line verdict: `APPROVE` or `ISSUES:` + numbered list.
+
+### Efficiency — fewer rounds + zero duplicate work, NEVER shallower checks
+
+Every run stays FULL-DEPTH: both scripts run to completion and the full
+judgment checklist applies each time. Efficiency comes ONLY from:
+
+- capping automatic rounds at 2 (gate protocol below);
+- batching fixes per file (fix discipline below);
+- never re-fixing an already-resolved finding.
+
+"Efficient" NEVER means skipping or lightening verify-plan.mjs, doc-index.mjs,
+or any judgment-checklist item.
+
+### Fix discipline — batch per file, dedupe repeats
+
+On `ISSUES:` the orchestrator fixes ALL findings before re-dispatching:
+
+- Group findings BY FILE; apply each file's fixes in ONE edit pass — open
+  each file once per round, not once per finding.
+- Round N reports the SAME finding as round N-1 (same file + same issue) →
+  the prior fix did not land: re-read the file and fix it properly — never
+  re-apply the identical edit.
+
+### Gate protocol — 2 automatic rounds, then ask the user
+
+The initial VERIFIER GATE flow (GENERATE step 5). Rounds 1–2 run
+automatically; fix ALL findings between rounds (fix discipline above):
+
+1. Round 1: dispatch verifier. `APPROVE` → gate passed → §plan-review.
+   `ISSUES:` → fix ALL findings → round 2.
+2. Round 2: dispatch verifier.
+   - Clean `APPROVE` → ask the user once more, recommending NO, proceed.
+   - `ISSUES:` → fix ALL findings → ask the user once more, recommending
+     YES, one more pass.
+   Ask recommendation-first per interview.md § How to ask: "Run the verifier
+   once more to make sure everything passes?"
+3. On YES → run another round; if it returns `ISSUES:`, fix all and ask again
+   — every round beyond 2 is user-approved. On NO → proceed to §plan-review.
+4. On NO with findings still outstanding and no verifier `APPROVE` on record:
+   surface every outstanding finding verbatim and require an EXPLICIT user
+   waiver — never proceed silently. Hard rule 2 stands: the plan MUST NOT
+   reach the USER GATE without at least one verifier `APPROVE` (or that
+   explicit waiver on the record). An earlier `APPROVE` on record → proceed
+   to §plan-review, noting the latest unverified fixes.
 
 ## §plan-review — post-plan review stage
 
-Run AFTER verify-plan returns APPROVE and BEFORE the user gate. Dispatch one
-or more REVIEWER sub-agents; count scales with the right-sizing class:
+Run AFTER verify-plan returns APPROVE and BEFORE the user gate. Dispatch
+REVIEWER sub-agents sized by the right-sizing class — always ONE holistic
+review of the WHOLE plan, never per-concern splits:
 
 - SMALL: main-agent self-review acceptable if no reviewer mechanism exists.
 - MEDIUM: 1 reviewer.
-- LARGE: 2–3 reviewers split by concern (correctness / ordering / docs).
+- LARGE: 1 holistic reviewer on the strongest reasoning tier. A 2nd reviewer
+  ONLY if the plan is genuinely too large for one reviewer's context — split
+  by ARTIFACT/VOLUME then (e.g. plans vs docs), never by concern.
+
+One holistic reviewer analyzes ALL issues together: cross-issue reasoning
+catches contradictions a narrow per-concern slice misses, and one reviewer
+costs far fewer tokens than several. NEVER dispatch one sub-agent per
+individual issue/concern.
 
 ```
 TASK: Review the plan in .archgen/<slug>/ READ-ONLY.
@@ -61,9 +159,29 @@ You NEVER edit files. Report only.
 ```
 
 Reviewers are read-only and report-only — they never edit artifacts or code.
-The orchestrator fixes the artifacts itself, re-runs validate.mjs + re-dispatches
-the verifier gate after every change, and loops until zero findings remain or
-findings are explicitly waived by the user.
+The orchestrator fixes the artifacts itself, re-runs validate.mjs +
+re-dispatches the verifier gate after every change.
+
+### Review loop — bounded passes, then ask
+
+The fix→re-verify cycle stays, but reviewer passes are countable and bounded:
+
+1. Pass 1: holistic review. Zero findings → stage done.
+2. Findings → fix ALL (batched per file), re-run validate.mjs + the verifier
+   gate → pass 2.
+3. Pass 2 still yields findings → do NOT spawn more reviewers. Consolidate
+   the outstanding findings and ask the user once, recommendation-first per
+   interview.md § How to ask: "Run one more targeted review pass on the N
+   open findings? 1. One more pass (recommended) 2. Waive these findings and
+   proceed."
+4. On YES → run EXACTLY ONE more pass, then consolidate and STOP. Zero
+   findings → stage done; findings remain → surface them and require an
+   explicit user waiver before the user gate. On NO → record the explicit
+   waiver, proceed.
+
+A "more review" approval authorizes EXACTLY ONE additional pass — never a
+fresh loop, never more reviewers. The stage ends ONLY at zero findings or an
+explicit user waiver on record.
 
 ## §investigate — root-cause protocol
 
@@ -150,10 +268,15 @@ Every worker receives ALL of:
   `node <skill>/scripts/set-status.mjs .archgen/<slug>/tasks.yaml <id> done|failed`;
 - commit guidance: commit completed work scoped to the owned files;
 - BEFORE writing code run
-  `node <skill>/scripts/plan-graph.mjs --node <task-id> --tasks <tasks.yaml>`
+  `node <skill>/scripts/plan-graph.mjs <slug-dir-or-tasks.yaml> --node <task-id>`
   and honor every connected dependency shown;
 - all file paths come from tasks.yaml/architecture.yaml VERBATIM — never
   reconstruct paths from memory.
+- working state goes under `.archgen/<slug>/.agent/` — execution decisions to
+  `.agent/decisions/`, notes to `.agent/notes/<id>.md` (see
+  references/artifact-templates.md § Agent workspace & artifact location).
+  NEVER create ad-hoc note/context/decision folders at the repo root or
+  anywhere outside `.archgen/`.
 
 Workers do NOT talk to each other; coordination happens only through
 tasks.yaml state.

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

@@ -81,3 +81,58 @@ Claude Code project-scope servers.
 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.
+
+## Codegraph indexing scope
+
+Current mainstream codegraph indexers extract SOURCE symbols only
+(functions/classes/imports) — they do not index markdown headings, and YAML
+support ranges from absent to file-level config tracking; none can graph
+tasks.yaml dependencies (audited 8 codegraph-family tools Aug 2026; local
+binary v1.0.1 empirically confirms). Generic code indexers verifiably do not
+extract markdown headings or YAML task semantics, so archgen ships its own
+deterministic graph tools:
+
+- Source navigation → codegraph MCP when configured (offered at Step 0).
+- YAML plan graphs → exclusively `scripts/plan-graph.mjs`.
+- Markdown artifact navigation → `scripts/doc-index.mjs`.
+
+If the harness exposes a markdown-heading indexer (e.g. a
+`codegraph_index_markdown`-style tool), prefer it for general repo docs but
+still use `doc-index.mjs` inside `.archgen/` — it understands TASK/FR
+reference semantics. Brownfield surveys prefer codegraph once present.
+
+### Codegraph install & index (concrete — researched Aug 2026, v1.0.1)
+
+CodeGraph = `@colbymchenry/codegraph` (npm), CLI `codegraph`, MIT, 100% local.
+It persists a SQLite symbol graph in `.codegraph/` and serves it over MCP. It
+indexes SOURCE symbols only (scope above) — pair with `doc-index.mjs` /
+`plan-graph.mjs` for markdown/YAML. Requires Node 22 or 24 (native SQLite
+bindings; other versions fall back to a 5–10x-slower WASM backend).
+
+Install the CLI (one-time, global):
+- `npm i -g @colbymchenry/codegraph` (any OS with Node), or
+- `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), or
+- zero-install: `npx @colbymchenry/codegraph`.
+
+Wire the harness (writes MCP config + instructions — INSTALL-MCP approval gate):
+- `codegraph install --yes` (auto-detect agents, global)
+- `codegraph install --target=<agent> --yes` (explicit harness)
+- `codegraph install --target=auto --location=local --yes` (project-local)
+- `codegraph install --print-config <agent>` (preview snippet, no writes)
+- Manual config shape: assets/mcp-template.json (stdio `codegraph serve --mcp`
+  or npx `-y @colbymchenry/codegraph mcp`).
+
+Index the project (per project; creates `.codegraph/` + builds the graph):
+- `codegraph init` (add `--yes` to skip prompts); one-shot bootstrap:
+  `codegraph install --yes --init`. Auto-syncs on file change thereafter.
+- `codegraph status` to verify; `codegraph uninit` removes the index;
+  `codegraph uninstall` de-wires the agents; `codegraph upgrade` updates.
+
+`.codegraph/` is deterministic and small — committing it gives teammates the
+index on first checkout (team recommendation); git-ignore it for solo repos.
+Never point two OSes (Windows + WSL) at one `.codegraph/`.
+
+Agent flow: detect `.codegraph/` at repo root. Present → use `codegraph_explore`
+for source navigation. Absent → offer once (INSTALL-MCP approval pattern,
+recommendation-first), run the commands above on approval; on decline use
+Glob+Grep.

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

@@ -2,16 +2,26 @@
 // 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).
 
+/** True iff `t` is a mapping object (not null, not an array, not a scalar). */
+function isTaskMapping(t) {
+  return t !== null && typeof t === 'object' && !Array.isArray(t);
+}
+
 /** 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. */
+ * every prerequisite is done; wave 1 = empty depends_on.
+ * Entries must be mappings with a non-empty string id — anything else is a
+ * GraphError naming the index, so consumers exit with a clean contract code
+ * instead of an uncaught TypeError on malformed tasks.yaml shapes. */
 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) {
+  for (const [i, t] of tasks.entries()) {
+    if (!isTaskMapping(t)) throw new GraphError(`tasks[${i}]: not a mapping (task entries must be 'key: value' mappings)`);
+    if (typeof t.id !== 'string' || t.id.length === 0) throw new GraphError(`tasks[${i}]: missing string 'id' (every task needs a non-empty string id)`);
     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 : []);
@@ -169,7 +179,9 @@ function globsMayOverlap(a, b) {
 export function dedupeDependencies(tasks) {
   let duplicatesCollapsed = 0;
   const normalized = tasks.map((t) => {
-    if (!Array.isArray(t.depends_on)) return t;
+    // Malformed entries pass through untouched; buildGraph owns reporting them
+    // (touching t.depends_on here would throw before the contract check runs).
+    if (!isTaskMapping(t) || !Array.isArray(t.depends_on)) return t;
     const seen = new Set();
     const deps = [];
     for (const d of t.depends_on) {
@@ -197,6 +209,9 @@ export function computeQualityStats(tasks) {
   let emptyOwnership = 0;
   let blankAcceptance = 0;
   for (const t of tasks) {
+    // Malformed entries are buildGraph's to report; counting them here would
+    // throw on property access before any consumer sees a contract error.
+    if (!isTaskMapping(t)) continue;
     if (Array.isArray(t.depends_on) && t.depends_on.includes(t.id)) selfDeps++;
     const own = t.file_ownership;
     if (!Array.isArray(own) || own.length === 0) emptyOwnership++;

package/vendor/skills/archgen/scripts/set-status.mjs

@@ -3,9 +3,13 @@
 // Usage: node set-status.mjs <tasks.yaml> <taskId> <status> [--force]
 // ANY transition out of 'done' requires --force (reopening completed work —
 // directly or via a failed/blocked hop — needs explicit intent). Exit 4 on refusal.
-// Writes via temp-file + rename so concurrent readers never see partial files,
+// Writes via O_EXCL temp-file + rename so concurrent readers never see partial
+// files (same-wave parallel workers + crash mid-write both safe: the original
+// stays byte-intact until the rename lands; a failure or kill before the rename
+// leaves at worst an orphaned .tmp- sibling, never a half-written tasks.yaml),
 // and re-emits the file's dominant line-ending convention (CRLF stays CRLF).
-import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+// Exit codes: 0 ok · 4 usage/refusal/parse/IO errors.
+import { readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
 import { parseYaml, stringifyYaml } from './lib/yaml.mjs';
 
 const STATUSES = ['pending', 'ready', 'running', 'blocked', 'done', 'failed'];
@@ -54,7 +58,25 @@ if (prev === 'done' && nextStatus !== 'done' && !force) {
 }
 
 task.status = nextStatus;
-const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-writeFileSync(tmp, stringifyYaml(data, comments, { eol }));
-renameSync(tmp, file); // atomic on POSIX: readers observe old-or-new, never partial
+// O_EXCL ('wx') guarantees the temp path is freshly created — a stale leftover
+// with the same pid+timestamp is never silently truncated and overwritten.
+const content = stringifyYaml(data, comments, { eol });
+let tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+for (let attempt = 0; ; attempt++) {
+  try {
+    writeFileSync(tmp, content, { flag: 'wx' });
+    break;
+  } catch (e) {
+    if (e?.code === 'EEXIST' && attempt < 10) { tmp = `${file}.tmp-${process.pid}-${Date.now()}-${attempt + 1}`; continue; }
+    console.error(`${file}: cannot write temp file (${e?.code ?? e?.message ?? e})`);
+    process.exit(4);
+  }
+}
+try {
+  renameSync(tmp, file); // atomic on POSIX: readers observe old-or-new, never partial
+} catch (e) {
+  try { unlinkSync(tmp); } catch { /* original intact; leftover tmp is harmless */ }
+  console.error(`${file}: atomic rename failed (${e?.code ?? e?.message ?? e}) — original left untouched`);
+  process.exit(4);
+}
 console.log(`${taskId}: ${prev} -> ${nextStatus}`);

package/vendor/skills/archgen/scripts/update-agents.mjs

@@ -9,7 +9,7 @@
 // disappeared are pruned by default (--prune is accepted as the explicit
 // no-op spelling of the same behavior). Writes atomically via temp + rename.
 // Exit codes: 0 ok · 2 no .archgen/ dir · 4 usage/IO/marker errors.
-import { existsSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseYaml } from './lib/yaml.mjs';
 
@@ -194,9 +194,18 @@ for (const r of ordered) {
   else unchanged++;
 }
 
+// O_EXCL ('wx') guarantees the temp path is freshly created; the original
+// AGENTS.md stays byte-intact until the rename lands (crash mid-write leaves
+// at worst an orphaned .tmp- sibling, never a half-written registry).
 const tmp = `${agentsPath}.tmp-${process.pid}-${Date.now()}`;
-writeFileSync(tmp, out);
-renameSync(tmp, agentsPath); // atomic on POSIX: readers observe old-or-new, never partial
+try {
+  writeFileSync(tmp, out, { flag: 'wx' });
+  renameSync(tmp, agentsPath); // atomic on POSIX: readers observe old-or-new, never partial
+} catch (e) {
+  try { unlinkSync(tmp); } catch { /* original intact; leftover tmp is harmless */ }
+  console.error(`${agentsPath}: atomic write failed (${e?.code ?? e?.message ?? e}) — original left untouched`);
+  process.exit(4);
+}
 
 console.log(banner);
 for (const n of notes) console.log(n);