@accelerator-mzq/forge 1.4.0

package/dist/core/templates/skills/finishing-a-development-branch.md

@@ -0,0 +1,251 @@
+---
+name: forge:finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the forge:finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** - keep options concise.
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Switch to base branch
+git checkout <base-branch>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# If tests pass
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+
+## forge archive 衔接说明
+
+forge 路径下,这一步发生在 `/forge:archive` 之后(archive 已做产物归档 — change 产物移入 `forge/changes/archive/<change-id>/`),本 skill 仅引导用户决定 git 层面的合并/PR/清理策略。
+
+**典型 forge 流程顺序:**
+
+1. `forge:verification-before-completion` — 验证通过,写 `.verify-passed`
+2. `/forge:archive` — 归档 change 产物到 `forge/changes/archive/`
+3. `forge:finishing-a-development-branch` — 决定 git merge/PR/清理
+
+如果用户跳过了 archive 步骤直接来到这里,提示用户先运行 `/forge:archive`,除非用户明确要求跳过。
+
+## Quick Reference
+
+| Option           | Merge | Push | Keep Worktree | Cleanup Branch |
+| ---------------- | ----- | ---- | ------------- | -------------- |
+| 1. Merge locally | ✓     | -    | -             | ✓              |
+| 2. Create PR     | -     | ✓    | ✓             | -              |
+| 3. Keep as-is    | -     | -    | ✓             | -              |
+| 4. Discard       | -     | -    | -             | ✓ (force)      |
+
+## Common Mistakes
+
+**Skipping test verification**
+
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+
+- **Problem:** "What should I do next?" → ambiguous
+- **Fix:** Present exactly 4 structured options
+
+**Automatic worktree cleanup**
+
+- **Problem:** Remove worktree when might need it (Option 2, 3)
+- **Fix:** Only cleanup for Options 1 and 4
+
+**No confirmation for discard**
+
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+
+**Always:**
+
+- Verify tests before offering options
+- Present exactly 4 options
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+
+## Integration
+
+**Called by:**
+
+- **forge:subagent-driven-development** (Step 7) - After all tasks complete
+
+**Pairs with:**
+
+- **forge:using-git-worktrees** - Cleans up worktree created by that skill
+
+---
+
+## forge archive step (Tier 2/3 OpenCode/Codex 路径用,Plan 0a 实测 Variant B PASS)
+
+**仅 OpenCode + Codex 路径**(Tier 1 Claude Code 路径走 commands.md `/forge:archive` 调 helper)。
+
+When user says "archive" / "/forge:archive" / "完成归档" or similar, **after** finishing branch tasks(merge / clean / etc),you **MUST** execute:
+
+```bash
+node "${FORGE_HELPER}" archive <change-id>
+```
+
+(`FORGE_HELPER` 解析见 forge:writing-plans skill 末尾 "CLI validation step" 段)
+
+forge CLI 内部严格门禁(spec §3.4):
+
+- `.verify-passed` 存在 + tasks_hash 匹配
+- `.review-passed` 存在 + content_hash 匹配 + git.diff_hash 匹配
+- specs sync(internal-only,不可绕过)
+
+**Result handling**:
+
+- exit 0 → mv 到 `forge/changes/archive/<date>-<id>/`,Tell user "Archive PASS"
+- exit 非零 → 报 stderr,**不**重试,提示用户跑缺失 step(`/forge:verify` 或 `/forge:review`)
+
+**严格门禁不可绕过 — 不要主动加 `--force`**(那是给 maintainer 紧急 escape hatch 用的,不是 AI 自主决策范畴)。

package/dist/core/templates/skills/index.d.ts

