@heihei0299/matt-skills 3.0.1 → 3.0.3

package/.agents/skills/tdd-implement/SKILL.md

@@ -35,32 +35,37 @@ disable-model-invocation: true
 
 读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。
 
-最终验证通过且 diff 稳定后执行完整 `code-review`。
+最终验证通过且 diff 稳定后进入 Review。
 
 #### Review
 
-每个 issue 只在 Verify 的最终 diff 稳定后调用一次完整 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；多 issue 层收敛不再次调用完整 Review。
+每个 issue 维护以下 Review 状态：
 
-若完整 Review 存在 blocking finding：
+- `full_review_done = false`
+- `open_findings = []`
+
+当 `full_review_done = false` 时，只调用一次完整 `code-review`。完成后立即设置 `full_review_done = true`，并将 blocking findings 写入 `open_findings`。
+
+当 `full_review_done = true` 时，完整 `code-review` 路径关闭，不得再次启动完整双轴 Review。后续仅处理 `open_findings`：
 
 1. 仅修复对应 finding，不扩大当前 issue 范围；
-2. 修复后仅对该 finding 及其直接影响执行增量 Review；
-3. 未受影响的 Review 结论继续有效；
-4. 不重新执行完整双轴 Review；
-5. 若增量 Review 仍存在问题，仅继续修复并复核剩余 finding。
+2. 重新验证该修复直接影响的证据；
+3. 直接针对该 finding 与修复 diff 做增量 Review；增量 Review 不调用完整 `code-review`；
+4. 复核通过后从 `open_findings` 移除该 finding；
+5. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，再回 Verify 验证受影响范围；`full_review_done` 保持为 `true`。
 
-所有 blocking finding 关闭后 Review 才算通过。
+`full_review_done = true` 且 `open_findings` 为空时 Review 才算通过。审查维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
 
 **出口：**
 
 - 当前 issue 所需最终验证通过；
 - 要求的真实运行验证完成；
-- 完整 Review 已完成；
-- 所有 blocking finding 已关闭。
+- `full_review_done = true`；
+- `open_findings` 为空。
 
 ## Finalize
 
-Verify 通过后读取 [finalize.md](references/finalize.md)，完成当前 issue 的必要同步、独立 commit 与 tracker/progress 收尾。
+Verify 与 Review 通过后读取 [finalize.md](references/finalize.md)，完成当前 issue 的必要同步、tracker/progress 与仓库 Git policy 收尾。
 
 Finalize 不新增产品 Behavior；若发现实现或验证遗漏，回到对应 Step 完成后再收尾。
 
@@ -69,7 +74,8 @@ Finalize 不新增产品 Behavior；若发现实现或验证遗漏，回到对
 - Red-Green 必须覆盖当前 issue 的全部待实现 Behavior，不能只对第一个改动执行 TDD。
 - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
 - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
-- 完整双轴 Review 每个 issue 只执行一次；后续修复只执行受影响 finding 的增量 Review。
+- 每个 issue 的完整双轴 Review 只允许从 `full_review_done = false` 进入一次；之后只处理 `open_findings` 的增量 Review。
+- Git 提交数量与粒度服从当前仓库规则和用户指令，本技能不另行规定。
 - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
 
 ## References

package/.agents/skills/tdd-implement/references/finalize.md

@@ -1,16 +1,16 @@
 # Finalize
 
-仅在 Verify 通过后执行；不新增产品 Behavior。
+仅在 Verify 与 Review 通过后执行；不新增产品 Behavior。Git 提交数量与粒度由当前仓库规则和用户指令决定，本文件不另行规定。
 
 1. 完成实现要求的必要 docs/config 同步。
-2. 为当前 issue 创建一个独立 commit。
-3. 更新 progress/tracker，记录 commit、Review、验证与运行结果，并解除已满足的 blockers。
-4. 将 Acceptance Criteria 标记完成，issue 标记 `resolved`。
+2. 更新 Acceptance Criteria 与 progress/tracker，记录 Review、验证与运行结果；若当前仓库策略已产生 commit，可记录对应 commit。
+3. 将 issue 标记 `resolved`，并解除已满足的 blockers。
+4. 若当前仓库规则或用户指令要求提交，按其 Git policy 执行。
 
 若发现实现或验证遗漏，返回对应 Step 完成后再收尾。
 
 ## 出口
 
-- 当前 issue 的独立 commit 已创建；
 - Acceptance Criteria 全部通过；
-- tracker/progress 与实际完成状态一致。
+- issue、blockers 与 tracker/progress 和实际完成状态一致；
+- Git 行为符合当前仓库规则与用户指令。

package/.agents/skills/tdd-implement/references/orchestration.md

@@ -25,19 +25,19 @@ for each layer:
 
 一个 issue Finalize 完成后立即进入下一个可调度 issue。前置 issue 未完成时，其依赖项保持 `blocked`。
 
-每个 issue 的 TDD、验证、Review 与 Finalize 规则分别以 `SKILL.md`、`red-green.md`、`verify.md`、`finalize.md` 为准，本文件不重复定义。
+每个 issue 的 Red-Green 与 Review 编排以 `SKILL.md` 为准；验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义。
 
 ## 3. 状态收敛
 
 每个 issue 完成后同步：
 
 - `Status`；
-- commit；
 - Review 状态；
 - 验证结果；
-- 已解除的 blockers。
+- 已解除的 blockers；
+- commit（仅当当前仓库 Git policy 已产生对应 commit 时）。
 
-当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
+当前层所有 issue 完成后进入下一层。全部层完成后，确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。Git 提交数量与粒度始终服从当前仓库规则和用户指令。
 
 ## 冲突与失败
 
@@ -49,6 +49,6 @@ for each layer:
 ## 出口
 
 - 所有可执行 issue 均按依赖顺序完成；
-- 每个完成的 issue 均有独立 commit；
 - issue、依赖状态与 progress 一致；
+- Git 行为符合当前仓库规则与用户指令；
 - 不存在被误当作已完成的 blocked issue。

package/README.md

