atlas-project-harness 0.2.0-beta.2 → 0.2.0-beta.21

package/apply/reference.md

@@ -2,6 +2,7 @@
 
 > 本环为 atlas 独立 skill `atlas-apply` 的执行契约，位于 `.atlas/apply/reference.md`。
 > 执行前先读共享契约：`.atlas/shared/global-rules.md`、`stack-profile.md`、`single-source.md`、`layout.md`。
+> 路径约定：本文 `product/` 均为**默认资产根**示例；实际按项目根 `atlas.config.yaml` 的 `layout.assets_root` 解析（见 `shared/layout.md` §1.1）。
 > 本环**跨四环**，是 atlas 里唯一的编排件：它只做「按需求跨环增量」与「按序全量」两件事，环内逻辑一律引用各环自己的契约，不在此复制正文。
 
 ## 0. 一句话
@@ -52,7 +53,7 @@
 
 ## 3. 参与环与顺序
 
-`apply <需求ID>` 按 **`prd → e2e`** 顺序处理；`structure` **不参与**该增量（它是 apply 的**输入**，不是产出——实然事实在实现后由 `after_finish` hook 与 `trellis-update-spec` 维护）。
+`apply <需求ID>` 按 **`prd → e2e`** 顺序处理；`structure` **不参与**该增量（它是 apply 的**输入**，不是产出——实然事实在实现后由 `after_archive` hook 与 `trellis-update-spec` 维护）。
 
 **唯一例外（有界）**：若本次 PRD 定稿**改变了域清单**（合并 / 拆分 / 改名），在 `prd` 之后追加一次 structure **re-key**（按 `rings/structure/reference.md` §2.2：按最终域重排 `.trellis/spec/structure/{current,legacy}/<domain>/` 目录并回写 `_meta.json.domains` / `tour.md`，**不重读代码**）。除该情形外，apply 不写结构事实。
 
@@ -70,13 +71,14 @@
 2. **这次是否需要人来确认应然 UI / 流程**？**是** ⇒ `prd` 六件套（用户流程 / 状态机 / 字段 / 文案 / 异常）落细 **+ 派生「用户旅程走查」并取得用户确认（`rings/prd/reference.md` §4·八；确认前不得进 `e2e` 环）**；应然 UI 的 testid 应然随用例分片产出（E1：原型环已移除）。
 3. **这次是否需要可重复的验收**（超出 lint / test / typecheck 的能力）？**是** ⇒ E2E 环参与。
 
-- **三问全否 ⇒ 只走 `structure` + Trellis**：atlas 三环记 `不适用`，报告里必须留一行 `本需求判定：纯加法 / 不启用三环` + 依据。**这是一条合法路径，不是绕过工作流**——结构事实仍由 `after_finish` hook 保鲜，实现任务照旧拿到路径注入的事实。
+- **三问全否 ⇒ 只走 `structure` + Trellis**：atlas 三环记 `不适用`，报告里必须留一行 `本需求判定：纯加法 / 不启用三环` + 依据。**这是一条合法路径，不是绕过工作流**——结构事实仍由 `after_archive` hook 保鲜，实现任务照旧拿到路径注入的事实。
 - **`prd` 不再恒参与**（原口径：任何需求至少在域级 PRD / 追溯总表留一条）。它在**资产为空的旧项目**上等于「第一个小需求就要写全套项目级 PRD」——成本炸弹，而且与 §2 输入表（要求资产已存在）自相矛盾。改为按上面的门判定；若判定「本需求不改任何应然资产」（纯内部重构且不影响产品定义），apply 报告 `no-op` 并写明依据，**不**强改资产。
 - **两条报告口径**并列**，可同段共存**（2026-09-27 补，`3509 §B91`）：① 三问全否 ⇒ 写 `本需求判定：纯加法 / 不启用三环` + 依据；② 本需求不改任何应然资产 ⇒ 写 `no-op` + 依据。一个需求可以**两条同时命中**（如「新增一个与产品无关的通用工具函数」：既三问全否，又不碰任何应然资产）——此种情形**两行都写**，不择一、也无优先序。
 - **门是语义判断，机器判不了**（与 `§8 末注` 同源）：所以要求把**判定 + 依据**写进 `atlas-apply.md`，让复核者一眼看出它有没有偷懒。
 - **E2E 首跑取证兜底（2026-10-16，`RFC-20261015-02` / issue #11）**：第 3 问判「是」且 `e2e.app_login` 仍未声明 ⇒ 向用户**追问一次**（`real` 四值 / `mode: none` / `fabricated` + `storage_key`，三选一必须显式），落 `product/stack-profile.yaml` 后再进 e2e 环。追问是 UX 加速器，不是判据——机器判据是生成器 `not_ready`（升档 = 下一次真跑准备日，`shared/gates.md`「E2E 真跑」行）；adopt 开户已问过（同批「靶场接入取证」）的项目此处自然不触发。
 - **环间人工门（E1 起；2026-09-29 重议 = `3507 AQ`，B124 结论）**：两道人侧门——① **走查单确认门（实现前，硬）**：改变应然 UI 的需求，域级 PRD 的「用户旅程走查」节须用户显式确认（节首 `已确认：<日期>`；`rings/prd/reference.md` §4·八，确认前对照 `product/design.md`（存在时）视觉方向，`3507 BE`），确认前 **`apply` 不得进 `e2e` 环**；② **验收走查门（收口前）**：该域 E2E 在真实应用全 green 后，用户按域级 PRD 功能清单逐条在真实应用上过一遍（可用 + 符合已确认走查单），确认后才算域收口；不符 ⇒ 差异登记且域不收口；真实应用不可用 ⇒ 与 E2E 同为 `blocked` 显式带原因（`rings/e2e/reference.md` §5.4 末）。`e2e` 用例另走独立审查门（`rings/e2e/reference.md` §12）+ 首跑分类协议（同文件 §5.4）。原型增量人工 review 门已随环退役（`3508 §92`）。
