@namewta/speculo 1.0.9 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/.speculo/README.md

@@ -14,7 +14,7 @@
 
 ## 读取顺序
 
-1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。
+1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。嵌套安装时，项目根 `.speculo/` 不是本目录；只有该文件声明的状态根是运行时状态的唯一持久化根，项目根 `.speculo/specdev` 非法。
 2. 从 `../workflows/<workflow>/INDEX.md` 发现 workflow并按需读取其中声明的永久知识；这一步不读取 Work 条目或运行状态。
 3. 用户明确激活 workflow 或 work 后，读取 INDEX 指向的 workflow 根 `README.md`，从其中的 Work 条目选择目标并读取具体入口文件。
 4. 按激活合同读取 `<Path>{roots.state}/{workflow}/status.json</Path>`。SpecDev/Learning 再读取当前 change `.status.json` 与 work 产物。Ops schema v3 读取 hosts/projects/deployments/allocations/bindings/releases 及对应运行记录，不创建 `changes/`。

package/template/canonical/canonical-specdev-goal-plan.md

@@ -1921,7 +1921,7 @@ node "${ZIP_SCRIPT}" "${RETURN_STAGING}" \
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -982,7 +982,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-spec.md

@@ -1072,7 +1072,7 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-tickets.md

@@ -1867,7 +1867,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/canonical/canonical-specdev-wayfinder.md

@@ -650,7 +650,7 @@ resolution: answered
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `workspace.json`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -35,12 +35,16 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 
 ### 1. 解析根目录
 
+创建任何状态目录之前，先从 cwd 向上定位并打开 `<Path>{roots.state}/workspace.json</Path>`，校验 `path_base` 与 `roots.*`。只在解析后的状态根下创建 specdev 目录；禁止在声明的状态根之外新建 `.speculo`。
+
 确认：
 
 - 工作流根可解析为 `<Path>{roots.workflows}/specdev/</Path>`；
-- 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`；
+- 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`，且必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`；
 - 当前用户允许在状态根创建目录和工件。
 
+嵌套安装反例：不得把状态根默认展开成项目根 `.speculo`。项目根 `.speculo/specdev` 非法；init 与 Grill 只写入声明的 `<Path>{roots.state}/specdev/</Path>`。
+
 不得把真实绝对路径写回模板或治理文档；持久化引用继续使用根变量。
 
 ### 2. 探测项目事实

package/template/workflows/specdev/README.md

@@ -4,7 +4,7 @@
 
 ## 运行时根
 
-工作流：`<Path>{roots.workflows}/specdev/</Path>`；状态：`<Path>{roots.state}/specdev/</Path>`。具体路径遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`，不使用内部相对链接、裸文件名或机器绝对路径。
+工作流：`<Path>{roots.workflows}/specdev/</Path>`；状态：`<Path>{roots.state}/specdev/</Path>`。roots 必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`，禁止把状态根默认展开成项目根 `.speculo`。嵌套安装下项目根 `.speculo/specdev` 非法。具体路径遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`，不使用内部相对链接、裸文件名或机器绝对路径。
 
 ## 工件链与权威
 
@@ -24,7 +24,7 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
 
 ## 启动协议
 
-1. 解析 roots，读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；定位相关 entry 后回读必要原文，不默认整读索引。
+1. 先打开 `<Path>{roots.state}/workspace.json</Path>` 解析 roots，再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；定位相关 entry 后回读必要原文，不默认整读索引。不得把状态根默认展开成项目根 `.speculo`；项目根 `.speculo/specdev` 非法。
 2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`；不存在时使用 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。保留已知配置，不重复询问。
 3. 从 `<Path>{roots.state}/specdev/status.json</Path>` 定位用户指定或唯一 active change；多个候选需要真实消歧，无候选按原规则创建。
 4. 读取 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`；恢复、创建或状态修改时加载上述状态细则。child 归属未完成父 Goal 时读取对应父 Map/Plan，不接管或覆盖其 owner。

package/template/workflows/specdev/common/rules/activation-and-memory.md

@@ -4,7 +4,7 @@
 
 ## Locate before read
 
-1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+1. 先打开 `<Path>{roots.state}/workspace.json</Path>`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。

package/template/workflows/specdev/common/rules/path-reference-contract.md