@@ -55,7 +55,7 @@ npx @heihei0299/matt-skills sync --all       # 同步全部可分发 skills
 npx @heihei0299/matt-skills sync --dry-run --json
 ```
 
-`init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。`sync` 不删除目标项目的额外文件或自定义 skills。
+`init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。默认 `sync` 只刷新 `AGENTS.md` 的 `matt-skills:managed` 受管区块并保留标记外的项目规则；旧的无标记 `AGENTS.md` 原样保留，`sync --all` 才整体刷新。`sync` 不删除目标项目的额外文件或自定义 skills。
 
 默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
 

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, cp, stat, rm, mkdir } from 'node:fs/promises';
+import { readdir, readFile, writeFile, cp, stat, rm, mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -71,7 +71,7 @@ Sync options:
   --dest <path>   Target directory (default: current directory)
   --help, -h      Show this help
 
-说明：默认不带 --all 仅增量同步默认 programming skill 且 AGENTS.md 有定制则跳过；--all 时同步全部可分发 skill 并强制更新 AGENTS.md。
+说明：默认不带 --all 增量同步默认 programming skill，并只更新 AGENTS.md 的 matt-skills 受管区块；没有受管标记的现有 AGENTS.md 原样保留。--all 时同步全部可分发 skill 并强制刷新 AGENTS.md。
 
 提示：matt-skills --help 查看全量
 `;
@@ -187,6 +187,34 @@ function shouldCopyTemplatePath(src) {
   return !(parts[0] === '.agents' && parts[1] === 'skills');
 }
 
+const AGENTS_MANAGED_START = '<!-- matt-skills:managed:start -->';
+const AGENTS_MANAGED_END = '<!-- matt-skills:managed:end -->';
+
+function findManagedBlock(content) {
+  const start = content.indexOf(AGENTS_MANAGED_START);
+  if (start < 0 || content.indexOf(AGENTS_MANAGED_START, start + AGENTS_MANAGED_START.length) >= 0) return null;
+  const endStart = content.indexOf(AGENTS_MANAGED_END, start + AGENTS_MANAGED_START.length);
+  if (endStart < 0 || content.indexOf(AGENTS_MANAGED_END, endStart + AGENTS_MANAGED_END.length) >= 0) return null;
+  return { start, end: endStart + AGENTS_MANAGED_END.length };
+}
+
+function mergeManagedAgents(current, template) {
+  const currentBlock = findManagedBlock(current);
+  const templateBlock = findManagedBlock(template);
+  if (!currentBlock || !templateBlock) return null;
+  const managed = template.slice(templateBlock.start, templateBlock.end);
+  return current.slice(0, currentBlock.start) + managed + current.slice(currentBlock.end);
+}
+
+async function syncManagedAgents(targetFile) {
+  const current = await readFile(targetFile, 'utf8');
+  const template = await readFile(path.join(TEMPLATE_DIR, 'AGENTS.md'), 'utf8');
+  const merged = mergeManagedAgents(current, template);
+  if (merged === null) return false;
+  if (merged !== current) await writeFile(targetFile, merged);
+  return true;
+}
+
 const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
 
 // 统一源：共享技能全部在 .agents/skills，harness 的 .pi/skills/.opencode/skills 仅用于项目自定义