-- 结构事实的**实现后**回写不属于 apply：由 `after_finish` hook（`refresh_structure.py`，事实区）与 Finish 的 `trellis-update-spec`（语义区）负责（D38）。
+- **走查单确认门的机器面（2026-10-23，`RFC-20261022-01` M1）**：`validators/validate_walkthrough.py` 读本报告（`atlas-apply.md`）第 2 问**已写下**的判定，与 `product/prd/<domain>-prd.md` 的 `> 已确认：YYYY-MM-DD` 行对账。因此报告里第 2 问的答句必须写成「是 / 否」开头；受影响域以报告内对 `product/prd/<domain>-prd.md` 的路径引用为准（解析不到 ⇒ WARN 要求人工核对）。本器只判「写下的『是』与确认行的对账」，不判三问语义对错（那仍归人）。
+- 结构事实的**实现后**回写不属于 apply：由 `after_archive` hook（`refresh_structure.py`，事实区）与 Finish 的 `trellis-update-spec`（语义区）负责（D38）。
 
 `all` 模式的顺序固定为 **`structure → prd → e2e`**（含 structure 全量）。
 
@@ -194,6 +196,7 @@ apply 只对**本次受影响集合**落笔，**不整文件覆盖**任何项目
 
 - **单写者表面（硬）**：每个共享文件在任一时刻**只允许一个在办任务**持有写权。
 - **声明与分派**：并发前，每个任务必须**声明自己要写哪些项目级文件**；由用户 / 编排者按 `one writer per file` 分派；冲突时**停下报告**，不得抢占（实测第三次才守住，`3508 §55 一`）。
+- **claim 钩子（2026-10-23，`RFC-20261022-01` M3）**：共享文件动手前 `python3 .atlas/scripts/write_claim.py take --file <路径> --task <需求ID>`，收口时 `release --file <路径>`。每 claim 一个原子文件（`.atlas/runs/write-claims/<hash>.json`，`O_CREAT|O_EXCL`）⇒ 并发 take 同一文件时后者**直接退出非零并指名在办任务**；未释放的 claim 由 `atlas_check` 的 `写面残留` 行 WARN 点名。**降级路径**：旧装配无此命令 ⇒ 纪律照旧（本钩子的主语义是「有命令则机器判」，安全性不押在降级上）。claims 是运行态，`.atlas/` 不入库 ⇒ 不进 git 历史；`validate_e2e_index` 的事后兜底保留不撤。
 - **降串行度的建议（非硬）**：索引类表面可**按用例 ID 分区**（或拆成每页一份的反向索引）；但反向视图现在是**生成**的（`single-source` §2），所以首选是「一次只让一个任务改主表」。
 - **不属本节**：需求级文件（`.trellis/tasks/**`）天然一任务一份，无需仲裁。
 

package/bin/atlas.js