@@ -0,0 +1,17 @@
+/** 16 个移植 skill 名(spec §2.2 12 skill 表 + plan-9i writing-skills + plan-9d verifying-three-dimensions + plan-9f exploring + plan-port-discipline subagent-driven-discipline) */
+export declare const SKILL_NAMES: readonly ["using-forge", "brainstorming", "writing-plans", "subagent-driven-development", "test-driven-development", "requesting-code-review", "receiving-code-review", "verification-before-completion", "systematic-debugging", "dispatching-parallel-agents", "using-git-worktrees", "finishing-a-development-branch", "writing-skills", "verifying-three-dimensions", "exploring", "subagent-driven-discipline"];
+export type SkillName = (typeof SKILL_NAMES)[number];
+/** 单 skill 内容加载 — 用 import.meta.url 定位,开发与生产路径自适应 */
+export declare function loadSkill(name: SkillName): Promise<string>;
+export interface LoadedSkill {
+    name: SkillName;
+    content: string;
+}
+/** 全量加载 16 个 skill,失败抛错(说明某个 .md 漏建) */
+export declare function loadAllSkills(): Promise<LoadedSkill[]>;
+/** 加载 _shared/*.md 全部 reference docs(plan-9b §2.6.8) */
+export declare function loadAllSharedDocs(): Promise<Array<{
+    name: string;
+    content: string;
+}>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/templates/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/skills/index.ts"],"names":[],"mappings":"AAUA,+KAA+K;AAC/K,eAAO,MAAM,WAAW,sZAiBd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,qDAAqD;AACrD,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhE;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,wBAAsB,aAAa,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAE5D;AAED,wDAAwD;AACxD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAgB3F"}

package/dist/core/templates/skills/index.js