@@ -340,26 +368,12 @@ async function initCommand({ dest, all }) {
 async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
   const onlyProgramming = !all;
   if (dryRun) {
-    const { compare } = await import('../scripts/sync-upstream.js');
+    const { compare, formatComparison } = await import('../scripts/sync-upstream.js');
     const cmp = await compare({ upstreamUrl, ref, onlyProgramming });
     if (json) {
       process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
     } else {
-      const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量上游）';
-      const lines = [];
-      lines.push(`上游 HEAD: ${cmp.head}`);
-      lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream} ${modeHint}`);
-      lines.push('');
-      const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;
-      if (totalDiff === 0) lines.push('✅ 已是最新，无差异');
-      else {
-        if (cmp.result.added.length) lines.push(`新增 (${cmp.result.added.length}): ${cmp.result.added.join(', ')}`);
-        if (cmp.result.updated.length) lines.push(`更新 (${cmp.result.updated.length}): ${cmp.result.updated.join(', ')}`);
-        if (cmp.result.renamed.length) lines.push(`重命名 (${cmp.result.renamed.length}): ${cmp.result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
-        if (cmp.result.removed.length) lines.push(`删除 (${cmp.result.removed.length}): ${cmp.result.removed.join(', ')}`);
-        if (cmp.result.same.length) lines.push(`一致 (${cmp.result.same.length}): ${cmp.result.same.join(', ')}`);
-      }
-      process.stdout.write(lines.join('\n') + '\n');
+      process.stdout.write(formatComparison(cmp) + '\n');
     }
     const { rm } = await import('node:fs/promises');
     await rm(cmp.dest, { recursive: true, force: true });
@@ -396,26 +410,25 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
     process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
   } else {
     process.stdout.write('同步：检测到现有项目，将增量更新\n');
-    let skipAgents = false;
-    // --all 时强制更新 AGENTS.md，不跳过
-    if (!all) {
-      try {
-        const content = await readFile(path.join(target, 'AGENTS.md'), 'utf8');
-        if (content.includes('tdd-implement')) skipAgents = true;
-      } catch {}
-    }
-    if (skipAgents) {
-      await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
-      await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
-      process.stdout.write('模板：已同步（AGENTS.md 跳过，已含定制）\n');
-    } else {
-      if (onlyProgramming) await copyTemplateFiltered();
-      else await cp(TEMPLATE_DIR, target, {
+    if (all) {
+      await cp(TEMPLATE_DIR, target, {
         recursive: true,
         force: true,
         filter: shouldCopyTemplatePath,
       });
-      process.stdout.write('模板：已同步（AGENTS.md、.agents/skills、.opencode/、.pi/）\n');
+      process.stdout.write('模板：已同步（AGENTS.md 整体刷新、.opencode/、.pi/）\n');
+    } else {
+      let agentsManaged = false;
+      try {
+        agentsManaged = await syncManagedAgents(marker);
+      } catch {}
+      await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
+      await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
+      if (agentsManaged) {
+        process.stdout.write('模板：已同步（AGENTS.md 受管区块已更新，项目自定义内容已保留）\n');
+      } else {
+        process.stdout.write('模板：已同步（AGENTS.md 未受管，已原样保留）\n');
+      }
     }
   }
   // 技能同步：--all 仅更新同名可分发技能内容，存在则覆盖，不存在则新增，并更新 AGENTS.md（由上一步已处理）；默认范围为默认 programming，不删多余
@@ -559,7 +572,7 @@ function parseInstallArgs(args) {
 }
 
 async function checkCommand(args) {
-  const { compare } = await import('../scripts/sync-upstream.js');
+  const { compare, formatComparison } = await import('../scripts/sync-upstream.js');
   const json = args.includes('--json');
   const onlyProgramming = !args.includes('--all');
   const upstreamIdx = args.indexOf('--upstream');
@@ -572,22 +585,7 @@ async function checkCommand(args) {
   if (json) {
     process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
   } else {
-    const lines = [];
-    lines.push(`上游 HEAD: ${cmp.head}`);
-    const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量上游）';
-    lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream} ${modeHint}`);
-    lines.push('');
-    const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;
-    if (totalDiff === 0) {
-      lines.push('✅ 已是最新，无差异');
-    } else {
-      if (cmp.result.added.length) lines.push(`新增 (${cmp.result.added.length}): ${cmp.result.added.join(', ')}`);
-      if (cmp.result.updated.length) lines.push(`更新 (${cmp.result.updated.length}): ${cmp.result.updated.join(', ')}`);
-      if (cmp.result.renamed.length) lines.push(`重命名 (${cmp.result.renamed.length}): ${cmp.result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
-      if (cmp.result.removed.length) lines.push(`删除 (${cmp.result.removed.length}): ${cmp.result.removed.join(', ')}`);
-      if (cmp.result.same.length) lines.push(`一致 (${cmp.result.same.length}): ${cmp.result.same.join(', ')}`);
-    }
-    process.stdout.write(lines.join('\n') + '\n');
+    process.stdout.write(formatComparison(cmp) + '\n');
   }
   const { rm } = await import('node:fs/promises');
   await rm(cmp.dest, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/scripts/sync-upstream.js

@@ -111,12 +111,12 @@ async function collectLocalSkills(proprietary) {
 export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true } = {}) {
   const proprietary = await loadProprietary();
   const engineering = await loadEngineering();
+  const required = await loadRequired();
   const fetched = await fetchUpstream({ tmpDir, upstreamUrl, ref });
   const upstreamRoot = fetched.dest;
   const upstreamMapFull = await collectUpstreamSkills(upstreamRoot);
   const localMapFull = await collectLocalSkills(proprietary);
   // 默认范围：engineering 桶（编程）+ 独有所需（config/required.json，如 grill-to-spec 经 grill-with-docs 所需的 grilling）；--all 则含全部 productivity
-  const required = await loadRequired();
   const upstreamMap = onlyProgramming
     ? new Map([...upstreamMapFull.entries()].filter(([name, v]) => v.bucket === 'engineering' || required.has(name)))
     : upstreamMapFull;
@@ -242,7 +242,7 @@ export async function applySync({ upstreamUrl, tmpDir, ref, dryRun = false, forc
 
   return { ...cmp, dest: null, actions, head };
 }
-function formatTable(cmp) {
+export function formatComparison(cmp) {
   const { result, counts, head, onlyProgramming } = cmp;
   const lines = [];
   lines.push(`上游 HEAD: ${head}`);
@@ -307,7 +307,7 @@ Options:
     if (opts.json) {
       process.stdout.write(JSON.stringify({ head: res.head, result: res.result, actions: res.actions, dryRun: opts.dryRun, onlyProgramming }, null, 2) + '\n');
     } else {
-      process.stdout.write(formatTable(res) + '\n');
+      process.stdout.write(formatComparison(res) + '\n');
       if (res.actions.length) {
         process.stdout.write(`\n已执行 ${res.actions.length} 项:\n`);
         for (const a of res.actions) process.stdout.write(`  - ${a}\n`);
@@ -324,7 +324,7 @@ Options:
   if (opts.json) {
     process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
   } else {
-    process.stdout.write(formatTable(cmp) + '\n');
+    process.stdout.write(formatComparison(cmp) + '\n');
   }
   const hasDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length > 0;
   // 清理临时目录

package/template/.opencode/CONTEXT.md

@@ -1,6 +1,6 @@
 # matt-skills
 
-The domain vocabulary for this repo — two sections: how this repository is positioned (`## Repository`) and the terms that govern how long-horizon skills are written, reviewed, and evolved (`## Skill Design`). Every term here is a single source of truth; skills and docs reference it rather than restating the definition.
+Repository vocabulary for this project. This file defines domain terms only; execution policy belongs to the active `AGENTS.md`, and skill-specific behavior belongs to each live `SKILL.md` and its references.
 
 ## Repository
 
@@ -9,47 +9,29 @@ This repository's identity. It is the config repo for mattpocock/skills: it dist
 _Avoid_: skill distribution repo
 
 **Upstream Repository** (上游仓库):
-mattpocock/skills — the source of the 26 Skill bodies (skills/engineering + skills/productivity) that are mirrored into this repo's Workspace canonical Skill source and then distributed by the CLI. This repo syncs them via `scripts/sync-upstream.js` and `matt-skills sync`.
+mattpocock/skills — the source of the upstream Skill bodies mirrored into this repo's Workspace canonical Skill source and then distributed by the CLI. This repo syncs them via `scripts/sync-upstream.js` and `matt-skills sync`.
 _Avoid_: source repo, skill origin
 
 **Proprietary Skill** (独有技能):
-A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check, scaffold-functional-test and show-me). Before adding a new skill, check the Upstream Repository first; only skills absent there qualify as proprietary. The 7 proprietary skills are classified as 5 distributable (`tdd-implement`, `diagnose-fix`, `grill-to-spec`, `scaffold-functional-test`, `show-me`) and 2 repo-local (`ci-guard`, `commit-check`). The default programming set includes 4 proprietary skills: `tdd-implement`, `diagnose-fix`, `grill-to-spec` and `show-me`; `scaffold-functional-test` is distributable but optional. Repo-local skills serve matt-skills maintenance and are never distributed. The issue-audit subagent is NOT a skill: it ships as a subagent + command under `.opencode/` and is distributed through the Template Snapshot without a skill directory.
+A skill that does not exist upstream and lives only in this repo. The current proprietary set is classified in `config/proprietary.json` as distributable or repo-local; that config is the source of truth for membership. Repo-local skills serve matt-skills maintenance and are never distributed. Before adding a new proprietary skill, check the Upstream Repository first.
 _Avoid_: private skill, local skill
 
 **Workspace** (工作区):
-The root-level working copies of the template content — `.agents/skills/` (upstream plus all proprietary Skills, the canonical shared Skill source), `.opencode/` (issue-audit agent, explicit-Skill commands), `.pi/` (pi-agent prompts: `issue-audit`), `AGENTS.md`, `CONTEXT.md`, `docs/`. This is where the repo's own sessions load, modify and test the content. The Template Snapshot projects only the distributable configuration and skeleton: `.opencode/commands/*.md` → `template/.opencode/commands/`, `.pi/prompts/issue-audit.md` → `template/.pi/prompts/issue-audit.md`, and root-level `CONTEXT.md` and `docs/agents/` → `template/.opencode/` + `template/.pi/`. The CLI assembles selected shared Skills from the canonical source into a Target Repository. Harness-specific Skill dirs `.pi/skills/` and `.opencode/skills/` are reserved for project-local custom Skills (empty placeholders with `.gitkeep` + `README.md` in the Template Snapshot).
+The root-level canonical working area: `.agents/skills/` for shared Skills, `.opencode/` and `.pi/` for harness configuration, plus repository docs and configuration. Shared Skills are authored here. Harness-specific `.pi/skills/` and `.opencode/skills/` are reserved for project-local custom Skills rather than shared mirrors.
 _Avoid_: working copy, source repo
 
 **Template Snapshot** (模板快照):
-Everything under `template/` — the distributable snapshot of project skeleton content: harness Skill dirs `.pi/skills/` + `.opencode/skills/` as empty placeholders for project custom Skills, distributable opencode commands under `.opencode/commands/`, the pi issue-audit command under `.pi/prompts/`, discipline files and glossary under `.opencode/` + `.pi/`, and AGENTS.md at the top level. It is generated by `node scripts/build-template.js` and used to initialize other repositories. Shared Skills and repo-local Skills remain in the Workspace; the CLI distributes only the selected shared Skills. The sync direction for the skeleton is one-way: Workspace → Template Snapshot. Template structure tests guard the content the snapshot owns.
+Everything under `template/` that is generated or copied from Workspace sources for Target Repository initialization. The snapshot owns project skeleton/configuration, while shared Skills are assembled separately by the CLI from the Workspace canonical source. Skeleton sync is one-way: Workspace → Template Snapshot.
 _Avoid_: release snapshot, published snapshot
 
 **Target Repository** (目标仓库):
-A repository initialized by copying the Template Snapshot skeleton into its root and then receiving selected distributable shared Skills from the CLI. It loads shared Skills from its own `.agents/skills/`, project-local custom Skills from `.pi/skills/` / `.opencode/skills/` (if any), the distributable commands from `.opencode/commands/` (opencode) and the `issue-audit` command from `.pi/prompts/` (pi) / `.opencode/commands/` (opencode), and the project-level global config from `.opencode/` + `.pi/` and AGENTS.md. Repo-local matt-skills maintenance Skills are not part of a Target Repository by default.
+A repository initialized from the Template Snapshot and selected distributable shared Skills. Its root `AGENTS.md` is the project-level execution policy. Shared Skills live in `.agents/skills/`; project-local custom Skills may live in harness-specific skill directories.
 _Avoid_: inheriting repo, child repo
 
 **Initialize** (初始化):
-The one-time action of setting up a Target Repository: copying the Template Snapshot skeleton into its root, then having the CLI create its shared Skill directory and copy the selected distributable Skills from the Workspace canonical source. No separate upstream fetch is needed. Repo-local Skills are intentionally absent. Copying, not inheriting — no runtime relationship survives the copy.
+The one-time action of setting up a Target Repository by copying the Template Snapshot skeleton and installing the selected distributable Skills. Repo-local Skills are intentionally excluded.
 _Avoid_: inherit, bootstrap
 
 **Sync** (同步):
-`matt-skills sync` 同步 Target Repository 的 skeleton 与 Skills：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，canonical shared Skills 按默认 programming 范围覆盖但不删多余，Template Snapshot 的 `.opencode` / `.pi` 配置增量 add/update，`.pi/skills` 与 `.opencode/skills` 中已有的 project-local Skill 不按名称删除，避免把项目自定义 Skill 误删）、`--all` 仅更新同名可分发 Skill 内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余 Skill。Repo-local Skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
+`matt-skills sync` updates Target Repository skeleton/configuration and selected distributable Skills according to CLI policy. Default sync preserves project customization where the CLI can identify it; `--all` applies the broader distributable scope. Repo-local Skills are never newly distributed by sync.
 _Avoid_: update, force sync
-
-## Skill Design
-
-**Turn Continuity** (回合连续性):
-The rule that a long-horizon skill must carry a positive instruction to keep executing within a turn — red → green → typecheck → next seam serial in one turn until the stage's exit condition is met. The stage exit is reached when all of its seams are complete — one seam going green is not an exit, and progress output does not itself end the turn. It is the skill's own guard against premature turn-end; it must not rely on the harness `/goal` line (which does not exist when no `/goal` is active).
-_Avoid_: keep going, don't stop
-
-**Chunking** (拆小步 / 进度编排):
-Splitting a giant turn — one large `write` or a batch of `replace`s — into small steps that are individually verified before continuing, so the turn never hits output caps and gets truncated mid-work.
-_Avoid_: step-by-step, take it slow
-
-**Git History Preservation** (Git 历史保护):
-Every git-touching skill must preserve history after `BASE_HEAD=$(git rev-parse HEAD)` recorded at stage entry — history may only be appended. Before any commit or stage exit, verify `git merge-base --is-ancestor $BASE_HEAD HEAD`; if it fails, history was rewritten and must be recovered via `git reflog` before continuing. "Directory clean" (`git status` clean) may only be achieved by deleting the skill's own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files); destructive git commands `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked`, `git push --force`, `git rebase -i` are forbidden without explicit user confirmation.
-_Avoid_: force clean, stash all
-
-**Long-Horizon Skill** (长程多阶段技能):
-A skill whose run spans multiple stages or seams executed continuously (e.g. tdd-implement, diagnosing-bugs, improve-codebase-architecture, wayfinder, grill-to-spec, to-spec). The class of skill that must carry a Turn Continuity rule.
-_Avoid_: complex skill, big skill

package/template/.opencode/docs/agents/runtime-discipline.md

@@ -1,37 +1,26 @@
 # Runtime Discipline
 
-本仓库会话的运行时纪律，执行口径源自 `docs/agents/skill-design.md` 的四条规则（规范正文）。术语定义见 `CONTEXT.md`。
+This file contains only general execution discipline. It does not override the active project `AGENTS.md` or any skill-specific lifecycle.
 
-## 回合连续性规则
+## Ownership
 
-每个逻辑单元（红-绿循环、typecheck、测试修复）必须在一个回合内连续执行完毕后才输出：测试 → 分析失败 → 修正 → 重跑 → 全绿整条链一气呵成，中途不输出、不停止、不等用户"继续"。
+- authorization, validation scope, review scope and Git policy come from the active `AGENTS.md` and explicit user instructions;
+- a skill owns only its own lifecycle, state transitions and exit conditions;
+- TDD semantics belong to `.agents/skills/tdd/SKILL.md`;
+- full code-review semantics belong to `.agents/skills/code-review/SKILL.md`.
 
-输出只允许发生在三种情况：
-- 合规交互点：技能/流程要求的用户确认（如 tdd-implement 的 seams 清单确认）
-- 外部阻塞：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
-- 阶段完成：整个阶段的出口条件满足（如 seam 全绿、typecheck 通过、commit 完成）
+When rules disagree, do not invent a merged policy: follow the higher-scope project/user rule for repository policy and the owning skill for its internal protocol.
 
-预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.agents/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
+## Execution
 
-## 运行纪律（长程任务）
+- Continue the active workflow until its stated exit condition, a required user decision, or an external blocker.
+- Progress output does not reset lifecycle state or authorize restarting completed stages.
+- Reuse still-valid evidence; do not repeat equivalent validation or review merely for reassurance.
+- Do not invent build, test, typecheck, commit, or review requirements that are absent from the owning policy.
+- Keep changes local to the requested scope and reuse existing abstractions and dependency direction.
 
-本仓库会话做**长程任务**（Long-Horizon Skill：多阶段/多 seam 串行执行，如 tdd-implement、diagnosing-bugs、improve-codebase-architecture、wayfinder、grill-to-spec、to-spec）时：
+## Documentation Maintenance
 
-- **长程声明**：执行长程技能前，确认技能文本自带长程任务声明与回合连续性规则（Turn Continuity）——阶段内连续动作一回合内完成，不依赖 harness `/goal` 防线。tdd-implement 已内嵌（SKILL.md 声明 + references/stages.md 阶段③规则）。
-- **模型选择**：flash 级模型长程任务卡住概率显著更高；关键长任务优先强模型或 `/goal` 模式。
-- **任务分解（Chunking）**：巨型操作拆小步执行——单次 `write` 超过 ~150 行先写骨架再分批补全；批量 `replace` 超过 ~5 处分批执行，每批后立即验证。tdd-implement 已内嵌该规则（随包分发）。
-- **Git 历史保护（Git History Preservation）**：任何触及 git 的操作必须追加历史、不可改写丢弃。阶段入口记录 `BASE_HEAD=$(git rev-parse HEAD)`，阶段出口与 commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才继续。"目录卫生"仅删本次产生的 `[DEBUG-...]`/一次性脚本等未跟踪临时文件，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认）。
-
-## 执行原则（细则）
-
-- 先澄清边界再实现；任务收敛后直接执行，不做不必要的形式化流程
-- 局部修改、最小充分实现，避免无关扩张
-- 用户当次明确指令优先于历史经验与参考项目
-- 脏工作区不回滚他人改动；遇到未明改动先理解再兼容
-
-## 文档维护（细则）
-
-- 本文件与分文件只记录长期有效、跨任务可复用的工程经验与项目级约定
-- 一次性需求、临时接口选择、用户当次指定方案不沉淀；更换接口/方案视为需求变更，不判定"旧错新对"
-- 仅当问题重复出现、暴露长期约束、影响后续多次开发、用户明确要求沉淀，或涉及安全/构建/测试/发布/架构边界时更新
-- 经验条目包含：标题、触发信号、根因/约束、正确做法、验证方式、适用范围
+- Keep only durable, cross-task rules here.
+- One-off decisions and temporary implementation choices do not become runtime policy.
+- When a repeated failure reveals a missing invariant, prefer enforcing it in the owning skill, test, tool, type, or repository policy rather than duplicating prose across layers.

package/template/.opencode/docs/agents/skill-design.md

@@ -1,37 +1,15 @@
-# Skill Design Spec
+# Skill Design — Deprecated
 
-The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../CONTEXT.md) — reference them there, never restate the definition.
+This file is retained temporarily for compatibility. It is **not** a normative rule source.
 
-This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The four rules below are the preventive measures that came out of that diagnosis and subsequent git-history incidents (see `docs/adr/0003-git-history-preservation.md`). They are repo rules, not advice.
-## Rule 1 — Turn Continuity
+Current ownership is:
 
-Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of its own: the consecutive actions of a stage (red → green → typecheck → next seam) are executed serially **within one turn**, until the stage's exit condition is met. Do not end the turn at "announce the next step" points, and do not wait for the user to say "continue".
+- repository or project execution policy → the active `AGENTS.md`;
+- repository vocabulary and distribution concepts → `CONTEXT.md`;
+- skill-specific lifecycle and state → that skill's `SKILL.md` and live references;
+- TDD semantics → `.agents/skills/tdd/SKILL.md`;
+- full code-review semantics → `.agents/skills/code-review/SKILL.md`.
 
-- State it **positively** (per the negation principle in `writing-for-agents`): describe the target behaviour, never the banned one.
-- It must be **self-contained** — the skill cannot rely on the harness `/goal` line, because no `/goal` exists when the user does not activate one.
-- Every stage ends on a checkable exit condition; reaching it is the only thing that ends the turn.
-- A sub-step going green (e.g. one seam) is not a stage exit — a stage ends only when all of its seams are complete. Progress output does not itself end the turn: output, then keep executing until one of the three endpoints (compliance checkpoint, external blocker, stage exit) is reached.
-- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md), especially the Red-Green continuity section.
+Do not add Git policy, build/test policy, review lifecycle, model-selection rules, or cross-skill orchestration here. New or changed behavior must be owned by the layer that executes it.
 
-## Rule 2 — Model Selection
-
-Flash-class models are markedly more likely to stop prematurely on long-horizon agentic work. For critical long tasks, prefer a stronger model or `/goal` mode. This is a runtime choice, not something a skill text can enforce — record it here so skill authors and session runners share the same guidance.
-
-## Rule 3 — Progress Chunking
-
-Giant turns — a single `write` of a large file, or a batch `replace` of a hundred-plus lines — hit output caps and get truncated mid-work. Chunk the work into small, individually verifiable steps:
-
-- A single `write` over ~150 lines: write the skeleton first, then fill in batches.
-- A batch of more than ~5 `replace`s: split into batches and verify after each batch.
-
-These thresholds are experience defaults; adjust them as practice shows better values.
-## Rule 4 — Git History Preservation
-
-Every skill that touches git must preserve history after `BASE_HEAD`: history may only be appended, never rewritten or dropped. The skill must record `BASE_HEAD=$(git rev-parse HEAD)` at stage entry, and verify `git merge-base --is-ancestor $BASE_HEAD HEAD` at every stage exit and before any commit — failure means history was rewritten and the skill must recover via `git reflog` before continuing.
-
-To achieve "directory clean" (`git status` clean) the skill may only delete its own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files) — it must never use git-level destructive commands to reach a clean state. The following are forbidden without explicit user confirmation: `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked` (use `--keep-index` instead and `pop` with verification), `git push --force`, `git rebase -i` and any `reset`/`checkout` that moves `HEAD` backward.
-
-Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) checks `BASE_HEAD` at every delivery-stage exit and before the Finalize commit; multi-issue enforcement lives in [`tdd-implement/references/orchestration.md`](.agents/skills/tdd-implement/references/orchestration.md) A2-A4. Repository-local commit gating remains a workspace-only concern and is not part of the distributable template.
-## Long-horizon skills inventory
-
-Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — orchestration for diagnosis + TDD fix), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec` (fixed — carries its own Turn Continuity rule), `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.
+This compatibility file can be removed once no maintained consumer depends on its path.

package/template/.pi/CONTEXT.md

@@ -1,6 +1,6 @@
 # matt-skills
 
-The domain vocabulary for this repo — two sections: how this repository is positioned (`## Repository`) and the terms that govern how long-horizon skills are written, reviewed, and evolved (`## Skill Design`). Every term here is a single source of truth; skills and docs reference it rather than restating the definition.
+Repository vocabulary for this project. This file defines domain terms only; execution policy belongs to the active `AGENTS.md`, and skill-specific behavior belongs to each live `SKILL.md` and its references.
 
 ## Repository
 
@@ -9,47 +9,29 @@ This repository's identity. It is the config repo for mattpocock/skills: it dist
 _Avoid_: skill distribution repo
 
 **Upstream Repository** (上游仓库):
-mattpocock/skills — the source of the 26 Skill bodies (skills/engineering + skills/productivity) that are mirrored into this repo's Workspace canonical Skill source and then distributed by the CLI. This repo syncs them via `scripts/sync-upstream.js` and `matt-skills sync`.
+mattpocock/skills — the source of the upstream Skill bodies mirrored into this repo's Workspace canonical Skill source and then distributed by the CLI. This repo syncs them via `scripts/sync-upstream.js` and `matt-skills sync`.
 _Avoid_: source repo, skill origin
 
 **Proprietary Skill** (独有技能):
-A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check, scaffold-functional-test and show-me). Before adding a new skill, check the Upstream Repository first; only skills absent there qualify as proprietary. The 7 proprietary skills are classified as 5 distributable (`tdd-implement`, `diagnose-fix`, `grill-to-spec`, `scaffold-functional-test`, `show-me`) and 2 repo-local (`ci-guard`, `commit-check`). The default programming set includes 4 proprietary skills: `tdd-implement`, `diagnose-fix`, `grill-to-spec` and `show-me`; `scaffold-functional-test` is distributable but optional. Repo-local skills serve matt-skills maintenance and are never distributed. The issue-audit subagent is NOT a skill: it ships as a subagent + command under `.opencode/` and is distributed through the Template Snapshot without a skill directory.
+A skill that does not exist upstream and lives only in this repo. The current proprietary set is classified in `config/proprietary.json` as distributable or repo-local; that config is the source of truth for membership. Repo-local skills serve matt-skills maintenance and are never distributed. Before adding a new proprietary skill, check the Upstream Repository first.
 _Avoid_: private skill, local skill
 
 **Workspace** (工作区):
-The root-level working copies of the template content — `.agents/skills/` (upstream plus all proprietary Skills, the canonical shared Skill source), `.opencode/` (issue-audit agent, explicit-Skill commands), `.pi/` (pi-agent prompts: `issue-audit`), `AGENTS.md`, `CONTEXT.md`, `docs/`. This is where the repo's own sessions load, modify and test the content. The Template Snapshot projects only the distributable configuration and skeleton: `.opencode/commands/*.md` → `template/.opencode/commands/`, `.pi/prompts/issue-audit.md` → `template/.pi/prompts/issue-audit.md`, and root-level `CONTEXT.md` and `docs/agents/` → `template/.opencode/` + `template/.pi/`. The CLI assembles selected shared Skills from the canonical source into a Target Repository. Harness-specific Skill dirs `.pi/skills/` and `.opencode/skills/` are reserved for project-local custom Skills (empty placeholders with `.gitkeep` + `README.md` in the Template Snapshot).
+The root-level canonical working area: `.agents/skills/` for shared Skills, `.opencode/` and `.pi/` for harness configuration, plus repository docs and configuration. Shared Skills are authored here. Harness-specific `.pi/skills/` and `.opencode/skills/` are reserved for project-local custom Skills rather than shared mirrors.
 _Avoid_: working copy, source repo
 
 **Template Snapshot** (模板快照):
-Everything under `template/` — the distributable snapshot of project skeleton content: harness Skill dirs `.pi/skills/` + `.opencode/skills/` as empty placeholders for project custom Skills, distributable opencode commands under `.opencode/commands/`, the pi issue-audit command under `.pi/prompts/`, discipline files and glossary under `.opencode/` + `.pi/`, and AGENTS.md at the top level. It is generated by `node scripts/build-template.js` and used to initialize other repositories. Shared Skills and repo-local Skills remain in the Workspace; the CLI distributes only the selected shared Skills. The sync direction for the skeleton is one-way: Workspace → Template Snapshot. Template structure tests guard the content the snapshot owns.
+Everything under `template/` that is generated or copied from Workspace sources for Target Repository initialization. The snapshot owns project skeleton/configuration, while shared Skills are assembled separately by the CLI from the Workspace canonical source. Skeleton sync is one-way: Workspace → Template Snapshot.
 _Avoid_: release snapshot, published snapshot
 
 **Target Repository** (目标仓库):
-A repository initialized by copying the Template Snapshot skeleton into its root and then receiving selected distributable shared Skills from the CLI. It loads shared Skills from its own `.agents/skills/`, project-local custom Skills from `.pi/skills/` / `.opencode/skills/` (if any), the distributable commands from `.opencode/commands/` (opencode) and the `issue-audit` command from `.pi/prompts/` (pi) / `.opencode/commands/` (opencode), and the project-level global config from `.opencode/` + `.pi/` and AGENTS.md. Repo-local matt-skills maintenance Skills are not part of a Target Repository by default.
+A repository initialized from the Template Snapshot and selected distributable shared Skills. Its root `AGENTS.md` is the project-level execution policy. Shared Skills live in `.agents/skills/`; project-local custom Skills may live in harness-specific skill directories.
 _Avoid_: inheriting repo, child repo
 
 **Initialize** (初始化):
-The one-time action of setting up a Target Repository: copying the Template Snapshot skeleton into its root, then having the CLI create its shared Skill directory and copy the selected distributable Skills from the Workspace canonical source. No separate upstream fetch is needed. Repo-local Skills are intentionally absent. Copying, not inheriting — no runtime relationship survives the copy.
+The one-time action of setting up a Target Repository by copying the Template Snapshot skeleton and installing the selected distributable Skills. Repo-local Skills are intentionally excluded.
 _Avoid_: inherit, bootstrap
 
 **Sync** (同步):
-`matt-skills sync` 同步 Target Repository 的 skeleton 与 Skills：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，canonical shared Skills 按默认 programming 范围覆盖但不删多余，Template Snapshot 的 `.opencode` / `.pi` 配置增量 add/update，`.pi/skills` 与 `.opencode/skills` 中已有的 project-local Skill 不按名称删除，避免把项目自定义 Skill 误删）、`--all` 仅更新同名可分发 Skill 内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余 Skill。Repo-local Skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
+`matt-skills sync` updates Target Repository skeleton/configuration and selected distributable Skills according to CLI policy. Default sync preserves project customization where the CLI can identify it; `--all` applies the broader distributable scope. Repo-local Skills are never newly distributed by sync.
 _Avoid_: update, force sync
-
-## Skill Design
-
-**Turn Continuity** (回合连续性):
-The rule that a long-horizon skill must carry a positive instruction to keep executing within a turn — red → green → typecheck → next seam serial in one turn until the stage's exit condition is met. The stage exit is reached when all of its seams are complete — one seam going green is not an exit, and progress output does not itself end the turn. It is the skill's own guard against premature turn-end; it must not rely on the harness `/goal` line (which does not exist when no `/goal` is active).
-_Avoid_: keep going, don't stop
-
-**Chunking** (拆小步 / 进度编排):
-Splitting a giant turn — one large `write` or a batch of `replace`s — into small steps that are individually verified before continuing, so the turn never hits output caps and gets truncated mid-work.
-_Avoid_: step-by-step, take it slow
-
-**Git History Preservation** (Git 历史保护):
-Every git-touching skill must preserve history after `BASE_HEAD=$(git rev-parse HEAD)` recorded at stage entry — history may only be appended. Before any commit or stage exit, verify `git merge-base --is-ancestor $BASE_HEAD HEAD`; if it fails, history was rewritten and must be recovered via `git reflog` before continuing. "Directory clean" (`git status` clean) may only be achieved by deleting the skill's own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files); destructive git commands `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked`, `git push --force`, `git rebase -i` are forbidden without explicit user confirmation.
-_Avoid_: force clean, stash all
-
-**Long-Horizon Skill** (长程多阶段技能):
-A skill whose run spans multiple stages or seams executed continuously (e.g. tdd-implement, diagnosing-bugs, improve-codebase-architecture, wayfinder, grill-to-spec, to-spec). The class of skill that must carry a Turn Continuity rule.
-_Avoid_: complex skill, big skill

package/template/.pi/docs/agents/runtime-discipline.md

@@ -1,37 +1,26 @@
 # Runtime Discipline
 
-本仓库会话的运行时纪律，执行口径源自 `docs/agents/skill-design.md` 的四条规则（规范正文）。术语定义见 `CONTEXT.md`。
+This file contains only general execution discipline. It does not override the active project `AGENTS.md` or any skill-specific lifecycle.
 
-## 回合连续性规则
+## Ownership
 
-每个逻辑单元（红-绿循环、typecheck、测试修复）必须在一个回合内连续执行完毕后才输出：测试 → 分析失败 → 修正 → 重跑 → 全绿整条链一气呵成，中途不输出、不停止、不等用户"继续"。
+- authorization, validation scope, review scope and Git policy come from the active `AGENTS.md` and explicit user instructions;
+- a skill owns only its own lifecycle, state transitions and exit conditions;
+- TDD semantics belong to `.agents/skills/tdd/SKILL.md`;
+- full code-review semantics belong to `.agents/skills/code-review/SKILL.md`.
 
-输出只允许发生在三种情况：
-- 合规交互点：技能/流程要求的用户确认（如 tdd-implement 的 seams 清单确认）
-- 外部阻塞：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
-- 阶段完成：整个阶段的出口条件满足（如 seam 全绿、typecheck 通过、commit 完成）
+When rules disagree, do not invent a merged policy: follow the higher-scope project/user rule for repository policy and the owning skill for its internal protocol.
 
-预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.agents/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
+## Execution
 
-## 运行纪律（长程任务）
+- Continue the active workflow until its stated exit condition, a required user decision, or an external blocker.
+- Progress output does not reset lifecycle state or authorize restarting completed stages.
+- Reuse still-valid evidence; do not repeat equivalent validation or review merely for reassurance.
+- Do not invent build, test, typecheck, commit, or review requirements that are absent from the owning policy.
+- Keep changes local to the requested scope and reuse existing abstractions and dependency direction.
 
-本仓库会话做**长程任务**（Long-Horizon Skill：多阶段/多 seam 串行执行，如 tdd-implement、diagnosing-bugs、improve-codebase-architecture、wayfinder、grill-to-spec、to-spec）时：
+## Documentation Maintenance
 
-- **长程声明**：执行长程技能前，确认技能文本自带长程任务声明与回合连续性规则（Turn Continuity）——阶段内连续动作一回合内完成，不依赖 harness `/goal` 防线。tdd-implement 已内嵌（SKILL.md 声明 + references/stages.md 阶段③规则）。
-- **模型选择**：flash 级模型长程任务卡住概率显著更高；关键长任务优先强模型或 `/goal` 模式。
-- **任务分解（Chunking）**：巨型操作拆小步执行——单次 `write` 超过 ~150 行先写骨架再分批补全；批量 `replace` 超过 ~5 处分批执行，每批后立即验证。tdd-implement 已内嵌该规则（随包分发）。
-- **Git 历史保护（Git History Preservation）**：任何触及 git 的操作必须追加历史、不可改写丢弃。阶段入口记录 `BASE_HEAD=$(git rev-parse HEAD)`，阶段出口与 commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才继续。"目录卫生"仅删本次产生的 `[DEBUG-...]`/一次性脚本等未跟踪临时文件，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认）。
-
-## 执行原则（细则）
-
-- 先澄清边界再实现；任务收敛后直接执行，不做不必要的形式化流程
-- 局部修改、最小充分实现，避免无关扩张
-- 用户当次明确指令优先于历史经验与参考项目
-- 脏工作区不回滚他人改动；遇到未明改动先理解再兼容
-
-## 文档维护（细则）
-
-- 本文件与分文件只记录长期有效、跨任务可复用的工程经验与项目级约定
-- 一次性需求、临时接口选择、用户当次指定方案不沉淀；更换接口/方案视为需求变更，不判定"旧错新对"
-- 仅当问题重复出现、暴露长期约束、影响后续多次开发、用户明确要求沉淀，或涉及安全/构建/测试/发布/架构边界时更新
-- 经验条目包含：标题、触发信号、根因/约束、正确做法、验证方式、适用范围
+- Keep only durable, cross-task rules here.
+- One-off decisions and temporary implementation choices do not become runtime policy.
+- When a repeated failure reveals a missing invariant, prefer enforcing it in the owning skill, test, tool, type, or repository policy rather than duplicating prose across layers.

package/template/.pi/docs/agents/skill-design.md

@@ -1,37 +1,15 @@
-# Skill Design Spec
+# Skill Design — Deprecated
 
-The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../CONTEXT.md) — reference them there, never restate the definition.
+This file is retained temporarily for compatibility. It is **not** a normative rule source.
 
-This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The four rules below are the preventive measures that came out of that diagnosis and subsequent git-history incidents (see `docs/adr/0003-git-history-preservation.md`). They are repo rules, not advice.
-## Rule 1 — Turn Continuity
+Current ownership is:
 
-Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of its own: the consecutive actions of a stage (red → green → typecheck → next seam) are executed serially **within one turn**, until the stage's exit condition is met. Do not end the turn at "announce the next step" points, and do not wait for the user to say "continue".
+- repository or project execution policy → the active `AGENTS.md`;
+- repository vocabulary and distribution concepts → `CONTEXT.md`;
+- skill-specific lifecycle and state → that skill's `SKILL.md` and live references;
+- TDD semantics → `.agents/skills/tdd/SKILL.md`;
+- full code-review semantics → `.agents/skills/code-review/SKILL.md`.
 
-- State it **positively** (per the negation principle in `writing-for-agents`): describe the target behaviour, never the banned one.
-- It must be **self-contained** — the skill cannot rely on the harness `/goal` line, because no `/goal` exists when the user does not activate one.
-- Every stage ends on a checkable exit condition; reaching it is the only thing that ends the turn.
-- A sub-step going green (e.g. one seam) is not a stage exit — a stage ends only when all of its seams are complete. Progress output does not itself end the turn: output, then keep executing until one of the three endpoints (compliance checkpoint, external blocker, stage exit) is reached.
-- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md), especially the Red-Green continuity section.
+Do not add Git policy, build/test policy, review lifecycle, model-selection rules, or cross-skill orchestration here. New or changed behavior must be owned by the layer that executes it.
 
-## Rule 2 — Model Selection
-
-Flash-class models are markedly more likely to stop prematurely on long-horizon agentic work. For critical long tasks, prefer a stronger model or `/goal` mode. This is a runtime choice, not something a skill text can enforce — record it here so skill authors and session runners share the same guidance.
-
-## Rule 3 — Progress Chunking
-
-Giant turns — a single `write` of a large file, or a batch `replace` of a hundred-plus lines — hit output caps and get truncated mid-work. Chunk the work into small, individually verifiable steps:
-
-- A single `write` over ~150 lines: write the skeleton first, then fill in batches.
-- A batch of more than ~5 `replace`s: split into batches and verify after each batch.
-
-These thresholds are experience defaults; adjust them as practice shows better values.
-## Rule 4 — Git History Preservation
-
-Every skill that touches git must preserve history after `BASE_HEAD`: history may only be appended, never rewritten or dropped. The skill must record `BASE_HEAD=$(git rev-parse HEAD)` at stage entry, and verify `git merge-base --is-ancestor $BASE_HEAD HEAD` at every stage exit and before any commit — failure means history was rewritten and the skill must recover via `git reflog` before continuing.
-
-To achieve "directory clean" (`git status` clean) the skill may only delete its own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files) — it must never use git-level destructive commands to reach a clean state. The following are forbidden without explicit user confirmation: `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked` (use `--keep-index` instead and `pop` with verification), `git push --force`, `git rebase -i` and any `reset`/`checkout` that moves `HEAD` backward.
-
-Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) checks `BASE_HEAD` at every delivery-stage exit and before the Finalize commit; multi-issue enforcement lives in [`tdd-implement/references/orchestration.md`](.agents/skills/tdd-implement/references/orchestration.md) A2-A4. Repository-local commit gating remains a workspace-only concern and is not part of the distributable template.
-## Long-horizon skills inventory
-
-Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — orchestration for diagnosis + TDD fix), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec` (fixed — carries its own Turn Continuity rule), `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.
+This compatibility file can be removed once no maintained consumer depends on its path.

package/template/AGENTS.md

@@ -1,5 +1,7 @@
 # AGENTS.md
 
+<!-- matt-skills:managed:start -->
+
 ## Workflow
 
 按任务目标选择 skill / 工具，并用一行声明：
@@ -82,3 +84,5 @@ codegraph node "<符号>"
 ## Completion
 
 有实际修改时说明：改动、验证、未验证项 / 风险、commit hash（如有）。
+
+<!-- matt-skills:managed:end -->