@@ -44,6 +44,8 @@
 
 目录引用必须以 `/` 结束；文件引用不得以 `/` 结束。
 
+嵌套安装反例：项目根 `.speculo/specdev` 不是状态根。change 必须位于 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 或 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
+
 ## 3. 项目代码路径
 
 SpecDev 不假定运行时一定提供项目根变量。Ticket、Evidence、诊断与架构审查中的项目代码路径统一使用项目相对路径，并仍置于 Path 标签中：

package/template/workflows/specdev/common/tools/validate-specdev.mjs

@@ -17,7 +17,7 @@ import {
   statSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { dirname, basename, extname, join, relative, resolve, sep } from "node:path";
+import { dirname, basename, extname, join, relative, resolve, sep, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -262,7 +262,7 @@ function parseScalar(raw) {
   return value;
 }
 
-function findSpecdevConfig(change) {
+function findSpecdevConfigByAncestry(change) {
   let current = resolve(change);
   while (true) {
     const candidate = join(current, ".speculo", "specdev", "config.json");
@@ -279,6 +279,149 @@ function findSpecdevConfig(change) {
   }
 }
 
+function uniqueResolved(paths) {
+  const seen = new Set();
+  const result = [];
+  for (const path of paths) {
+    const resolved = resolve(path);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    result.push(resolved);
+  }
+  return result;
+}
+
+function ancestorsOf(start) {
+  const dirs = [];
+  let current = resolve(start);
+  while (true) {
+    dirs.push(current);
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return dirs;
+}
+
+function parseWorkspaceCandidate(filePath, projectRoot) {
+  if (!isFile(filePath)) return null;
+  let data;
+  try {
+    data = JSON.parse(readText(filePath));
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  if (data.schema_version !== 1 || data.path_base !== "project-root") return null;
+  const state = data.roots?.state;
+  if (typeof state !== "string" || !state.trim()) return null;
+  const declared = toPosix(state).replace(/^\.?\//, "").replace(/\/$/, "");
+  if (
+    !declared ||
+    declared.split("/").includes("..") ||
+    isAbsolute(declared) ||
+    ABSOLUTE_MACHINE_PATH_RE.test(declared)
+  ) {
+    return null;
+  }
+  const expected = resolve(projectRoot, declared, "workspace.json");
+  if (expected !== resolve(filePath)) return null;
+  return {
+    filePath: resolve(filePath),
+    projectRoot: resolve(projectRoot),
+    stateDeclared: declared,
+    stateRoot: resolve(projectRoot, declared),
+    data,
+  };
+}
+
+function workspaceProbes(projectRoot) {
+  const root = resolve(projectRoot);
+  return [
+    { projectRoot: root, filePath: join(root, "speculo", ".speculo", "workspace.json") },
+    { projectRoot: root, filePath: join(root, ".speculo", "workspace.json") },
+  ];
+}
+
+function collectWorkspaceCandidates(repoRoot, change) {
+  const probes = [];
+  if (repoRoot) {
+    probes.push(...workspaceProbes(repoRoot));
+  } else {
+    for (const dir of uniqueResolved([...ancestorsOf(change), ...ancestorsOf(process.cwd())])) {
+      probes.push(...workspaceProbes(dir));
+    }
+  }
+  const found = new Map();
+  for (const probe of probes) {
+    const parsed = parseWorkspaceCandidate(probe.filePath, probe.projectRoot);
+    if (!parsed) continue;
+    if (!found.has(parsed.filePath)) found.set(parsed.filePath, parsed);
+  }
+  return [...found.values()];
+}
+
+function isLegalChangeLocation(changeAbs, stateRoot) {
+  const name = basename(changeAbs);
+  if (resolve(stateRoot, "specdev", "changes", name) === changeAbs) return true;
+  const monthDir = dirname(changeAbs);
+  const archiveRoot = dirname(monthDir);
+  return (
+    /^\d{4}-\d{2}$/.test(basename(monthDir)) &&
+    resolve(stateRoot, "specdev", "archive") === archiveRoot &&
+    basename(changeAbs) === name
+  );
+}
+
+function resolveWorkspaceContract(repoRoot, change) {
+  const changeAbs = resolve(change);
+  const candidates = collectWorkspaceCandidates(repoRoot, changeAbs);
+  if (!candidates.length) {
+    return { mode: "legacy", errors: [], config: null, specdevRoot: null, stateDeclared: null };
+  }
+  const uniqueRoots = uniqueResolved(candidates.map((candidate) => candidate.stateRoot));
+  if (uniqueRoots.length > 1) {
+    const declared = [...new Set(candidates.map((candidate) => candidate.stateDeclared))].sort();
+    return {
+      mode: "strict",
+      errors: [`conflicting workspace.json roots.state (${declared.join(" vs ")})`],
+      config: null,
+      specdevRoot: null,
+      stateDeclared: null,
+    };
+  }
+  const workspace = candidates[0];
+  const specdevRoot = join(workspace.stateRoot, "specdev");
+  const errors = [];
+  if (!isLegalChangeLocation(changeAbs, workspace.stateRoot)) {
+    errors.push(
+      `change is outside workspace roots.state (${workspace.stateDeclared}/specdev); project-root .speculo/specdev is illegal`,
+    );
+  }
+  let config = null;
+  const configPath = join(specdevRoot, "config.json");
+  if (isFile(configPath)) {
+    try {
+      config = JSON.parse(readText(configPath));
+    } catch {
+      config = null;
+    }
+  }
+  return {
+    mode: "strict",
+    errors,
+    config,
+    specdevRoot,
+    stateDeclared: workspace.stateDeclared,
+  };
+}
+
+function findSpecdevConfig(change, repoRoot = null) {
+  const contract = resolveWorkspaceContract(repoRoot, change);
+  if (contract.mode === "strict") return contract.config;
+  return findSpecdevConfigByAncestry(change);
+}
+
 function positiveConfigLimit(config, key, fallback) {
   const value = config?.execution?.[key];
   return Number.isInteger(value) && value >= 1 ? value : fallback;
@@ -1701,9 +1844,9 @@ function validateGoalPlan(path, errors) {
   return { path, meta, body };
 }
 
-function validateGoalPlanRuntimeLimits(path, change, goalPlan, errors) {
+function validateGoalPlanRuntimeLimits(path, change, goalPlan, errors, repoRoot = null) {
   if (!goalPlan) return;
-  const config = findSpecdevConfig(change);
+  const config = findSpecdevConfig(change, repoRoot);
   if (!config) {
     errors.push(`${basename(path)}: SpecDev config.json is required to validate execution limits`);
     return;
@@ -2758,7 +2901,7 @@ function validateParentImplementation(change, parentStatus, stage, errors, warni
     if (overlap.length) errors.push(`member changes already belong to unfinished parent implementation ${entry.name}: ${JSON.stringify(overlap)}`);
   }
 
-  const config = findSpecdevConfig(change);
+  const config = findSpecdevConfig(change, repoRoot);
   const configuredAgents = positiveConfigLimit(config, "max_implementation_agents", 0);
   const configuredAttempts = positiveConfigLimit(config, "max_integration_attempts", 0);
   if (!config || config.schema_version !== CONFIG_SCHEMA_VERSION || configuredAgents === 0 || configuredAttempts === 0) {
@@ -2849,6 +2992,9 @@ function validateChange(change, stage = null, repoRoot = null) {
     return { errors: [`change directory does not exist: ${change}`], warnings };
   }
 
+  const workspace = resolveWorkspaceContract(repoRoot, change);
+  errors.push(...workspace.errors);
+
   const changeStatus = validateChangeStatus(join(change, ".status.json"), basename(change), errors);
   validateParentImplementation(change, changeStatus, stage, errors, warnings, repoRoot);
   errors.push(...validateInitiative(change));
@@ -2972,7 +3118,7 @@ function validateChange(change, stage = null, repoRoot = null) {
     }
   }
   if (changeStatus && goalPlan) {
-    validateGoalPlanRuntimeLimits(goalPlan.path, change, goalPlan, errors);
+    validateGoalPlanRuntimeLimits(goalPlan.path, change, goalPlan, errors, repoRoot);
     const attemptLimit = Number.isInteger(goalPlan.meta.integration_attempt_limit) ? goalPlan.meta.integration_attempt_limit : null;
     if (attemptLimit !== null) {
       for (const worktree of changeStatus.worktrees ?? []) {