@@ -0,0 +1,53 @@
+// 16 个 skill 真实文本的 registry — Plan 4 + plan-9i + plan-9d + plan-9f + plan-port-discipline
+// 文件实体 .md 由 Task B 逐个填实
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** 16 个移植 skill 名(spec §2.2 12 skill 表 + plan-9i writing-skills + plan-9d verifying-three-dimensions + plan-9f exploring + plan-port-discipline subagent-driven-discipline) */
+export const SKILL_NAMES = [
+    'using-forge',
+    'brainstorming',
+    'writing-plans',
+    'subagent-driven-development',
+    'test-driven-development',
+    'requesting-code-review',
+    'receiving-code-review',
+    'verification-before-completion',
+    'systematic-debugging',
+    'dispatching-parallel-agents',
+    'using-git-worktrees',
+    'finishing-a-development-branch',
+    'writing-skills', // 9i 新增(沿 design §2.9 协议落地 + plan-9i v7)
+    'verifying-three-dimensions', // 9d 新增(沿 design §2.2 协议落地 + plan-9d v15)
+    'exploring', // 9f 新增(沿 design §2.5 全节 + plan-9f)
+    'subagent-driven-discipline', // plan-port-discipline 新增(移植 superpowers SDD 的 companion)
+];
+/** 单 skill 内容加载 — 用 import.meta.url 定位,开发与生产路径自适应 */
+export async function loadSkill(name) {
+    return readFile(join(__dirname, `${name}.md`), 'utf8');
+}
+/** 全量加载 16 个 skill,失败抛错(说明某个 .md 漏建) */
+export async function loadAllSkills() {
+    return Promise.all(SKILL_NAMES.map(async (name) => ({ name, content: await loadSkill(name) })));
+}
+/** 加载 _shared/*.md 全部 reference docs(plan-9b §2.6.8) */
+export async function loadAllSharedDocs() {
+    const sharedDir = join(__dirname, '_shared');
+    let entries;
+    try {
+        entries = await readdir(sharedDir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const mdFiles = entries.filter((n) => n.endsWith('.md'));
+    return Promise.all(mdFiles.map(async (filename) => ({
+        name: filename.replace(/\.md$/, ''),
+        content: await readFile(join(sharedDir, filename), 'utf8'),
+    })));
+}
+//# sourceMappingURL=index.js.map

package/dist/core/templates/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/templates/skills/index.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,yBAAyB;AAEzB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,+KAA+K;AAC/K,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa;IACb,eAAe;IACf,eAAe;IACf,6BAA6B;IAC7B,yBAAyB;IACzB,wBAAwB;IACxB,uBAAuB;IACvB,gCAAgC;IAChC,sBAAsB;IACtB,6BAA6B;IAC7B,qBAAqB;IACrB,gCAAgC;IAChC,gBAAgB,EAAE,yCAAyC;IAC3D,4BAA4B,EAAE,0CAA0C;IACxE,WAAW,EAAE,oCAAoC;IACjD,4BAA4B,EAAE,0DAA0D;CAChF,CAAC;AAIX,qDAAqD;AACrD,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAe;IAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAOD,wCAAwC;AACxC,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAClG,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC7C,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAChE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,GAAG,CAChB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QACnC,OAAO,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC3D,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC"}

package/dist/core/templates/skills/process-evidence.md

@@ -0,0 +1,146 @@
+---
+name: forge:process-evidence
+description: 用于 v1.0 process_evidence 协议 — 写 marker 阶段必须走 helper / 不直写 marker / 不静默切 mode / 不跳 RED commit / staging append-only。当主代理在 task 实施时或写 .verify-passed marker 时,本 skill 强制 helper-only 写入路径,挡 5 大类伪造攻击。
+---
+
+# process-evidence skill
+
+> v1.0 forge 反伪造架构关键 skill。**当 AI 实施 task / 写 marker 时强制本协议**。
+
+## 何时调用
+
+- 主代理在 `commands/apply.md` 步骤 4 dispatch subagent + 收到 DONE_REPORT
+- 主代理在 `commands/verify.md` 步骤 4.3 写 .verify-passed YAML
+- 主代理在 `commands/review.md` 写 .review-passed YAML
+
+## 核心协议(brainstorm spec §2.7)
+
+### 1. 走 helper,不直写 marker
+
+✗ 禁止:
+
+- 主代理直接 fs.writeFile .verify-passed 含 process_evidence 字段
+- 主代理拼接 YAML 字面塞到 marker
+
+✓ 必须:
+
+- subagent 在 task 实施时跑测试 + 算 hash + 报 DONE 含 RED commit / GREEN commit / log paths / log hashes / report paths / report hashes / exit_codes / expected_failures
+- 主代理调 `forge evidence record-tdd <changeId> --task <...> --red-commit <sha> --red-timestamp <iso> --red-log <path> --red-log-hash <sha256> --red-report <path> --red-report-hash <sha256> --red-exit <int> --green-commit <sha> ... --expected-failures <json>`(20 options)
+- 主代理在 verify 完成时调 `forge evidence record-verify <changeId> --task-refs <list> --scope <type> --report <path> --report-hash <sha256> --log <path> --log-hash <sha256> --exit-code <int> --invoked-at <iso>`
+- 主代理在 SDD 二段 review 完成时调 `forge evidence record-review <changeId> --task <...> --implementer-commit <sha> --spec-iterations <json> --quality-iterations <json> --main-check-off-at <iso>`
+- 主代理在 commands/verify.md 步骤 4.3 写完 .verify-passed YAML 后**必须**调 `forge evidence freeze <changeId> --kind verify`
+
+### 2. 不静默切 mode=hash-only
+
+✗ 禁止:
+
+- 主代理改 forge/config.yaml process_verification.mode 不跑 ack
+- AI 自行决定走 sample / hash-only 模式
+
+✓ 必须:
+
+- 用户主动跑 `forge ack propose --action ack-mode --finding <id>`
+- mode != full 必须 user CLI ack(不变量 12 strict)
+- CI 模式(CI=true)强制 mode=full;ack-mode 在 CI 拒绝(brainstorm spec §6 ack.allow_ci_mode 默认 false)
+
+### 3. RED commit 不可省略
+
+✗ 禁止:
+
+- subagent 同 commit 写测试 + 实现
+- 主代理填 tdd_exemption 不跑 ack
+
+✓ 必须:
+
+- subagent 先建 RED commit(测试 fail + 实现未写 / 不通过)
+- subagent 后建 GREEN commit(实现写 + 测试 pass)
+- light mode trivial change(< writing_plans.light_threshold)允许 tdd_exemption,但**必须**跑 `forge ack propose --action ack-tdd-exemption`(不变量 11 strict)
+
+### 4. Staging append-only,不绕过
+
+✗ 禁止:
+
+- 主代理直接编辑 .evidence/process-evidence.staging.yaml
+- 主代理跳 staging,直接修改 marker.process_evidence
+
+✓ 必须:
+
+- helper(record-tdd / record-verify / record-review)是唯一 staging 写入路径
+- staging 写入走文件锁 .evidence/.staging.lock(并发保护)
+- freeze 子命令是唯一 marker 写入路径
+
+### 5. 不绕过 freeze 子命令
+
+✗ 禁止:
+
+- 主代理直接写 .verify-passed.yaml 含完整 process_evidence(包括 staging_hash / ack_log_tail_hash / ack_log_entry_count)
+- 主代理拼接 marker.verify_findings(WARNING 转 VerifyFinding 由 freeze 子命令做)
+
+✓ 必须:
+
+- 调 `forge evidence freeze --kind verify|review` 写 process_evidence + 三 hash 字段
+- 接受 freeze 子命令 stderr 输出 WARNING(自动写 marker.verify_findings;archive 步骤 3.6 接 ack 流程)
+- 若 freeze exit 1 → 先跑 `forge ack propose` 处理 CRITICAL 11/12 后 retry freeze
+
+## 反伪造五源 cross-check
+
+archive `crossCuttingFenceCheck()` 跑 14 不变量:
+
+- 1-4: 字段关系(timestamp / ancestor / exit_code)
+- 5-6: worktree 重跑实际 fail/pass + reporter parse expected_failures
+- 7: verify_invocations 计数(WARNING)
+- 8: subagent review chain commit 顺序
+- 9: 五源 hash cross-check(marker / staging / ack-log content / ack-log chain / tail+count)
+- 10: env_hash drift(WARNING)
+- 11: tdd_exemption ack
+- 12: mode != full ack + CI 拒签
+- 13: rerun timeout severity 分级
+- 14: green ↞ archive HEAD ancestor(挡旁支造链)
+
+CRITICAL → archive 拒签 exit 1;WARNING → marker.verify_findings 走 9d ack 流程(或 ack-mode 隐含覆盖 rerun-time WARNING)
+
+## 失败模式 + Recovery
+
+| 失败模式           | 症状                                                 | Recovery                                                          |
+| ------------------ | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| 直写 marker        | .verify-passed 含 process_evidence 但无 staging 条目 | archive fence 9 → CRITICAL 拒签;重跑 record-tdd + freeze          |
+| 静默 hash-only     | config.yaml mode=hash-only 无 ack-log entry          | fence 12 → CRITICAL 拒签;跑 `forge ack propose --action ack-mode` |
+| 跳 RED commit      | tdd_event_chain 无 red_exit_code!=0 条目             | fence 5 worktree 重跑 → CRITICAL;必须补 RED commit                |
+| staging 被手动编辑 | staging_hash mismatch                                | fence 9 → CRITICAL 拒签;从 ack-log 重建 staging                   |
+| freeze 绕过        | marker 有 process_evidence 但无 staging_hash 字段    | fence 9 → CRITICAL 拒签;重跑 freeze                               |
+
+## 反例 / 正例
+
+✗ 禁止(借口模式):
+
+```
+# 错误:主代理直接构造 process_evidence YAML
+cat <<EOF > .verify-passed.yaml
+process_evidence:
+  tdd_event_chain:
+    - red_commit: abc123
+      red_exit_code: 1
+      green_commit: def456
+      green_exit_code: 0
+EOF
+```
+
+✓ 必须(正确路径):
+
+```bash
+# subagent DONE_REPORT 后,主代理调 helper
+forge evidence record-tdd <changeId> \
+  --task task-1 \
+  --red-commit abc123 --red-timestamp 2026-05-13T10:00:00Z \
+  --red-log .evidence/task-1-red.log --red-log-hash sha256:... \
+  --red-report .evidence/task-1-red-junit.xml --red-report-hash sha256:... \
+  --red-exit 1 \
+  --green-commit def456 --green-timestamp 2026-05-13T10:30:00Z \
+  --green-log .evidence/task-1-green.log --green-log-hash sha256:... \
+  --green-report .evidence/task-1-green-junit.xml --green-report-hash sha256:... \
+  --green-exit 0 \
+  --expected-failures '[{"test_file":"src/auth.test.ts","test_name":"should reject expired token","failure_type":"AssertionError"}]'
+
+# verify 完成后写 marker,再 freeze
+forge evidence freeze <changeId> --kind verify
+```