@namewta/speculo 2.0.1 → 2.0.2

package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md

@@ -1,27 +1,27 @@
 # Candidate Merge And Parent Integration
 
-仅由 Lead/integration owner 对状态为 `review` 的 Ticket 调用。
+仅由 Lead/integration owner 对处于 review 的 Ticket 或 Direct Spec 执行单元调用。Ticket 状态来自原票；Direct Spec 状态来自原 Evidence 的 Workspace Execution Record。unit-id 为真实 Ticket ID 或 direct-spec。
 
 ## 1. 接收 source checkpoint
 
-1. 核对 Ticket、Goal Plan、Evidence 目标、owner 与本地 integration 授权；
+1. 核对获批 Spec/Ready Ticket、实际存在的计划、Evidence 目标、owner 与本地 integration 授权；
 2. 验证来源 worktree clean，branch tip 精确等于 `source_checkpoint`，commit 从 `base_sha` 可达；
 3. 审计实际 diff 未越过 writable/shared owner 合同；
 4. 确认 source-worktree 必跑非 E2E 检查已执行，且没有把 E2E 自报为通过；
 5. 重读父分支 checkout clean、HEAD 与 remote/本地约定，记录 `parent_before_sha`。
 
-建立新 candidate 前先比较 Ticket `attempts` 与有效 Plan 的 `integration_attempt_limit`。若前一轮尚未通过且当前 attempts 已达到上限，不创建或重建 candidate、不增加 attempts；保留 source workspace、旧 candidate 与失败记录，将 Ticket/worktree 标为 `blocked`，向有效 Lead 返回 `integration-attempt-limit`。
+建立新 candidate 前先比较原记录 `attempts` 与有效 Plan 或无 Goal 执行合同的 `integration_attempt_limit`。若前一轮尚未通过且当前 attempts 已达到上限，不创建或重建 candidate、不增加 attempts；保留 source workspace、旧 candidate 与失败记录，将执行记录及已有 Ticket 标为 `blocked`，向有效 Lead 返回 `integration-attempt-limit`。
 
 其他预检失败时保持 `review`/`blocked`，不开始候选合并。
 
 ## 2. 建立 parent-candidate checkout
 
-1. 使用 branch `speculo/integration/<change>/<ticket-id>` 和 locator `specdev-worktree/.integration/<ticket-id>`，从最新 `parent_before_sha` 建立 Lead-owned integration worktree；
+1. 使用 branch `speculo/integration/<change>/<unit-id>` 和 locator `specdev-worktree/.integration/<change>/<unit-id>`，从最新 `parent_before_sha` 建立 Lead-owned integration worktree；
 2. 如果父 SHA 是 source checkpoint 的祖先，在 candidate checkout 执行 `git merge --ff-only <source_checkpoint>`，`method=fast-forward`；
 3. 否则执行 `git merge --no-ff --no-commit <source_checkpoint>`；
 4. 冲突按 `<Path>{roots.workflows}/specdev/specdev-i-implement/references/merge-conflict-protocol.md</Path>` 处理。需要新产品决定时执行 `git merge --abort`，记录 blocker 并返回来源 worktree；
 5. 对分叉结果创建一次 Lead-owned candidate merge commit，`method=merge-commit`；
-6. 记录 candidate branch/locator、`candidate_sha`、`source_sha`、冲突路径与 attempts，worktree 状态改为 `integrating`、integration 状态改为 `candidate`。
+6. 记录 candidate branch/locator、`candidate_sha`、实际 Git tree SHA `candidate_tree_sha`、`source_sha`、冲突路径与 attempts，worktree 状态改为 `integrating`、integration 状态改为 `candidate`。
 
 重试前从最新父分支重建 candidate branch/worktree；旧 candidate SHA 保存在 Evidence。候选生命周期的重建/回收包含在 local candidate integration 授权中。
 
@@ -29,11 +29,11 @@
 
 在 candidate checkout 运行：
 
-- Ticket 受影响集成与回归；
+- 当前实现单元受影响集成与回归；
 - 项目要求的 typecheck/lint/build 或其他父状态检查；
-- 仅当 Ticket/Goal Plan `e2e.required=true` 时运行对应 E2E。
+- 仅当 Spec/Ticket/有效执行合同 `e2e.required=true` 时运行对应 E2E。
 
-每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。当本轮失败使 attempts 达到 Goal Plan 快照的 `integration_attempt_limit` 时，保存本轮失败并返回 Lead 复盘；不得继续机械修正、放宽断言、删除检查或发明行为。上限是 Lead 复盘触发点，不是永久禁止恢复。
+每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。当本轮失败使 attempts 达到有效执行合同的 `integration_attempt_limit` 时，保存本轮失败并返回 Lead 复盘；不得继续机械修正、放宽断言、删除检查或发明行为。上限是 Lead 复盘触发点，不是永久禁止恢复。
 
 ## 4. 推进父分支
 
