archgen-skill 0.1.0 → 0.1.2

package/lib/node_modules/archgen-mcp/src/tools/tasks.mjs

@@ -0,0 +1,206 @@
+// tasks.mjs — the `archgen_tasks` tool: the wave execution loop.
+import { z } from 'zod/v4';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { resolveWaves, listTasks } from '../core/wave-resolver.mjs';
+import { buildWorkerContract } from '../core/worker-contract.mjs';
+import { matchSkills, findInstalledSkill, skillRules, skillSections } from '../core/skill-manager.mjs';
+import { docIndex } from '../core/doc-navigator.mjs';
+import { parseYaml } from '../core/yaml.mjs';
+import { readFileSync, existsSync } from 'node:fs';
+import { loadAsset } from '../context.mjs';
+import { setTaskStatus, STATUSES } from '../core/status-mutator.mjs';
+import { writeResumeSnapshot } from '../core/resume-snapshot.mjs';
+import { invalidInput } from '../core/errors.mjs';
+import { resolveSlugInput, ScopeError } from '../core/scope.mjs';
+import { dirname, join } from 'node:path';
+
+/**
+ * The `.archgen/<slug>/` directory a tasks file belongs to.
+ *
+ * A tasks.yaml outside the artifact space has no slug directory, so there is
+ * nowhere the snapshot may be written — and the worker contract says the
+ * snapshot is NEVER created outside `.archgen/`.
+ */
+function slugDirFor(tasksFile, action) {
+  try {
+    return resolveSlugInput(tasksFile).root;
+  } catch (e) {
+    if (e instanceof ScopeError) {
+      throw invalidInput(
+        `tasks.yaml must live in .archgen/<slug>/ — ${tasksFile} does not`,
+        { action, file: tasksFile },
+      );
+    }
+    throw e;
+  }
+}
+
+const ACTION_DESC = 'next | set_status | list | snapshot | contract — see archgen_help.';
+
+const schema = z.object({
+  action: z.enum(['next', 'set_status', 'list', 'snapshot', 'contract']).describe(ACTION_DESC),
+  tasksYaml: z.string().optional().describe('Absolute path to tasks.yaml. Required for next, set_status and list.'),
+  taskId: z.string().optional().describe('Task id (set_status).'),
+  status: z.enum(STATUSES).optional().describe('New status (set_status).'),
+  force: z.boolean().optional().describe('Allow reopening a done task (set_status).'),
+  filterStatus: z.string().optional().describe('Filter by status (list).'),
+  slugDir: z.string().optional().describe('The .archgen/<slug>/ directory (contract) — locates the plan docs.'),
+  codeStandardsPath: z.string().optional().describe('Path to the code-standards reference (contract).'),
+  module: z.string().optional().describe('Filter by module path fragment (list).'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerTaskTools(server) {
+  registerTool(server, 'archgen_tasks', {
+    title: 'ArchGen tasks',
+    description:
+      'Execute an archgen plan: resolve the next dependency-safe wave, update task status atomically, ' +
+      'list tasks, or write the resume snapshot that survives context compaction.',
+    inputSchema: schema,
+    readOnly: false,
+    destructive: true,
+    handler: (ctx, args) => {
+      const action = args.action;
+
+      switch (action) {
+        case 'set_status': {
+          if (!args.tasksYaml) throw invalidInput('tasksYaml is required for set_status', { action });
+          if (!args.taskId) throw invalidInput('taskId is required for set_status', { action });
+          if (!args.status) throw invalidInput('status is required for set_status', { action });
+          return setTaskStatus(ctx.contain(args.tasksYaml), args.taskId, args.status, { force: args.force === true });
+        }
+        case 'list': {
+          if (!args.tasksYaml) throw invalidInput('tasksYaml is required for list', { action });
+          return listTasks(ctx.contain(args.tasksYaml), {
+            status: args.filterStatus ?? null,
+            module: args.module ?? null,
+          });
+        }
+        case 'snapshot': {
+          if (!args.tasksYaml) throw invalidInput('tasksYaml is required for snapshot', { action });
+          const tasksFile = ctx.contain(args.tasksYaml);
+          // The snapshot belongs to the artifact space: `<slug>/.agent/`.
+          // Deriving it from the tasks file's PARENT wrote it wherever that
+          // file happened to be — `<project>/plans/.agent/resume.md`, outside
+          // `.archgen/`, which is exactly what the worker contract forbids.
+          const slugDir = slugDirFor(tasksFile, action);
+          const waves = resolveWaves(tasksFile).waves;
+          return writeResumeSnapshot(slugDir, waves);
+        }
+        case 'contract': {
+          if (!args.tasksYaml) throw invalidInput('tasksYaml is required for contract', { action });
+          if (!args.taskId) throw invalidInput('taskId is required for contract', { action });
+          const tasksFile = ctx.contain(args.tasksYaml);
+          const slugDir = args.slugDir ? ctx.contain(args.slugDir) : dirname(tasksFile);
+
+          // The capability skills: match the task, resolve the INSTALLED
+          // path, and carry the skill's NORMATIVE RULES into the prompt.
+          //
+          // EVERY matched required skill is included. The old code injected
+          // `required[0]` only — so a task matching the baseline AND the
+          // accessibility skill silently lost the second, even though it had
+          // been installed on purpose. An installed skill that no contract
+          // ever names is a skill that is never applied.
+          //
+          // The rules travel WITH the contract rather than as a path alone:
+          // a pointer is a file the worker may never open, and a worker that
+          // never opens it produces work that ignores the skill.
+          let capabilities = [];
+          try {
+            const registry = loadAsset('skill-registry.json');
+            const raw = readFileSync(tasksFile, 'utf8');
+            const { data } = parseYaml(raw, { filename: tasksFile });
+            const task = (data?.tasks ?? []).find((t) => t?.id === args.taskId);
+            const matched = matchSkills(registry, {
+              title: task?.title ?? '',
+              summary: task?.summary ?? '',
+              fileOwnership: task?.file_ownership ?? [],
+            });
+            const required = matched.filter((m) => m.policy === 'required');
+            capabilities = required.map((m) => {
+              const found = findInstalledSkill(ctx.projectRoot, m.slug, { home: ctx.home });
+              const cap = {
+                slug: m.slug,
+                path: found.path,
+                purpose: m.purpose,
+                domain: m.domain,
+                installed: found.installed,
+                rules: '',
+                sections: [],
+              };
+              if (found.installed && found.path) {
+                try {
+                  const content = readFileSync(found.path, 'utf8');
+                  cap.rules = skillRules(content).rules;
+                  cap.sections = skillSections(content).map((s) => ({
+                    slug: s.slug,
+                    title: s.title,
+                    normative: s.normative,
+                  }));
+                } catch {
+                  cap.rules = '';
+                  cap.sections = [];
+                }
+              }
+              return cap;
+            });
+          } catch {
+            capabilities = []; // a missing registry or an unparsed task must not break the contract
+          }
+
+          // The doc sections that actually contain this task's contract — never
+          // the whole plan.
+          let docSections = [];
+          try {
+            const map = docIndex(slugDir, { mode: 'map', token: args.taskId, projectRoot: ctx.projectRoot });
+            docSections = (map.data.sections ?? []).slice(0, 2).map((s) => ({
+              file: s.file,
+              section: s.section,
+              title: s.title,
+              line: s.line,
+              endLine: s.endLine,
+            }));
+          } catch {
+            docSections = [];
+          }
+
+          // The code-standards reference: resolved from the INSTALLED skill when
+          // the caller does not name it. The worker needs a real path, and the
+          // agent should not have to guess where the skill lives.
+          //
+          // A caller-supplied path is CONTAINED, exactly like every other
+          // path argument: it ends up verbatim in a prompt a worker reads,
+          // so an uncontained one would point the worker anywhere on the
+          // machine.
+          const codeStandardsPath = args.codeStandardsPath
+            ? ctx.contain(args.codeStandardsPath)
+            : ctx.skill
+              ? join(ctx.skill.path, 'references', 'code-standards.md')
+              : null;
+
+          const contract = buildWorkerContract({
+            tasksYaml: tasksFile,
+            taskId: args.taskId,
+            slugDir,
+            codeStandardsPath,
+            capabilities,
+            docSections,
+            // CodeGraph is DETECTED here, not left for the worker to work
+            // out: the instruction only helps if it is in the prompt.
+            codegraph: existsSync(join(ctx.projectRoot, '.codegraph')),
+          });
+          return contract;
+        }
+        case 'next': {
+          if (!args.tasksYaml) throw invalidInput('tasksYaml is required for next', { action });
+          return resolveWaves(ctx.contain(args.tasksYaml));
+        }
+        default:
+          throw invalidInput(`unknown action '${action}'`, { action });
+      }
+    },
+  });
+}

package/lib/store.js

@@ -177,9 +177,26 @@ function realpathWithTail(p) {
  * outside `rootAbs`. Catches `.agents -> /elsewhere` style redirects that a
  * final-component lstat cannot see.
  *
- * The LEXICAL check always applies — it is the only guard that can work when
- * the root does not exist yet (init calls this before it created anything),
- * and a lexical escape (`../../etc/passwd`) is an escape under any root.
+ * TWO COMPARISONS, AND THE PATH IS ALLOWED IF EITHER SAYS IT IS INSIDE.
+ *
+ *   1. LEXICAL — the caller's spelling against the root's spelling.
+ *   2. REAL — where the path actually LANDS against where the root actually
+ *      IS. This is the one that catches a symlinked PARENT.
+ *
+ * They can disagree, and they DO whenever the root and the path are spelled
+ * differently — the NORMAL case on macOS (`/tmp`, `/var`) and for any
+ * symlinked project: `process.cwd()` is the REAL path while the caller
+ * passes the LOGICAL one.
+ *
+ * The old guard compared the LEXICAL path against the REAL root and refused
+ * on that mismatch, so a perfectly valid path inside the project was
+ * reported as an escape — and the two names the SAME place. The real
+ * comparison is the one that can actually answer the question, and it must
+ * be allowed to.
+ *
+ * The guard does NOT fail open: when the real comparison cannot be made the
+ * lexical one stands alone, and a path outside the root by every measure we
+ * could make is always refused.
  *
  * @param {string} rootAbs project/base root
  * @param {string} absPath path that must stay inside the root
@@ -187,17 +204,20 @@ function realpathWithTail(p) {
 export function assertWithinRoot(rootAbs, absPath) {
   const rootLex = resolve(rootAbs);
   const pathLex = resolve(absPath);
-  if (pathLex !== rootLex && !pathLex.startsWith(rootLex + sep)) {
-    throw new Error(refuseSymlinkMessage(absPath));
-  }
 
   const rootReal = realpathWithTail(rootLex);
   const pathReal = realpathWithTail(pathLex);
-  // Unresolvable (no existing ancestor at all): the lexical check stands.
-  if (!rootReal || !pathReal) return;
-  if (pathReal !== rootReal && !pathReal.startsWith(rootReal + sep)) {
-    throw new Error(refuseSymlinkMessage(absPath));
-  }
+
+  const lexicalInside = pathLex === rootLex || pathLex.startsWith(rootLex + sep);
+  const realInside =
+    rootReal && pathReal ? pathReal === rootReal || pathReal.startsWith(rootReal + sep) : null;
+
+  if (realInside === true || (realInside === null && lexicalInside)) return;
+
+  // Outside by every measure we could make. The refusal WORDING is unchanged
+  // from the guard this replaces — it is the CLI's established contract, and
+  // a test pins it. Only the COMPARISON changed.
+  throw new Error(refuseSymlinkMessage(absPath));
 }
 
 /** Version string of this CLI package (used for the in-store stamp). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Architecture generation & autonomous task execution for coding agents - conversational requirements in, dependency-ordered tasks out, executed wave-by-wave with verifier gates. Works with Claude Code, OpenCode, Cursor, Codex, Gemini CLI and any agentskills.io harness.",
   "license": "MIT",
   "type": "module",

package/vendor/skills/archgen/SKILL.md

@@ -4,10 +4,10 @@ description: Architecture generation and autonomous task execution for coding ag
 license: MIT
 compatibility: Requires Node.js >= 20. The archgen MCP server (archgen-mcp) provides every deterministic capability; the skill itself ships no code.
 metadata:
-  version: 0.1.0
+  version: 0.1.2
   repo: https://github.com/akashmaurya99/archgen
   requires:
-    archgen_mcp: ">=0.1.0"
+    archgen_mcp: ">=0.1.2"
 ---
 
 # archgen — architecture generation & wave execution
@@ -57,7 +57,9 @@ Never shell out to scripts to bypass missing tools.
 
 All tools return `{ ok, data, error, meta }`. `ok:false` returns a typed `error.code` (`INVALID_INPUT`, `NOT_FOUND`, `CYCLE`, `OWNERSHIP_CONFLICT`, `CONFLICT`, `PERMISSION_DENIED`, `UNAVAILABLE`, `TIMEOUT`, `INTERNAL`)—handle it as structured data. `ok:true` means the tool call succeeded; inspect `data.valid` for plan health and `data.verdict` for gate verdicts.
 
-**Token discipline:** Fetch sections, never full files—use `archgen_docs{action:'digest'}` $\rightarrow$ `{action:'section'}` and `archgen_refs{action:'index'}` $\rightarrow$ `{action:'read'}`.
+**Token discipline:** Fetch sections, never full files—use `archgen_docs{action:'digest'}` $\rightarrow$ `{action:'section'}` and `archgen_refs{action:'index'}` $\rightarrow$ `{action:'read'}`. Every tool takes `limit`/`offset` (default 50), and every collection narrows to one item (`taskId`, `skillId`, `file`+`section`, `harness`). Each answer's `meta` says what else exists and the exact next call—**fetch it; never take the whole set.**
+
+**Batching:** settle every call in a batch (`allSettled`)—one bad argument must not discard the siblings' results.
 
 ## Loading a reference (§) — MANDATORY
 
@@ -72,7 +74,7 @@ archgen_refs { action: 'search', topic: 'orchestration', token: 'APPROVE' }
 
 **Rules for `§`:**
 1. **Load BEFORE acting.** Entering a mode requires loading its `§` sections first.
-2. **Load SECTIONS, not topics.** Call `index` for exact slugs, then `read` (~1–2 KB vs ~11 KB).
+2. **Load SECTIONS, not topics.** The `§` name IS a slug prefix — `§artifact-templates/plan-depth` resolves to `plan-depth-by-scope-class`. Call `index` only when a prefix is ambiguous.
 3. **Reload after compaction.** Context compaction drops loaded protocols; reload active mode `§` sections immediately upon re-entry (Hard Rule 9).
 4. **Never guess a protocol.** If an unread `§` covers your next step, load it first.
 
@@ -82,7 +84,7 @@ archgen_refs { action: 'search', topic: 'orchestration', token: 'APPROVE' }
 
 1. **Workspace isolation:** Write all generated files inside `.archgen/<project-slug>/` at repo root, including all agent/sub-agent state under `.archgen/<slug>/.agent/` (`§artifact-templates/agent-workspace`). *Exceptions:* (a) approved task code/deliverable edits within declared `file_ownership` (`§orchestration/dispatch`); (b) `AGENTS.md` updates via `archgen_registry`.
 2. **Three pre-execution gates:** (a) VERIFIER sub-agent `APPROVE` on plan + tasks, (b) PLAN-REVIEW at zero findings (or explicit user waiver), (c) USER approval. Never skip a gate.
-3. **Right-size depth:** Classify scope (`SMALL`/`MEDIUM`/`LARGE` per `§interview/step-1`) before creating files. Generate the exact file set returned by `archgen_plan{action:'scaffold', scope, slug}`—adding or omitting files is a defect (`§artifact-templates/plan-depth`). Write dense bullets over prose; never regenerate untouched artifacts.
+3. **Right-size depth:** Classify scope (`SMALL`/`MEDIUM`/`LARGE` per `§interview/step-1`) before creating files. `archgen_plan{action:'scaffold', scope, slug}` returns the exact file set AND each file's CONTENT—**it writes nothing**, you write it; adding or omitting files is a defect (`§artifact-templates/plan-depth`). Write dense bullets over prose; never regenerate untouched artifacts.
 4. **Self-containment:** Artifacts must execute cleanly from `.archgen/<slug>/` alone with zero chat history. Every task must use verbatim repo-root-relative paths from `architecture.yaml`/`tasks.yaml`. Forbidden phrases: `"as discussed"`, `"see chat"`, `"same as before"` (`§artifact-templates/self-containment`).
 5. **Completeness:** No partial features ship as done. Acceptance criteria must be objectively verifiable and cover edge-matrix rows. Stubs, TODOs, and mock-only paths count as `failed` tasks even if tests pass. Include a per-feature completeness checklist in the final report.
 6. **Status discipline (PER-TURN, NON-NEGOTIABLE):** Immediately upon EVERY task completion, in the same turn before any other action, execute and verify all three:
@@ -91,11 +93,12 @@ archgen_refs { action: 'search', topic: 'orchestration', token: 'APPROVE' }
    3. `AGENTS.md` updated via `archgen_registry{action:'update'}`.
    After EACH completed wave, write the 10-line resume snapshot via `archgen_tasks{action:'snapshot'}`. Dispatching a new wave while status updates lag is FORBIDDEN.
 7. **Platform awareness:** Run `archgen_setup{action:'harness_info'}` before editing configs or spawning sub-agents. Unknown platform $\rightarrow$ web-search official MCP/skill docs, present findings, and obtain user approval before writing.
-8. **Contractual code quality:** Workers must obey `references/code-standards.md` (zero `any`, no unhandled `undefined`, files < 1000 LOC, modular directory layout, why-comments). The verifier rejects violations.
+8. **Contractual code quality:** Workers must obey `references/code-standards.md` (zero `any`, no unhandled `undefined`, files < 1000 LOC, modular directory layout, why-comments). **Source and tests are separate trees**—the test tree is a sibling of the source tree, never inside it; the test file NAME is the language's choice. The verifier rejects violations.
 9. **Compaction recovery:** Immediately after any context summarization, execute in order:
    1. `archgen_tasks{action:'next'}` and `archgen_tasks{action:'snapshot'}` to restore ground-truth state.
    2. Reload the current mode's `§` sections via `archgen_refs`.
    Never act on memorized state, paths, or statuses.
+10. **Version-controlled artifacts:** Every archgen artifact in the project is **COMMITTED**—the plan of record (`.archgen/<slug>/`), the installed skill, `AGENTS.md`, and the project MCP config. NEVER gitignore one; remove any rule that hides it (`§artifact-templates/artifact-tracking`).
 
 ## Codegraph — use it when you need understanding
 
@@ -114,7 +117,7 @@ Select ONE mode matching user intent and **load its required `§` sections BEFOR
 
 | Intent | Mode | Mandatory Pre-Load (`§`) |
 |---|---|---|
-| Build net-new system/module | **GENERATE** | `§interview/how-to-ask` · `§interview/step-1` · `§artifact-templates/plan-depth` · `§artifact-templates/self-containment` · `§orchestration/verifier` · `§orchestration/plan-review` |
+| Build net-new system/module | **GENERATE** | `§interview/how-to-ask` · `§interview/step-1` · `§artifact-templates/plan-depth` · `§artifact-templates/self-containment` · `§artifact-templates/artifact-tracking` · `§orchestration/verifier` · `§orchestration/plan-review` |
 | Add/modify feature in existing repo | **BROWNFIELD** | `§orchestration/survey` · then all **GENERATE** sections |
 | Execute pending tasks ("start work") | **START-WORK** | `§orchestration/dispatch` · `§orchestration/failure-policy` |
 | Change requirements mid-flight | **UPDATE** | `§orchestration/verifier` · `§orchestration/plan-review` · `§artifact-templates/plan-depth` |
@@ -127,14 +130,15 @@ Select ONE mode matching user intent and **load its required `§` sections BEFOR
 
 ## GENERATE (greenfield)
 
-**Pre-load:** `§interview/how-to-ask` · `§interview/step-1` · `§artifact-templates/plan-depth` · `§artifact-templates/self-containment` · `§orchestration/verifier` · `§orchestration/plan-review`.
+**Pre-load:** `§interview/how-to-ask` · `§interview/step-1` · `§artifact-templates/plan-depth` · `§artifact-templates/self-containment` · `§artifact-templates/artifact-tracking` · `§orchestration/verifier` · `§orchestration/plan-review`.
 
 1. **Acknowledge & scope:** State planned action + inferred scope (`SMALL`/`MEDIUM`/`LARGE`) in one sentence. Ask to proceed. `[wait for user]`
 2. **Interview:** Follow the loaded `§interview` sections—calibrate (Round 0), record `intent_class` in `answers.yaml`, batch 3–5 recommendation-first decision-fork questions per round. `[wait per round]`
 3. **Generate artifacts** in `.archgen/<slug>/` (on collision, use `<slug>-2`, `<slug>-3`; never overwrite/merge):
-   - Call `archgen_plan{action:'scaffold', scope, slug}` FIRST and populate the exact returned artifact skeletons.
+   - Call `archgen_plan{action:'scaffold', scope, slug}` FIRST and populate the exact returned artifact skeletons. It returns each file's CONTENT and **writes nothing**—you write them under `.archgen/<slug>/`.
    - Ensure every task specifies `id`, `title`, `depends_on`, disjoint `file_ownership` globs, objective `acceptance` criteria, and leaves `status` unset.
    - Run the **FETCH-SKILL pre-planning scan** before finalizing.
+   - **Commit the artifact set** before the first wave—`.archgen/<slug>/` is version-controlled, never ignored (Hard Rule 10).
 4. **Validate & register:** Run `archgen_plan{action:'validate', tasksYaml}` and fix errors until `data.valid:true`. Then run `archgen_registry{action:'update', slug, status:'planned'}` (repeat after any subsequent artifact edit).
 5. **VERIFIER GATE:** Dispatch ONE holistic verifier sub-agent on the strongest reasoning tier using `archgen_plan{action:'brief', kind:'verifier'}` verbatim. Requires `APPROVE` from `archgen_plan{action:'verify', tasksYaml, planDir}`, zero broken refs from `archgen_docs{action:'validate'}`, and a complete `COVERAGE:` table (`PASS`/`FAIL`/`N/A` per dimension). Batch fixes per file; run max 2 automatic rounds, then ask user recommendation-first (`§orchestration/gate-protocol`).
 6. **PLAN-REVIEW:** Dispatch ONE read-only holistic reviewer (sized per `§orchestration/plan-review`) using `archgen_plan{action:'brief', kind:'review'}` verbatim. Fix findings yourself, re-running `validate` + Verifier Gate after edits. Bounded passes: user approval for "more review" grants exactly ONE additional pass before consolidating.
@@ -167,7 +171,7 @@ Select ONE mode matching user intent and **load its required `§` sections BEFOR
    - **Fallback.** If sub-agents are unsupported, fail to spawn, or lack file permissions $\rightarrow$ **self-execute sequentially** without asking permission. Cross-harness/CLI switching requires explicit user approval.
    - **Worker prompt.** Pass `archgen_tasks{action:'contract', tasksYaml, taskId}` verbatim. Halt if `warnings` report missing acceptance criteria, missing `file_ownership`, or uninstalled required skills.
 4. **Per-task closeout (Hard Rule 6):** As each task finishes (same turn): verify `set_status` (`done`|`failed`) landed, complete todo tracker item, and run `archgen_registry{action:'update'}`.
-5. **Wave closeout:** Once the wave settles, verify all statuses landed, update `AGENTS.md`, write the resume snapshot (`archgen_tasks{action:'snapshot'}`), and call `next`. Never auto-retry failed tasks—report failure, propose a fix task, and `[wait for user]`.
+5. **Wave closeout:** Once the wave settles, verify all statuses landed, update `AGENTS.md`, write the resume snapshot (`archgen_tasks{action:'snapshot'}`), **commit the wave's artifact state**—the updated `tasks.yaml` and the `.agent/` notes, decisions and reports—with the wave's commits, and call `next`. Never auto-retry failed tasks—report failure, propose a fix task, and `[wait for user]`.
 6. **Loop:** Repeat steps 1–5 until no actionable tasks remain.
 7. **Final report:** Summarize done/failed/blocked tasks, commits, follow-ups, clean `archgen_docs{action:'validate'}` status, and per-feature completeness checklist (Hard Rule 5); check off `.archgen/<slug>/plans/*.md` items.
 
@@ -211,7 +215,7 @@ Capability loading is mandatory whenever work matches a registry domain (`archge
 
 ## Things you must NOT do
 
-- **NEVER** violate Hard Rules 1–9.
+- **NEVER** violate Hard Rules 1–10.
 - **NEVER** overwrite or merge into an existing `.archgen/<slug>/` directory—use `-2`, `-3` suffixes.
 - **NEVER** auto-spawn external CLIs/harnesses when sub-agents fail—self-execute or get user approval.
 - **NEVER** self-execute tasks while native sub-agents are healthy and available.
@@ -238,7 +242,7 @@ Capability loading is mandatory whenever work matches a registry domain (`archge
 | `§` Topic | Scope |
 |---|---|
 | `§interview` | Elicitation playbook, intent classes, question sets, `answers.yaml` spec |
-| `§artifact-templates` | Self-containment, scope depth ladder, workspace layout, authoring rules |
+| `§artifact-templates` | Self-containment, scope depth ladder, workspace layout, artifact tracking, authoring rules |
 | `§orchestration` | Survey, Verifier, Plan-Review, Investigate, and Wave Dispatch protocols |
 | `§platforms` | Harness detection, MCP config schemas, unknown-platform flow, CodeGraph scope |
 | `§mcp-and-skills` | Approval-gated `INSTALL-MCP` and mandatory `FETCH-SKILL` workflows |

package/vendor/skills/archgen/archgen.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0",
+  "version": "0.1.2",
   "skillName": "archgen",
   "markers": {
     "start": "<!-- archgen:start (managed block - do not edit between markers) -->",

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

@@ -21,22 +21,37 @@ src/
   features/<name>/   # Feature-first: everything a feature owns
     api/             # Inbound contracts (routes/handlers)
     internal/        # Private implementation
-    tests/           # Colocated tests mirroring structure
   shared/            # Cross-feature utilities ONLY; MUST NOT import features/
   config/            # Typed env parsing + constants
+tests/
+  unit/              # Unit tests — mirror the source path
+    features/<name>/
+  integration/       # Feature-level tests across module boundaries
+  e2e/               # User journeys, end to end
 ```
 
 - `features/*` may import `shared/`; `shared/` imports NOTHING from `features/`.
-- Colocate tests beside the code they test—never in a disconnected root `/tests` directory.
+
+## Source and tests are SEPARATE trees
+
+The test tree is a **sibling** of the source tree, never a child.
+
+- **No test tree inside the source tree:** no `tests/` directory under `src/`, and no test file beside the code it covers.
+- **The mirror:** the path under the source root is preserved; the source root is replaced by the test root. `src/features/catalog/api/routes.ts` → `tests/unit/features/catalog/api/<test file>`. A monorepo package mirrors its own source: `packages/foo/src/**` → `packages/foo/tests/unit/**`.
+- **The FILE NAME is the language's business.** This standard fixes the PLACE, never the name—use the naming convention the language's ecosystem and the host repository already use. The plan's `architecture.yaml` records it in `naming_conventions.test_placement`.
+- **One exception:** a language whose test runner discovers tests only inside the package directory keeps those files beside the code they cover. Everything the runner can discover elsewhere—integration and end-to-end tests—still lives in the test tree.
+- **Ownership follows the tree:** a task that owns `src/features/x/**` also owns `tests/unit/features/x/**`. A worker may not write outside `file_ownership`, so the mirrored path must be in it. A plan that gives the tests to a dedicated task is valid too—as long as some task owns them.
+
+Why: one directory holding both `foo.ts` and its test grows a second, undeclared structure. The test files become half the listing, imports blur, and "where does this go?" becomes a per-file judgement call that different agents answer differently.
 
 ## File naming
 
-| Language | Source files | Components / Classes | Tests |
-|---|---|---|---|
-| TypeScript | `kebab-case.ts` | `PascalCase.tsx` components, `PascalCase` classes | `<subject>.test.ts` (colocated) |
-| Python | `snake_case.py` | `PascalCase` classes, `snake_case` functions | `test_<subject>.py` (mirrored) |
-| Rust | `snake_case.rs` | `PascalCase` types/traits | `#[cfg(test)] mod tests` or `tests/` |
-| Go | `snake_case.go` | `PascalCase` exported, `camelCase` internal | `<subject>_test.go` (same dir) |
+| Language | Source files | Components / Classes |
+|---|---|---|
+| TypeScript | `kebab-case.ts` | `PascalCase.tsx` components, `PascalCase` classes |
+| Python | `snake_case.py` | `PascalCase` classes, `snake_case` functions |
+| Rust | `snake_case.rs` | `PascalCase` types/traits |
+| Go | `snake_case.go` | `PascalCase` exported, `camelCase` internal |
 
 - **Descriptive over terse:** Use `rate-limiter.ts` (not `rl.ts`) and `parse-config.ts` (not `utils2.ts`).
 - **BANNED names:** `utils.*`, `misc.*`, `helpers.*`, `temp*`, `final*`, `copy*`, or numbered duplicates (`auth2.ts`). Split by specific responsibility.
@@ -51,4 +66,5 @@ src/
 
 - Every `tasks.yaml` acceptance list MUST include $\ge 1$ objectively verifiable check (exit code or observable output).
 - The verifier runs `archgen_plan{action:'verify'}` and audits plans against this file; violations trigger `ISSUES`.
+- The plan must declare both trees: `architecture.yaml`'s `structure:` lists the source tree AND the test tree, and every task that owns source owns the mirrored test path.
 - Workers receive this file path in their prompt contract and are strictly bound by it.