@@ -2,6 +2,7 @@
 const { spawnSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const readline = require('readline');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const args = process.argv.slice(2);
@@ -27,6 +28,7 @@ Atlas — 践行 Project Harness 的全流程 AI 编程工作流治理引擎
 示例:
   atlas init                  # 在当前项目初始化装配
   atlas init --target /path   # 在指定项目初始化装配
+  atlas init --assets-root docs  # 首次装配指定项目级资产根（默认 product）
   atlas update                # 刷新当前项目的工程线束与资产
   atlas update --dry-run      # 预览项目更新改动
   atlas upgrade               # 升级全局 CLI 至最新发布版
@@ -41,7 +43,7 @@ switch (command) {
   case 'init': {
     const installScript = path.join(PKG_ROOT, 'install.sh');
     const passthroughArgs = args.slice(1);
-    
+
     // 如果没有指定 --target，默认使用当前工作目录
     let hasTarget = false;
     let targetDir = process.cwd();
@@ -52,36 +54,72 @@ switch (command) {
         break;
       }
     }
-    const finalArgs = hasTarget ? passthroughArgs : ['--target', targetDir, ...passthroughArgs];
-    
-    // Trellis 环境检测与自动初始化引导
-    const trellisDir = path.join(targetDir, '.trellis');
-    if (!fs.existsSync(trellisDir)) {
-      const hasTrellis = spawnSync('which', ['trellis']).status === 0;
-      if (hasTrellis) {
-        console.log('\n[Atlas] 检测到目标项目尚未初始化 Trellis (.trellis/ 缺失)。');
-        console.log('[Atlas] 正在自动运行 trellis init 初始化状态机骨架...');
-        const initRes = spawnSync('trellis', ['init'], {
-          cwd: targetDir,
-          stdio: 'inherit',
-          env: process.env,
-        });
-        if (initRes.status !== 0) {
-          console.warn('[Atlas] ⚠️ 警告: trellis init 执行异常，继续执行 Atlas 装配...');
+
+    const hasAssetsRoot = passthroughArgs.includes('--assets-root');
+    const hasConfig = fs.existsSync(path.join(targetDir, 'atlas.config.yaml'));
+    const hasAtlas = fs.existsSync(path.join(targetDir, '.atlas'));
+    const shouldPrompt = !hasAssetsRoot && !hasConfig && !hasAtlas
+      && process.stdin.isTTY && process.stdout.isTTY;
+
+    function runInstall(extraArgs) {
+      const baseArgs = hasTarget ? passthroughArgs : ['--target', targetDir, ...passthroughArgs];
+      const finalArgs = [...baseArgs, ...extraArgs];
+
+      // Trellis 环境检测与自动初始化引导
+      const trellisDir = path.join(targetDir, '.trellis');
+      if (!fs.existsSync(trellisDir)) {
+        const hasTrellis = spawnSync('which', ['trellis']).status === 0;
+        if (hasTrellis) {
+          console.log('\n[Atlas] 检测到目标项目尚未初始化 Trellis (.trellis/ 缺失)。');
+          console.log('[Atlas] 正在自动运行 trellis init 初始化状态机骨架...');
+          const initRes = spawnSync('trellis', ['init'], {
+            cwd: targetDir,
+            stdio: 'inherit',
+            env: process.env,
+          });
+          if (initRes.status !== 0) {
+            console.warn('[Atlas] ⚠️ 警告: trellis init 执行异常，继续执行 Atlas 装配...');
+          }
+        } else {
+          console.warn('\n[Atlas] ⚠️ 提示: 未检测到 Trellis CLI。');
+          console.warn('[Atlas] Atlas 需求级执行依赖 Trellis，建议稍后安装:');
+          console.warn('        npm install -g @mindfoldhq/trellis\n');
         }
-      } else {
-        console.warn('\n[Atlas] ⚠️ 提示: 未检测到 Trellis CLI。');
-        console.warn('[Atlas] Atlas 需求级执行依赖 Trellis，建议稍后安装:');
-        console.warn('        npm install -g @mindfoldhq/trellis\n');
       }
+
+      const res = spawnSync('bash', [installScript, ...finalArgs], {
+        stdio: 'inherit',
+        env: process.env,
+      });
+      process.exit(res.status || 0);
     }
 
-    const res = spawnSync('bash', [installScript, ...finalArgs], {
-      stdio: 'inherit',
-      env: process.env,
-    });
+    if (shouldPrompt) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(
+        '\nAtlas 项目级资产根目录（PRD / E2E / ADR 等）[product]: ',
+        (answer) => {
+          rl.close();
+          const value = (answer || '').trim() || 'product';
+          const validation = spawnSync(
+            'python3',
+            [path.join(PKG_ROOT, '_support', 'layout.py'),
+             '--root', targetDir, '--validate-value', 'assets_root', value],
+            { encoding: 'utf8' },
+          );
+          if (validation.status !== 0) {
+            console.error('[Atlas] 无效资产根：' + (validation.stderr || '').trim());
+            process.exit(2);
+          }
+          console.log('[Atlas] 资产根 = ' + value
+            + '（Atlas 资产会放在此目录；已有文件不会被覆盖）');
+          runInstall(['--assets-root', value]);
+        },
+      );
+      break;
+    }
 
-    process.exit(res.status || 0);
+    runInstall([]);
     break;
   }
 
@@ -107,7 +145,7 @@ Atlas update — 安全刷新当前项目中的 .atlas/ 工程线束与平台 Sk
 说明:
   atlas update 会安全刷新当前项目中的 .atlas/ 契约、校验器、模板、脚本以及各平台
   Skills 瘦桩，并重新对账生成 .atlas/VERSION 装配版本戳。
-  项目原有的业务资产（product/stack-profile.yaml、product/e2e/cases/ 等）将严格保留。
+  项目原有的业务资产（默认资产根下的 stack-profile.yaml、e2e/cases/ 等）将严格保留。
 `);
       process.exit(0);
     }
@@ -300,7 +338,7 @@ Atlas upgrade — 自动拉取 npm 最新全局包升级全局 Atlas CLI
   1. 在 Agent 会话中直接输入大白话，例如:
      - "帮我把这个项目接入 Atlas 工作流" (意图 = adopt 存量开户)
      - "跑一下三环全量构建，建立应然基线" (意图 = all 全量构建)
-     注意「装配 ≠ 开户」：开户产物是 product/prd/ 与 .trellis/spec/structure/ 的内容。
+     注意「装配 ≠ 开户」：开户产物是资产根/prd/ 与 .trellis/spec/structure/ 的内容。
      若 Agent 因 .atlas/ 已存在而回你「已接入」，改用下面第 2 种（确定性入口）。
   2. 或在支持 Slash Command 的平台中唤起技能:
      /atlas-apply ${sub}

package/extensions/pi.ts

@@ -16,15 +16,16 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 
 const EXTENSION_NAME = "atlasharness";
 
 /**
  * 开户态（2026-10-15 补）：**装配 ≠ 开户**。
  *
- * `atlas init` 只装配线束（`.atlas/` / `product/` 骨架 / AGENTS.md 指针 / Trellis 接线）；
+ * `atlas init` 只装配线束（`.atlas/` / 资产根骨架（默认 `product/`） / AGENTS.md 指针 / Trellis 接线）；
  * 「开户」另有产物，且只有该轮真产出才算数：
- *   * `product/prd/prd.md`                 —— 全局 PRD（`adopt` 最小必填集必产）
+ *   * `<资产根>/prd/prd.md`                 —— 全局 PRD（`adopt` 最小必填集必产；默认 `product/prd/prd.md`）
  *   * `.trellis/spec/structure/_meta.json` —— 域清单（`structure` 全量的机器视图）
  * 骨架期这两个文件都不存在（目录里只有 `.gitkeep`）⇒ **不能拿「目录非空」当信号**。
  * 「半开通」（只有其一）是常态：开户按产物存在与否**断点续跑**（`apply/reference.md` §1）。
@@ -43,15 +44,39 @@ interface AtlasProjectStatus {
   hasStackProfile: boolean;
   onboarding: Onboarding;
   version?: string;
+  stackProfileRel: string;
+  prdRel: string;
+  layoutNote?: string;
+}
+
+function layoutValue(cwd: string, key: string, absolute: boolean): string | null {
+  const script = join(cwd, ".atlas", "_support", "layout.py");
+  if (!existsSync(script)) return null;
+  const flag = absolute ? "--print-abs" : "--print";
+  const res = spawnSync("python3", [script, "--root", cwd, flag, key], { encoding: "utf8" });
+  if (res.status !== 0) return null;
+  const out = (res.stdout || "").trim();
+  return out || null;
 }
 
 function detectAtlasStatus(cwd: string): AtlasProjectStatus {
   const hasAtlasDir = existsSync(join(cwd, ".atlas"));
-  const hasStackProfile = existsSync(join(cwd, "product", "stack-profile.yaml"));
+  const hasConfig = existsSync(join(cwd, "atlas.config.yaml"));
+  const stackProfileAbs = layoutValue(cwd, "stack_profile", true)
+    ?? join(cwd, "product", "stack-profile.yaml");
+  const stackProfileRel = layoutValue(cwd, "stack_profile", false)
+    ?? "product/stack-profile.yaml";
+  const prdAbs = layoutValue(cwd, "prd", true) ?? join(cwd, "product", "prd");
+  const prdRel = layoutValue(cwd, "prd", false) ?? "product/prd";
+  const hasStackProfile = existsSync(stackProfileAbs);
   const hasTrellis = existsSync(join(cwd, ".trellis"));
+  const layoutReady = !hasConfig || layoutValue(cwd, "assets_root", false) !== null;
+  const layoutNote = hasConfig && !layoutReady
+    ? "自定义布局未解析（python3 缺席 / 旧装配 / 配置非法），按默认 product 判定"
+    : undefined;
 
   // 开户产物 = 上面 Onboarding 注里点名的两个文件
-  const hasPrd = existsSync(join(cwd, "product", "prd", "prd.md"));
+  const hasPrd = existsSync(join(prdAbs, "prd.md"));
   const hasStructureMeta = existsSync(
     join(cwd, ".trellis", "spec", "structure", "_meta.json"),
   );
@@ -74,6 +99,9 @@ function detectAtlasStatus(cwd: string): AtlasProjectStatus {
     hasStackProfile,
     onboarding,
     version,
+    stackProfileRel,
+    prdRel,
+    layoutNote,
   };
 }
 
@@ -106,14 +134,17 @@ export default function (pi: ExtensionAPI) {
             `  - Atlas 已装配: ${status.isAtlasProject ? `是 (版本: ${status.version || "dev"})` : "否"}`,
             `  - 开户态: ${ONBOARDING_LABEL[status.onboarding]}`,
             `  - Trellis 接入: ${status.hasTrellis ? "已接入" : "未检测到 (.trellis/ 缺失)"}`,
-            `  - 技术栈画像: ${status.hasStackProfile ? "已配置 (product/stack-profile.yaml)" : "未配置"}`,
+            `  - 技术栈画像: ${status.hasStackProfile ? `已配置 (${status.stackProfileRel})` : "未配置"}`,
           ];
+          if (status.layoutNote) {
+            lines.push(`  - 布局: ${status.layoutNote}`);
+          }
           if (!status.isAtlasProject) {
             lines.push(``, `提示: 当前项目尚未接入 Atlas。使用 \`/atlas init\` 即可一键装配。`);
           } else if (status.onboarding !== "done") {
             lines.push(
               ``,
-              `提示: **装配 ≠ 开户** —— 开户产物 = product/prd/prd.md 与 .trellis/spec/structure/_meta.json。`,
+              `提示: **装配 ≠ 开户** —— 开户产物 = ${status.prdRel}/prd.md 与 .trellis/spec/structure/_meta.json。`,
               `      现在${ONBOARDING_LABEL[status.onboarding]}；用户说「把项目接入 Atlas 工作流」时`,
               `      直接唤起技能 \`/atlas-apply adopt\`（存量：只登记既有基线 + 开户最小集，`,
               `      不重写老 PRD/用例）。开户按产物存在与否断点续跑，不吃掉已完成的部分。`,
@@ -216,11 +247,11 @@ export default function (pi: ExtensionAPI) {
         `\n\n# Atlas: 已装配但尚未开户（装配 ≠ 开户）\n` +
         `This project has the Atlas harness **assembled** but is **not onboarded** ` +
         `(onboarding state: ${status.onboarding}). Onboarding artifacts are ` +
-        `\`product/prd/prd.md\` and \`.trellis/spec/structure/_meta.json\` — both still missing.\n` +
+        `\`${status.prdRel}/prd.md\` and \`.trellis/spec/structure/_meta.json\` — both still missing.\n` +
         `When the user asks to 「把项目接入 Atlas 工作流」/「接入 Atlas」, run the skill ` +
         `\`atlas-apply adopt\` (existing project: register the baseline + minimal PRD only; ` +
         `do NOT rewrite old PRDs or invent legacy test cases). **Do not** conclude "already ` +
-        `onboarded" just because \`.atlas/\` or \`product/\` exist, and do not ask the user ` +
+        `onboarded" just because \`.atlas/\` or the asset root exist, and do not ask the user ` +
         `whether they already onboarded. Onboarding resumes by artifact presence.\n`;
       return { systemPrompt: prompt + onboardingNotice };
     }

package/install.sh

@@ -4,26 +4,30 @@
 #
 # 用法：
 #   bash install.sh [--target <项目根>] [--update] [--force] [--dry-run] [--no-skill] [--no-patch] [--no-wiring]
+#                   [--assets-root <dir>] [--adr-dir <dir>]
 #
 # 装配行为：
 #   1. 整包装配到 <目标>/.atlas/（shared / rings / apply / templates / adapters /
-#      validators / patches / tests）。.atlas/ 属包产物，默认刷新。
+#      validators / patches / tests / _support / extensions）。.atlas/ 属包产物：白名单子目录默认刷新，
+#      `.atlas/runs/`（运行态：E2E 汇总 / check 事件 / write-claims）保留不删。
 #   2. 每个 skills/atlas-*/ 以一个瘦桩 SKILL.md 装到各平台 skill 目录。
 #   3. 清理历史遗留的单入口 skill（<平台>/skills/atlas）。
-#   4. 建 product/ 骨架（已有内容永不覆盖）。
+#   4. 建资产根骨架（默认 product/；已有内容永不覆盖）。
 #   5. 应用 .trellis/workflow.md 的 Plan 挂载补丁（atlas apply；锚点幂等，
 #      用 --no-patch 跳过）。
-#   6. 项目接线：AGENTS.md 的 atlas 指针段 + .trellis/config.yaml 的 after_finish
+#   6. 项目接线：AGENTS.md 的 atlas 指针段 + .trellis/config.yaml 的 after_archive
 #      hook（幂等，用 --no-wiring 跳过）。
 #      第 5、6 步属 global-rules §7 确认门动作，由本次显式安装触发。
 #
 # 模式：
 #   --update: 刷新已有项目的 .atlas/ 资产与平台 Skills 瘦桩（要求目标已初始化 .atlas/）。
+#   --assets-root / --adr-dir: 首次安装选择项目级资产根（默认 product/）与可选 ADR 根；
+#      写入项目根 atlas.config.yaml（git 跟踪）。--update 只读配置，不重新选择。
 #   --update 的触点守卫：已跟踪触点存在未提交改动 ⇒ 拒（--force 越过）；触点整目录
 #   未跟踪（如 .atlas/ 不入库）⇒ WARN 放行、不消费 --force（覆盖自负，先回灌更稳）。
 #
 # 幂等：.atlas/ 与 skill 瘦桩默认刷新（属包下发物，用 --no-skill 跳过 skill）；
-#       product/ 下的既有内容永不覆盖；workflow.md 补丁只做锚点插入、重跑即恢复；
+#       资产根下的既有内容永不覆盖；workflow.md 补丁只做锚点插入、重跑即恢复；
 #       AGENTS.md 指针段与 config.yaml hook 就地更新、重跑即恢复。
 #
 set -euo pipefail
@@ -37,6 +41,8 @@ DRY_RUN=0
 INSTALL_SKILL=1
 INSTALL_PATCH=1
 INSTALL_WIRING=1
+ASSETS_ROOT_ARG=""
+ADR_DIR_ARG=""
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -47,8 +53,10 @@ while [ $# -gt 0 ]; do
     --no-skill) INSTALL_SKILL=0; shift ;;
     --no-patch) INSTALL_PATCH=0; shift ;;
     --no-wiring) INSTALL_WIRING=0; shift ;;
+    --assets-root) ASSETS_ROOT_ARG="${2:-}"; shift 2 ;;
+    --adr-dir) ADR_DIR_ARG="${2:-}"; shift 2 ;;
     -h|--help)