@@ -42,13 +42,13 @@
 1. 重读父分支 HEAD；不等于 `parent_before_sha` 时将 candidate 标记 `stale`，不推进父分支并从步骤 2 重建；
 2. 在父分支 checkout 执行 `git merge --ff-only <candidate_sha>`；候选 merge commit 本身已以父 SHA 为第一祖先，因此不再创建第二个 merge commit；
 3. 重读父 HEAD、tree 与 ancestor 关系，确认 HEAD 精确等于 candidate SHA 且包含 source checkpoint；
-4. 写入 `result_sha=candidate_sha`、`verification=passed`、E2E 最终状态和 Evidence；
-5. integration/status 改为 `passed`/`integrated`，再由 Lead 标记 Ticket Done。
+4. 写入 `result_sha=candidate_sha`、`verification=passed`、full_suite/E2E 最终状态、`promotion_status=applied` 和 Evidence；
+5. integration/status 改为 `passed`/`integrated`，再由 Lead 标记 Ticket Done 或在 Direct Spec 全部 AC 通过后完成 change。
 
 ## 5. 失败、清理与恢复
 
-- candidate 检查失败：父分支不动，Ticket 回 `in_progress` 或 `blocked`，来源 worktree 保留；
-- 达到 integration attempt 上限：保留全部 source/candidate checkpoint 与失败记录，等待 Lead 在 Ticket Evidence 写明共同失败模式、最可能原因、下一轮改变和下一 owner/路由；只有形成有实质变化的新 Dispatch Packet 后，Lead 才可将当前 Ticket `attempts` 重置为 `0` 并重新进入 finalize；
+- candidate 检查失败：父分支不动，已有 Ticket 回 `in_progress` 或 `blocked`，来源 worktree 保留；
+- 达到 integration attempt 上限：保留全部 source/candidate checkpoint 与失败记录，等待 Lead 在原 Evidence 写明共同失败模式、最可能原因、下一轮改变和下一 owner/路由；只有形成有实质变化的新 Dispatch Packet 后，Lead 才可将当前执行记录 `attempts` 重置为 `0` 并重新进入 finalize；
 - 父 HEAD 漂移：旧 candidate 记 `stale`，完整重建并重跑；
 - 成功后可按 candidate integration 授权回收 transient integration worktree/branch；来源 branch/worktree 不自动清理。获得独立 cleanup 授权并清理后，只将生命周期状态改为 `removed`，完整保留已经通过的集成与 E2E 证据；
 - push、PR、remote merge、deploy、migration 和生产动作仍需各自授权。

package/template/workflows/specdev/common/tools/README.md