-      sed -n '2,22p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+      sed -n '2,26p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
       exit 0 ;;
     *) echo "未知参数: $1" >&2; exit 2 ;;
   esac
@@ -193,6 +201,127 @@ if [ "${#PLATFORM_DIRS[@]}" -eq 0 ]; then
   PLATFORM_DIRS=(".agents/skills")
 fi
 
+# ---------------------------------------------------------------- 布局配置
+
+# 布局锚点 = 项目根 atlas.config.yaml（git 跟踪）；首次安装由本脚本写，--update 只读。
+# 配置缺失 ⇒ 默认 product/（存量项目零变化）。
+CONFIG_FILE="$TARGET/atlas.config.yaml"
+LAYOUT_PY="$SCRIPT_DIR/_support/layout.py"
+if [ ! -f "$LAYOUT_PY" ]; then
+  say "错误：源包缺少 _support/layout.py，无法解析项目级资产根。"
+  exit 1
+fi
+
+layout_print() { python3 "$LAYOUT_PY" --root "$TARGET" --print "$1"; }
+layout_validate() { python3 "$LAYOUT_PY" --root "$TARGET" --validate >/dev/null; }
+
+if [ "$IS_UPDATE" -eq 1 ]; then
+  if ! layout_validate; then
+    say "错误：布局配置非法（${CONFIG_FILE}）；先修正再 update。"
+    python3 "$LAYOUT_PY" --root "$TARGET" --validate || true
+    exit 2
+  fi
+  ASSETS_ROOT="$(layout_print assets_root)" || exit 2
+  ADR_DIR_REL="$(layout_print adr)" || exit 2
+  if [ -n "$ASSETS_ROOT_ARG" ] && [ "$ASSETS_ROOT_ARG" != "$ASSETS_ROOT" ]; then
+    say "错误：--assets-root=$ASSETS_ROOT_ARG 与现有配置（${ASSETS_ROOT}）不一致；update 不换根。"
+    exit 2
+  fi
+  if [ -n "$ADR_DIR_ARG" ] && [ "$ADR_DIR_ARG" != "$ADR_DIR_REL" ]; then
+    say "错误：--adr-dir=$ADR_DIR_ARG 与现有配置（${ADR_DIR_REL}）不一致；update 不换根。"
+    exit 2
+  fi
+elif [ -f "$CONFIG_FILE" ]; then
+  if ! layout_validate; then
+    say "错误：布局配置非法（${CONFIG_FILE}）。"
+    python3 "$LAYOUT_PY" --root "$TARGET" --validate || true
+    exit 2
+  fi
+  ASSETS_ROOT="$(layout_print assets_root)" || exit 2
+  ADR_DIR_REL="$(layout_print adr)" || exit 2
+  if [ -n "$ASSETS_ROOT_ARG" ] && [ "$ASSETS_ROOT_ARG" != "$ASSETS_ROOT" ]; then
+    say "错误：--assets-root=$ASSETS_ROOT_ARG 与现有配置（${ASSETS_ROOT}）不一致。"
+    exit 2
+  fi
+  if [ -n "$ADR_DIR_ARG" ] && [ "$ADR_DIR_ARG" != "$ADR_DIR_REL" ]; then
+    say "错误：--adr-dir=$ADR_DIR_ARG 与现有配置（${ADR_DIR_REL}）不一致。"
+    exit 2
+  fi
+else
+  NEW_ASSETS_ROOT="${ASSETS_ROOT_ARG:-product}"
+  NEW_ADR_DIR="${ADR_DIR_ARG:-}"
+  python3 "$LAYOUT_PY" --root "$TARGET" --validate-value assets_root "$NEW_ASSETS_ROOT" || exit 2
+  if [ -n "$NEW_ADR_DIR" ]; then
+    python3 "$LAYOUT_PY" --root "$TARGET" --validate-value adr "$NEW_ADR_DIR" || exit 2
+  fi
+  if [ "$NEW_ASSETS_ROOT" != "product" ]; then
+    for p in stack-profile.yaml prd e2e adr design.md reviews atlas-reports; do
+      if [ -e "$TARGET/product/$p" ]; then
+        say "错误：所选资产根 $NEW_ASSETS_ROOT 不是默认 product，但 product/$p 已存在（双根风险）。"
+        say "      先手工迁移既有资产到 $NEW_ASSETS_ROOT/，或明确改用 --assets-root product。"
+        exit 2
+      fi
+    done
+  fi
+  if [ "$DRY_RUN" -eq 1 ]; then
+    say "      [dry-run] + atlas.config.yaml（assets_root: ${NEW_ASSETS_ROOT}）"
+    [ -n "$NEW_ADR_DIR" ] && say "                      adr: $NEW_ADR_DIR"
+    ASSETS_ROOT="$NEW_ASSETS_ROOT"
+    ADR_DIR_REL="${NEW_ADR_DIR:-$ASSETS_ROOT/adr}"
+    STACK_PROFILE_REL="$ASSETS_ROOT/stack-profile.yaml"
+    PRD_DIR_REL="$ASSETS_ROOT/prd"
+    E2E_DIR_REL="$ASSETS_ROOT/e2e"
+    E2E_CASES_REL="$E2E_DIR_REL/cases"
+    E2E_SCRIPTS_REL="$E2E_DIR_REL/scripts"
+    E2E_INDEX_REL="$E2E_DIR_REL/e2e-index.md"
+    E2E_REVIEWS_REL="$E2E_DIR_REL/reviews"
+    CONSOLE_LEDGER_REL="$E2E_REVIEWS_REL/console/events.jsonl"
+  else
+    WRITE_ARGS=(--root "$TARGET" --write --assets-root "$NEW_ASSETS_ROOT")
+    [ -n "$NEW_ADR_DIR" ] && WRITE_ARGS+=(--adr "$NEW_ADR_DIR")
+    python3 "$LAYOUT_PY" "${WRITE_ARGS[@]}" >/dev/null || exit 2
+    say "      + atlas.config.yaml（assets_root: ${NEW_ASSETS_ROOT}）"
+    [ -n "$NEW_ADR_DIR" ] && say "                      adr: $NEW_ADR_DIR"
+    ASSETS_ROOT="$(layout_print assets_root)" || exit 2
+    ADR_DIR_REL="$(layout_print adr)" || exit 2
+    STACK_PROFILE_REL="$(layout_print stack_profile)" || exit 2
+    PRD_DIR_REL="$(layout_print prd)" || exit 2
+    E2E_DIR_REL="$(layout_print e2e)" || exit 2
+    E2E_CASES_REL="$(layout_print e2e_cases)" || exit 2
+    E2E_SCRIPTS_REL="$(layout_print e2e_scripts)" || exit 2
+    E2E_INDEX_REL="$(layout_print e2e_index)" || exit 2
+    E2E_REVIEWS_REL="$(layout_print e2e_reviews)" || exit 2
+    CONSOLE_LEDGER_REL="$(layout_print console_ledger)" || exit 2
+  fi
+fi
+
+if [ "$IS_UPDATE" -eq 0 ] && [ -f "$CONFIG_FILE" ]; then
+  STACK_PROFILE_REL="$(layout_print stack_profile)" || exit 2
+  PRD_DIR_REL="$(layout_print prd)" || exit 2
+  E2E_DIR_REL="$(layout_print e2e)" || exit 2
+  E2E_CASES_REL="$(layout_print e2e_cases)" || exit 2
+  E2E_SCRIPTS_REL="$(layout_print e2e_scripts)" || exit 2
+  E2E_INDEX_REL="$(layout_print e2e_index)" || exit 2
+  E2E_REVIEWS_REL="$(layout_print e2e_reviews)" || exit 2
+  CONSOLE_LEDGER_REL="$(layout_print console_ledger)" || exit 2
+fi
+if [ "$IS_UPDATE" -eq 1 ]; then
+  STACK_PROFILE_REL="$(layout_print stack_profile)" || exit 2
+  PRD_DIR_REL="$(layout_print prd)" || exit 2
+  E2E_DIR_REL="$(layout_print e2e)" || exit 2
+  E2E_CASES_REL="$(layout_print e2e_cases)" || exit 2
+  E2E_SCRIPTS_REL="$(layout_print e2e_scripts)" || exit 2
+  E2E_INDEX_REL="$(layout_print e2e_index)" || exit 2
+  E2E_REVIEWS_REL="$(layout_print e2e_reviews)" || exit 2
+  CONSOLE_LEDGER_REL="$(layout_print console_ledger)" || exit 2
+fi
+
+STACK_PROFILE="$TARGET/$STACK_PROFILE_REL"
+E2E_CASES_DIR="$TARGET/$E2E_CASES_REL"
+say "  资产根   : $ASSETS_ROOT"
+say "  ADR 根   : $ADR_DIR_REL"
+say ""
+
 # ---------------------------------------------------------------- 1. 整包 → .atlas/
 
 say "[1/6] 装配 atlas 包到 .atlas/"
@@ -278,17 +407,27 @@ say "[4/6] 建立骨架"
 for d in \
   ".trellis/spec/structure/domains" \
   ".trellis/spec/structure/global" \
-  "product/e2e/cases"
+  "$E2E_CASES_REL"
 do
   run mkdir -p "$TARGET/$d"
   [ -f "$TARGET/$d/.gitkeep" ] || run touch "$TARGET/$d/.gitkeep"
 done
 
-if [ -f "$TARGET/product/stack-profile.yaml" ]; then
-  say "      = product/stack-profile.yaml 已存在，保留"
+if [ -f "$STACK_PROFILE" ]; then
+  say "      = $STACK_PROFILE_REL 已存在，保留"
 else
-  run cp "$SCRIPT_DIR/templates/stack-profile.yaml" "$TARGET/product/stack-profile.yaml"
-  say "      + product/stack-profile.yaml（草稿，需人工确认）"
+  if [ "$DRY_RUN" -eq 1 ]; then
+    say "      [dry-run] + ${STACK_PROFILE_REL}（由模板按资产根渲染）"
+  else
+    mkdir -p "$(dirname "$STACK_PROFILE")"
+    python3 - "$SCRIPT_DIR/templates/stack-profile.yaml" "$STACK_PROFILE" "$ASSETS_ROOT" <<'PY'
+import sys
+src, dst, assets_root = sys.argv[1], sys.argv[2], sys.argv[3]
+text = open(src, encoding="utf-8").read().replace("{{ASSETS_ROOT}}", assets_root)
+open(dst, "w", encoding="utf-8").write(text)
+PY
+    say "      + ${STACK_PROFILE_REL}（草稿，需人工确认）"
+  fi
 fi
 
 # ---------------------------------------------------------------- 5. Trellis workflow 补丁（遍历 patches/*/）