@@ -4,7 +4,7 @@
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|retro|pr-delivery|review|prototype|wayfinder|complete|archive-ready|archived> \
+  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn|retro|pr-delivery|review|prototype|wayfinder|complete|archive-ready|archived> \
   --repo <project-root> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```

package/template/workflows/specdev/common/tools/change-artifacts.mjs

@@ -2,6 +2,7 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { basename, join } from 'node:path';
+import { readChangeExecution } from './plan-contract.mjs';
 import {
   readChangeFactsSync, readArtifactSectionSync, readUtf8ArtifactSync,
   safeWorkPathSync, markdownBodyLines, parseFrontmatter,
@@ -105,16 +106,9 @@ function validateCancellation(facts, owner, errors) {
     }
   }
   for (const key of ['Dependencies','Checkpoints','External']) if (!/^(?:none|resolved|transferred|waived): \S/.test(data[key] ?? '')) errors.push(`closure-evidence-missing: ${facts.readmePath}: unresolved ${key}`);
-  const tickets = safeWorkPathSync(root, 'evidence', { type: 'directory' });
-  if (existsSync(tickets)) for (const file of readdirSync(tickets).filter(n => /^T-\d+\.md$/.test(n))) {
-    const path = safeWorkPathSync(tickets, file, { type: 'file', mustExist: true }), text = readUtf8ArtifactSync(path);
-    const blocks = [...text.matchAll(/^## Workspace Execution Record\r?\n([\s\S]*?)(?=^## |$(?![\s\S]))/gm)];
-    for (const block of blocks) {
-      const json = /```json\s*\n([\s\S]*?)\n```/.exec(block[1]);
-      if (!json) error('closure-evidence-missing', path, 'invalid workspace execution record');
-      const record = JSON.parse(json[1]);
-      if (['active','review','integrating','blocked'].includes(record.status)) errors.push(`writer-active: ${path}: cancellation does not end an execution owner or candidate`);
-    }
+  for (const record of readChangeExecution(root)) {
+    if (record.purpose === "direct-spec" && record.status === "cancelled" && !/^stopped: \S/.test(data.Writers ?? "")) errors.push(`writer-active: ${root}: cancelled Direct Spec execution requires observed stopped writer evidence`);
+    if (['active','review','integrating','blocked'].includes(record.status)) errors.push(`writer-active: ${root}: ${record.ticket_id ?? 'direct-spec'} cancellation does not end an execution owner or candidate`);
   }
 }
 export function validateArchiveDelivery(changeRoot) {
@@ -152,7 +146,7 @@ export function validateChangeClosure({context, change, forArchive = false}) {
       const goalPath = safeWorkPathSync(root, 'goal-plan.md', {type:'file'});
       const lightweightGoal = existsSync(goalPath) && parseFrontmatter(readUtf8ArtifactSync(goalPath)).fields.artifact === 'lightweight-goal-plan';
       const independent = ['spec.md','ticket','tickets-map.md','implementation-plan.md','implementation-map.md','retro',...(!lightweightGoal ? ['goal-plan.md'] : [])].some(name => existsSync(join(root, name)));
-      const complex = independent || ['DESIGN.md','prototypes'].some(name => existsSync(join(root,name)));
+      const complex = independent || readChangeExecution(root).length > 0 || ['DESIGN.md','prototypes'].some(name => existsSync(join(root,name)));
       scope = complex ? 'complex-preflight' : 'lightweight';
       if (!independent && facts.outcome === 'completed') {
         validateLightweightCompletion(root, errors);

package/template/workflows/specdev/common/tools/plan-contract.mjs

@@ -262,13 +262,13 @@ export function validateInitiative(directory) {
   return errors;
 }
 
-/** Read actual per-Ticket integration records; never creates empty execution slots. */
+/** Read actual Ticket or Direct Spec records; never creates empty execution slots. */
 export function readChangeExecution(changeRoot) {
   const root = join(changeRoot, 'evidence');
   if (!existsSync(root)) return [];
   if (lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) throw new Error('Evidence must be a real directory');
   const records = [];
-  for (const file of readdirSync(root).filter(name => /^T-\d{2,}\.md$/.test(name)).sort()) {
+  for (const file of readdirSync(root).filter(name => /^T-\d{2,}\.md$/.test(name) || name === 'direct-spec.md').sort()) {
     const path = join(root, file);
     if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) throw new Error(`${path}: Evidence must be a regular file`);
     const text = readFileSync(path, 'utf8').replaceAll('\r\n', '\n');
@@ -276,9 +276,17 @@ export function readChangeExecution(changeRoot) {
     if (!sections.length) continue;
     if (sections.length !== 1) throw new Error(`${path}: duplicate Workspace Execution Record`);
     const record = readEvidenceValue(text,'## Workspace Execution Record');
-    if (!plainObject(record) || record.ticket_id !== file.slice(0, -3)) throw new Error(`${path}: execution record identity differs from Evidence Ticket`);
+    const direct = file === 'direct-spec.md';
+    if (!plainObject(record) || (direct
+      ? record.purpose !== 'direct-spec' || record.change !== basename(changeRoot) || 'ticket_id' in record
+      : record.ticket_id !== file.slice(0, -3) || 'purpose' in record || 'change' in record)) {
+      throw new Error(`${path}: execution record identity differs from Evidence ${direct ? 'Direct Spec/change' : 'Ticket'}`);
+    }
     records.push(record);
   }
+  if (records.some(record => record.purpose === 'direct-spec') && records.some(record => record.ticket_id)) {
+    throw new Error('Direct Spec and Ticket execution records cannot coexist; reconcile the original execution before changing modes');
+  }
   return records;
 }
 

package/template/workflows/specdev/common/tools/tests/engineering.test.mjs

@@ -223,10 +223,10 @@ test('range comparison and merge-base comparison have distinct semantics', t =>
   const range = resolveReviewScope({ repo: r.root, mode: 'range', base: r.c, head: side });
   assert.deepEqual(baseline.changed_paths, ['side.txt']); assert.deepEqual(range.changed_paths, ['b.txt', 'c.txt', 'side.txt']);
 });
-test('fifteen Work IDs and persisted schema versions remain unchanged', () => {
+test('fifteen Work IDs match the current registry and persisted schema versions remain unchanged', () => {
   const entries = readdirSync(workflow).filter(name => /^specdev-[a-z]-/.test(name)); assert.equal(entries.length, 15);
   const ids = entries.map(name => /speculo-id: (.+)$/m.exec(readFileSync(join(workflow, name, 'SKILL.md'), 'utf8'))?.[1]);
-  assert.deepEqual(ids.sort(), ['archive-and-consolidate','code-review','diagnose-bugs','goal-plan','grill-with-docs','implement','init-setup','learn-change','prototype','retro','review-architecture','spec','tickets','triage','wayfinder'].map(id => 'specdev/' + id).sort());
+  assert.deepEqual(ids.sort(), ['archive-and-consolidate','code-review','diagnose-bugs','goal-plan','grill-with-docs','implement','init-setup','learn','prototype','retro','review-architecture','spec','tickets','triage','wayfinder'].map(id => 'specdev/' + id).sort());
   for (const [file, version] of [['config', 7], ['status', 5], ['change-status', 6], ['goal-plan', 7]]) {
     const schema = JSON.parse(readFileSync(join(workflow, 'common/schemas', `${file}.schema.json`), 'utf8'));
     assert.equal(schema.properties.schema_version.const, version);