@@ -344,13 +483,13 @@ if [ ! -f "$WIRING_DIR/apply-wiring.py" ] && [ -f "$SCRIPT_DIR/patches/project-w
   WIRING_DIR="$SCRIPT_DIR/patches/project-wiring"
 fi
 if [ "$INSTALL_WIRING" -eq 1 ]; then
-  say "[6/6] 项目接线（AGENTS.md 指针 + after_finish hook）"
+  say "[6/6] 项目接线（AGENTS.md 指针 + after_archive hook）"
   if [ -f "$WIRING_DIR/apply-wiring.py" ]; then
     if [ "$DRY_RUN" -eq 1 ]; then
       run python3 "$WIRING_DIR/apply-wiring.py" --target "$TARGET"
     else
       if python3 "$WIRING_DIR/apply-wiring.py" --target "$TARGET" --apply; then
-        say "      -> AGENTS.md（atlas 指针段）+ .trellis/config.yaml（after_finish hook）"
+        say "      -> AGENTS.md（atlas 指针段）+ .trellis/config.yaml（after_archive hook + session_auto_commit: false）"
       else
         say "      ⚠ 接线存在 error——不阻断装配（见上）。"
       fi
@@ -366,8 +505,8 @@ fi
 
 # profile 声明了 graph.backend ⇒ 探测 cgc（缺 = 显式 WARN，不阻断——可选能力，
 # 图谱消费者运行时按「not_ready / 响亮降级」三态处理；契约见 shared/stack-profile.md §2）。
-if [ -f "$TARGET/product/stack-profile.yaml" ] && [ "$DRY_RUN" -eq 0 ]; then
-  GRAPH_BACKEND="$(python3 - "$TARGET/product/stack-profile.yaml" <<'PY'
+if [ -f "$STACK_PROFILE" ] && [ "$DRY_RUN" -eq 0 ]; then
+  GRAPH_BACKEND="$(python3 - "$STACK_PROFILE" <<'PY'
 import re, sys
 sec = None
 for raw in open(sys.argv[1], encoding="utf-8"):
@@ -427,7 +566,9 @@ check "校验器 validate_testids" "$ATLAS_DEST/validators/validate_testids.py"
 check "校验器 validate_e2e_index" "$ATLAS_DEST/validators/validate_e2e_index.py"
 check "校验器 validate_design_exemptions" "$ATLAS_DEST/validators/validate_design_exemptions.py"
 check "校验器 validate_e2e_mocks" "$ATLAS_DEST/validators/validate_e2e_mocks.py"
+check "校验器 validate_ac_alignment" "$ATLAS_DEST/validators/validate_ac_alignment.py"
 check "校验器 validate_adr" "$ATLAS_DEST/validators/validate_adr.py"
+check "校验器 validate_walkthrough" "$ATLAS_DEST/validators/validate_walkthrough.py"
 check "E2E 脚本生成器" "$ATLAS_DEST/scripts/gen_e2e_scripts.py"
 check "结构事实刷新器" "$ATLAS_DEST/scripts/refresh_structure.py"
 check "testid 薄桩生成器" "$ATLAS_DEST/scripts/gen_testid_stub.py"
@@ -438,25 +579,36 @@ check "E2E 评审控制台" "$ATLAS_DEST/scripts/e2e_console.py"
 check "控制台静态资源" "$ATLAS_DEST/templates/e2e/console/index.html"
 check "适配器脚手架" "$ATLAS_DEST/adapters/_scaffold.py"
 check "适配器指南" "$ATLAS_DEST/adapters/README.md"
+check "AC 提取器注册表" "$ATLAS_DEST/adapters/ac/__init__.py"
+check "AC 提取器（pytest）" "$ATLAS_DEST/adapters/ac/pytest.py"
+check "AC 提取器（Vitest/Jest）" "$ATLAS_DEST/adapters/ac/js.py"
+check "AC 提取器（JUnit 5）" "$ATLAS_DEST/adapters/ac/junit.py"
+check "AC 外部 extractor 运行器" "$ATLAS_DEST/adapters/ac/command.py"
+check "JPA 模型解析器" "$ATLAS_DEST/adapters/_jpa.py"
 check "图谱后端隔离层" "$ATLAS_DEST/adapters/_graph.py"
 check "影响面基准报告器" "$ATLAS_DEST/scripts/impact_report.py"
 check "回灌助手" "$ATLAS_DEST/scripts/backflow.py"
+check "收口派生器" "$ATLAS_DEST/scripts/closeout_derive.py"
+check "写面 claim 仲裁" "$ATLAS_DEST/scripts/write_claim.py"
 check "共享内核（模块加载器）" "$ATLAS_DEST/_support/siblings.py"
 check "共享内核（profile 解析）" "$ATLAS_DEST/_support/stack_profile.py"
 check "共享内核（用例块解析）" "$ATLAS_DEST/_support/case_block.py"
+check "共享内核（手工走查块解析）" "$ATLAS_DEST/_support/manual_block.py"
 check "共享内核（用例 ID 文法）" "$ATLAS_DEST/_support/case_id.py"
 check "共享内核（node 运行器判据）" "$ATLAS_DEST/_support/pw_runner.py"
 check "共享内核（base query 转发）" "$ATLAS_DEST/_support/url_merge.py"
 check "共享内核（审查策略单源）" "$ATLAS_DEST/_support/review_policy.py"
+check "共享内核（布局解析）" "$ATLAS_DEST/_support/layout.py"
+check "共享内核（维度解析）" "$ATLAS_DEST/_support/ac_coverage.py"
 check "pi 宿主扩展" "$ATLAS_DEST/extensions/pi.ts"
 check "结构模板" "$ATLAS_DEST/templates/structure/_meta.json"
 check "PRD 模板" "$ATLAS_DEST/templates/prd/domain.md"
 check "E2E 模板" "$ATLAS_DEST/templates/e2e/e2e-index.md"
 check "ADR 模板" "$ATLAS_DEST/templates/adr/template.md"
 check "审查指引模板" "$ATLAS_DEST/templates/reviews/README.md"
-check "product/stack-profile" "$TARGET/product/stack-profile.yaml"
+check "stack-profile（资产根）" "$STACK_PROFILE"
 check "structure spec 根" "$TARGET/.trellis/spec/structure"
-check "e2e 用例分片目录" "$TARGET/product/e2e/cases"
+check "e2e 用例分片目录" "$E2E_CASES_DIR"
 
 if [ "$INSTALL_PATCH" -eq 1 ] && [ "$DRY_RUN" -ne 1 ] && [ -f "$TARGET/.trellis/workflow.md" ]; then
   if grep -q "atlas:apply:plan-step-1-6" "$TARGET/.trellis/workflow.md"; then
@@ -473,9 +625,9 @@ if [ "$INSTALL_WIRING" -eq 1 ] && [ "$DRY_RUN" -ne 1 ]; then
     say "  [WARN] AGENTS.md atlas 指针段未生效（见 patches/project-wiring/README.md）"
   fi
   if [ -f "$TARGET/.trellis/config.yaml" ] && grep -q "refresh_structure.py" "$TARGET/.trellis/config.yaml"; then
-    say "  [OK]   after_finish hook（refresh_structure）"
+    say "  [OK]   after_archive hook（refresh_structure）"
   else
-    say "  [WARN] after_finish hook 未生效（见 patches/project-wiring/README.md）"
+    say "  [WARN] after_archive hook 未生效（见 patches/project-wiring/README.md）"
   fi
 fi
 
@@ -518,6 +670,14 @@ print(stamp_file(Path(sys.argv[1]), Path(sys.argv[2])))
 PY
 )"; then
     say "  [ok] .atlas/VERSION 装配版本戳（${OUT}）"
+    # RFC-20261023-02 ②（2026-10-23）：装配基线 manifest 必须与戳同点落下——落戳成功而
+    # manifest 缺失 = 逐文件对账面不存在，按装配失败处理（硬错，与 F37 同款理由）。
+    if [ -s "$TARGET/.atlas/MANIFEST.json" ]; then
+      say "  [ok] .atlas/MANIFEST.json 装配基线（逐文件摘要）"
+    else
+      say "  [FAIL] 装配基线 manifest 未落下（.atlas/MANIFEST.json）⇒ 装配态无法逐文件对账。"
+      exit 1
+    fi
   else
     # 硬错而非 WARN（F37，2026-10-15）：落戳失败 = 装配集为空（摘要算不出来）或脚本缺失。
     # 「装配 0 文件」不得被记成一次合法装配，且 WARN 会让后续步骤照常往下走。
@@ -561,6 +721,6 @@ else
   else
     say "（未检测到既有源码：看起来是后者；也可以只说「跑一下三环全量构建，建立应然基线」）"
   fi
-  say "Agent 会先带你核对 product/stack-profile.yaml（origin / apps / role / adapters）"
+  say "Agent 会先带你核对 ${STACK_PROFILE_REL}（origin / apps / role / adapters）"
   say "再落盘；占位符替换前 atlas check 判 FAIL 属预期，不是装坏了。"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas-project-harness",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.21",
   "description": "践行 Project Harness 的全流程 AI 编程工作流治理引擎",
   "bin": {
     "atlas": "bin/atlas.js"