specdojo 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -4
  2. package/CHANGELOG.md +31 -0
  3. package/dist/commands/init.js +33 -7
  4. package/dist/devcontainer/scaffold.js +5 -1
  5. package/dist/exec/evidence.js +35 -3
  6. package/dist/exec/pipeline-state.js +1 -0
  7. package/dist/exec/plans-core.js +18 -2
  8. package/dist/exec/plans-generation.js +1 -1
  9. package/dist/exec/register-resume.js +8 -4
  10. package/dist/exec/register.js +47 -14
  11. package/dist/exec/reporter.js +8 -1
  12. package/dist/exec/results.js +1 -1
  13. package/dist/exec/run/agent-pipeline.js +7 -5
  14. package/dist/exec/run/agent.js +14 -1
  15. package/dist/exec/run/in-place.js +7 -4
  16. package/dist/exec/run/register-core.js +10 -2
  17. package/dist/exec/run/register-resume.js +1 -0
  18. package/dist/exec/run/register-worktree.js +7 -1
  19. package/dist/exec/task-repos.js +11 -0
  20. package/dist/exec/worktree-ops-lifecycle.js +4 -2
  21. package/dist/kata/command.js +54 -9
  22. package/dist/register/approach.js +13 -12
  23. package/dist/register/authoring-sources.js +132 -0
  24. package/dist/register/core.js +1 -0
  25. package/dist/register/create-commands.js +84 -15
  26. package/dist/register/events.js +2 -0
  27. package/dist/register/external-project.js +29 -8
  28. package/dist/register/item.js +6 -0
  29. package/dist/register/renumber.js +3 -3
  30. package/dist/register/views.js +3 -0
  31. package/dist/shared/git.js +3 -2
  32. package/dist/shared/lefthook-scaffold.js +5 -22
  33. package/dist/shared/markdownlint-scaffold.js +67 -0
  34. package/dist/shared/provider-scaffold.js +2 -2
  35. package/dist/shared/slidev-scaffold.js +102 -0
  36. package/dist/shared/specdojo-config.js +9 -3
  37. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +7 -7
  38. package/docs/ja/specdojo/exec-templates/xep-register-template.md +5 -4
  39. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +7 -7
  40. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +7 -7
  41. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +7 -7
  42. package/docs/ja/specdojo/guides/exec-config-guide.md +46 -16
  43. package/docs/ja/specdojo/guides/kata-guide.md +111 -2
  44. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +6 -6
  45. package/docs/ja/specdojo/guides/quick-start-guide.md +4 -2
  46. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
  47. package/docs/ja/specdojo/references/command-reference.md +155 -59
  48. package/docs/ja/specdojo/references/specdojo-config-reference.md +2 -0
  49. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +17 -1
  50. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +4 -3
  51. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +3 -3
  52. package/docs/specdojo/schemas/v1/register-events.schema.yaml +1 -0
  53. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +31 -3
  54. package/package.json +8 -7
  55. package/templates/antigravity/orchestrator.md +4 -4
  56. package/templates/claude/README.md +2 -0
  57. package/templates/claude/agents/specdojo-orchestrator.md +4 -4
  58. package/templates/codex/README.md +38 -9
  59. package/templates/codex/agents/codex-executor.toml +1 -1
  60. package/templates/codex/agents/codex-expert-executor.toml +1 -1
  61. package/templates/codex/agents/codex-expert-review-executor.toml +1 -1
  62. package/templates/codex/agents/codex-review-executor.toml +1 -1
  63. package/templates/codex/agents/specdojo-orchestrator.toml +5 -5
  64. package/templates/codex/orchestrator.md +4 -4
  65. package/templates/init-agent-members.yaml +85 -13
  66. package/templates/opencode/agents/specdojo-orchestrator.md +4 -4
@@ -169,12 +169,12 @@ npx specdojo exec validate --project <project-id>
169
169
  - 統合の後に `src` が dist より新しくなると、次の run は始まる前に止まる。dist を作り直してから流す。
170
170
  - 記帳は `register ... --commit` で行う。登録簿の lifecycle のロックを取るため、実行中の run と取り合わない。
171
171
  - 個票の本文を書き換えて普通に commit するのは、統合中の run がないときだけにする(`.git/index.lock` を確かめる)。commit に失敗したら、index に載ったファイルを残さない。残ると次の run の checkpoint が止まる。
172
- - 保護された設定(agent の定義・名簿・`exec-defaults.yaml`・`package.json` など)は、executor が書き換えると統合の前に止まる。完了条件で「案を result に書く」と指示し、反映は利用者の承認のもと feature ブランチで行う。
172
+ - 保護された設定(agent の定義・名簿・`exec-defaults.yaml`・`package.json` など)は、executor が書き換えると統合の前に止まる。register の完了条件では「案を個票の対応結果に書き、pipeline では報告の `handoff` にも書く」と指示する。「案を result に書く」は executor が result を直接書ける実行形式に限る。反映は利用者の承認のもと feature ブランチで行う。
173
173
  - プロジェクトの文書にオーケストレーター向けの運用メモがあれば、作業を始める前に読む。
174
174
 
175
175
  ## close の前の確かめ方
176
176
 
177
- - 完了条件を 1 項目ずつ、差分(`git show`)と result に照らして確かめる。親の検証が通っただけで close しない。
177
+ - 完了条件を 1 項目ずつ、差分(`git show`)と個票の対応結果と result の両方に照らして確かめる。完了条件が求める記録を result だけで未達と判定せず、個票の対応結果にもあるかを確認する。親の検証が通っただけで close しない。
178
178
  - agent の「直した」「反映済み」という報告は、実物(ファイルの中身、生成物、コマンドの出力)で確かめる。agent は、権限で編集を拒まれたあとでも完了と報告することがある。
179
179
  - 完了条件にない変更(特に保護された設定や、利用者の環境に関わる設定)が入っていないかを確かめる。
180
180
  - runner や CLI の動きを変えた項目は、統合の後に実際の `exec run --register` を 1 回流して動作を確かめてから close する。生成物を変えた項目は、空のリポジトリで生成して確かめる。
@@ -198,8 +198,8 @@ npx specdojo exec validate --project <project-id>
198
198
  - 検証できる形で書く。完了条件は `exec plan` の入力になり、曖昧だと agent が意図と違う範囲を実装する。
199
199
  - 作業を終える前に流す検査(型検査・lint・単体テスト)と、通すべき親の検証を書く。
200
200
  - CHANGELOG は未公開の版の節に書き、公開済みの版の節を変えないと書く。
201
- - 保護された設定に触れる場合は、案を result に書き、反映は利用者が行うと書く。
202
- - 未決の点は `_UNDECIDED_` で残すか、executor に決めさせて理由を result に書かせるかを明記する。
201
+ - 保護された設定に触れる場合、register の項目では案を個票の対応結果に書き、pipeline では報告の `handoff` にも書く。反映は利用者の承認のもとで行うと書く。「result に書く」は executor が result を直接書ける実行形式に限る。
202
+ - 未決の点は `_UNDECIDED_` で残すか、executor に決めさせて理由を記録させるかを明記する。register の項目では個票の対応結果に書かせ、pipeline では報告の `handoff` にも書かせる。「result に書く」は executor が result を直接書ける実行形式に限る。
203
203
  - Markdown では、`*` や `_` を含む語(glob など)をコードの書式にする。コードの書式の中を空白で始めたり終えたりしない。
204
204
 
205
205
  ## agent の選び方
package/CHANGELOG.md CHANGED
@@ -2,6 +2,37 @@
2
2
 
3
3
  SpecDojo の利用者に影響する変更を記録します。
4
4
 
5
+ ## [0.4.6] - 2026-10-25
6
+
7
+ ### 追加機能
8
+
9
+ - `init --slidev` と `config scaffold --slidev` で、Slidev 本体・Prettier plugin と kata 用の整形・markdownlint 除外設定を追加できるようにしました。既存設定・依存は保持し、追加内容を表示します。`init` の Dev Container preset が `full` の場合は Slidev 導入を既定で選び、`--no-slidev` で解除できます。`full` の VS Code 拡張に `antfu.slidev` を追加しました(PJR-84F7)。
10
+
11
+ ### 変更
12
+
13
+ - 同梱のオーケストレーターの本文で、register の完了条件の記録の書き先を「個票の対応結果」と報告の `handoff` にし、close の前に result だけでなく個票の対応結果も確かめるようにしました(PJR-R1FB)。
14
+ - `specdojo init --exec` が書く agent の名簿の雛形を、GPT-6 の系統と normal・expert の 2 段にそろえました。codex の normal は `gpt-6-luna` の `luna-executor`・`luna-review-executor`・`luna-reporter`、expert は `gpt-6.1-sol` の `sol-executor`・`sol-review-executor` です。claude には expert の `opus-executor`・`opus-review-executor` を加えました。別名 `claude-expert-executor`・`claude-expert-review-executor`・`codex-expert-executor`・`codex-expert-review-executor` を加え、`codex-executor` などの既存の別名は `luna-*` を指します。振り分けの表(`routing`)は hard を expert の別名、medium と easy と reporter を normal の別名にします。`init` と `config scaffold` が加える codex の起動スクリプトは `orch:sol`(`gpt-6.1-sol`)と `orch:luna`(`gpt-6-luna`)になり、`orch:terra` は作りません(PJR-9482)。
15
+ - 配布する `templates/codex/agents/*.toml` のモデルを名簿の雛形と同じ GPT-6 の系統へ引き上げました。`codex-executor`・`codex-review-executor` は `gpt-6-luna`(`medium`)、`codex-expert-executor`・`codex-expert-review-executor` は `gpt-6.1-sol`(`high`)、`specdojo-orchestrator` は `gpt-6.1-sol`(`medium`)です。既存の `.codex/agents/*.toml` は上書きされないため、移行する場合は `specdojo config scaffold --provider codex --force` で再配置するか、各ファイルの `model` を手動で書き換えます(PJR-EVAQ)。
16
+ - 既存の `.specdojo/agent-members.yaml`・`.specdojo/exec-defaults.yaml`・`package.json` は書き換えません。新しい名前へそろえる場合は、名簿の `terra-*` を `luna-*`(`model: gpt-6-luna`)へ、`sol-*` の `model` を `gpt-6.1-sol` へ変え、`aliases` の向き先を合わせます。`package.json` の `orch:terra` は `orch:luna`(`-m gpt-6-luna`)へ、`orch:sol` は `-m gpt-6.1-sol` へ手で直します。手順は exec 設定ガイドの `agent の名簿の 2 段構成と移行` にあります。
17
+
18
+ ### 不具合修正
19
+
20
+ - 登録簿に項目が 1 件もないとき、`register build` が生成する担当者別と状態別の派生ビューの空の章で空行が連続し、markdownlint の `MD012` に当たる問題を直しました。項目のない章には「該当なし」を書きます。項目がある場合の生成物は変わりません(PJR-ZG0A)。
21
+ - `init --lefthook` と `config scaffold --lefthook` の基本設定を `.markdownlintrc` に変更し、これを読み込む `.markdownlint-cli2.yaml` も生成するようにしました。VS Code で CLI2 のファイル別 overrides が効き、`--slidev` は kata の glob に Slidev 用の規則を当てます。commit hook と result 検査は markdownlint-cli を使い続けます。既存設定は保持し、追加例と移行手順を案内します(PJR-50YH)。
22
+ - executor の報告に省略可能な `completion_status`(`complete` / `incomplete`)を追加しました。未完了を申告した register 項目は終了コード 0 でも `waiting` となり、理由と残作業、worktree を保持して統合を止めます。`--resume --resume-from executor` で再開でき、欄のない既存報告は従来どおり扱います(PJR-XTE6)。
23
+ - `kata list`・`kata status` の kata 候補と `kata eject` の ID 選択を `.md`・`.mdx`・`.yaml`・`.yml`・`.json` にそろえ、同名 CSS などを別の kata として扱わないようにしました。`kata eject`・`kata install --all` は同名の付属ファイルと同名ディレクトリ内の画像などもコピーし、`--dry-run`・`--force` をファイルごとに適用します。付属ファイルだけの差分も親 kata の `modified` に含めます(PJR-6HS2)。
24
+ - `register update` で approach・target・source を変更しない場合、記録済みの組み合わせを再検証しないようにしました。authoring の kata が作成された後も、担当・期限・優先度などの更新を続けられます。approach 関連の値を変更する場合と `register add` では従来どおり検証します(PJR-JJBY)。
25
+ - executor の報告に省略可能な `handoff`(申し送り)を追加し、reporter の処理後に runner が edit result の申し送りへ確実に転記するようにしました。register の plan も、result への記載を求める完了条件を個票の対応結果と報告の `handoff` に記録するようにしました。`handoff` のない既存の報告も引き続き受け付けます(PJR-R1FB)。
26
+ - `external_projects` で SpecDojo 自身のリポジトリへ起票できるようにしました。相手に `node_modules/.bin/specdojo` がなく、`package.json` の `name` が `specdojo` の場合は `node <相手>/dist/specdojo.js` を使います。未ビルドの場合は `npm run build` を案内して停止します(PJR-PM2R)。
27
+ - 着手の checkpoint・待ち状態の記帳・統合の commit が hook で失敗したとき、空白を含む step 名(`lint Markdown documentation` など)でも、成功した Prettier の step ではなく、失敗印の付いた step と最初の error の行を要約するようにしました。checkpoint の失敗要約を補足説明より前に置き、`block_reason` にも原因を残します(PJR-68KR)。
28
+ - owner の role に当てはまるレビュー観点がないとき(カタログや `pm-roles.yaml`・`pm-review-viewpoints.yaml` がない project など)、edit plan のレビュー観点の欄を `_MISSING_` だけの段落ではなく箇条書きの 1 項目(`- _MISSING_`)にしました。`rulebook-maintenance` などの kata の見直しの plan が、着手の checkpoint の commit で hook の markdownlint(MD036)に止められていました(PJR-SS72)。
29
+
30
+ ## [0.4.5] - 2026-10-24
31
+
32
+ ### 追加機能
33
+
34
+ - kata authoring の手本を `register add` / `register update` の繰り返し可能な `--source` で指定できるようにしました。文書索引の doc id、プロジェクトリポジトリのファイル・ディレクトリ・glob、`repos` で宣言したプロダクトリポジトリの `<repo>:<path>` を使え、カタログがない project でも authoring plan を生成できます(PJR-ZV60)。
35
+
5
36
  ## [0.4.4] - 2026-10-24
6
37
 
7
38
  ### 変更
@@ -6,6 +6,7 @@ import { runScaffold } from "../catalog/scaffold.js";
6
6
  import { runDevcontainerScaffold } from "../devcontainer/scaffold.js";
7
7
  import { runProviderScaffold } from "../shared/provider-scaffold.js";
8
8
  import { runLefthookScaffold } from "../shared/lefthook-scaffold.js";
9
+ import { runSlidevScaffold, SLIDEV_KATA_PATTERNS } from "../shared/slidev-scaffold.js";
9
10
  import { generateDerivedViewFiles } from "../register/register.js";
10
11
  import { defaultWorktreeBase, projectGitignoreLayout, specdojoRootDir, } from "../shared/specdojo-config.js";
11
12
  import { ensureGitignore, formatGitignoreReport, gitignorePatternsForLayouts, } from "../shared/specdojo-gitignore.js";
@@ -147,6 +148,7 @@ export async function collectInitAnswers(options, prompter) {
147
148
  catalog: parseCatalog(options.catalog),
148
149
  devcontainer,
149
150
  lefthook: !!options.lefthook,
151
+ slidev: options.slidev ?? (devcontainer && devcontainerPreset === "full"),
150
152
  ...(devcontainerPreset ? { devcontainerPreset } : {}),
151
153
  });
152
154
  for (const [label, used] of [
@@ -160,6 +162,7 @@ export async function collectInitAnswers(options, prompter) {
160
162
  ["catalog=none", !options.catalog],
161
163
  ["devcontainer=no", !options.devcontainer],
162
164
  ["lefthook=no", !options.lefthook],
165
+ [`slidev=${answers.slidev ? "yes" : "no"}`, options.slidev === undefined],
163
166
  ["devcontainer-preset=recommended", devcontainer && options.devcontainerPreset === undefined],
164
167
  ]) {
165
168
  if (used)
@@ -196,6 +199,8 @@ export async function collectInitAnswers(options, prompter) {
196
199
  ? await promptUntilValid(prompter, "Dev Container preset (minimal, recommended, full) [recommended]: ", (answer) => parseDevcontainerPreset(answer.trim() || "recommended"))
197
200
  : explicitDevcontainerPreset;
198
201
  const lefthook = await promptUntilValid(prompter, `Create Git hooks with lefthook? [${lefthookDefault ? "Y/n" : "y/N"}]: `, (answer) => parseBoolean(answer, lefthookDefault));
202
+ const slidevDefault = options.slidev ?? (devcontainer && devcontainerPreset === "full");
203
+ const slidev = await promptUntilValid(prompter, `Set up Slidev for kata? [${slidevDefault ? "Y/n" : "y/N"}]: `, (answer) => parseBoolean(answer, slidevDefault));
199
204
  return validateAnswers({
200
205
  projectId,
201
206
  projectName,
@@ -207,6 +212,7 @@ export async function collectInitAnswers(options, prompter) {
207
212
  catalog,
208
213
  devcontainer,
209
214
  lefthook,
215
+ slidev,
210
216
  ...(devcontainerPreset ? { devcontainerPreset } : {}),
211
217
  });
212
218
  }
@@ -341,28 +347,42 @@ function writeExecConfiguration(repoRoot, packageRoot, providers, dryRun) {
341
347
  const selected = new Set(providers);
342
348
  const members = memberTemplate.members.filter((member) => member.provider && selected.has(member.provider));
343
349
  const aliases = selectAliases(memberTemplate.aliases ?? [], new Set(members.map((member) => member.nickname)));
350
+ // normal の段(medium・easy と全 reporter)と expert の段(hard)を provider ごとに選ぶ。
351
+ // expert の段がない provider(opencode・antigravity など)は hard も normal の段を使う。
344
352
  const pairs = providers.map((provider) => {
345
- const executor = members.find((member) => member.provider === provider && member.stage_role === "executor" && member.mode === "edit");
346
- const reporter = members.find((member) => member.provider === provider && member.stage_role === "reporter");
353
+ const executor = members.find((member) => member.provider === provider &&
354
+ member.stage_role === "executor" &&
355
+ member.mode === "edit" &&
356
+ member.proficiency !== "expert");
357
+ const expertExecutor = members.find((member) => member.provider === provider &&
358
+ member.stage_role === "executor" &&
359
+ member.mode === "edit" &&
360
+ member.proficiency === "expert");
361
+ const reporter = members.find((member) => member.provider === provider &&
362
+ member.stage_role === "reporter" &&
363
+ member.proficiency !== "expert");
347
364
  if (!executor || !reporter) {
348
365
  throw new Error(`init-agent-members.yaml must define an edit executor and reporter for ${provider}`);
349
366
  }
367
+ const normalExecutor = preferredAgentName(executor, aliases);
350
368
  return {
351
- executor: preferredAgentName(executor, aliases),
369
+ executor: normalExecutor,
370
+ hardExecutor: expertExecutor ? preferredAgentName(expertExecutor, aliases) : normalExecutor,
352
371
  reporter: preferredAgentName(reporter, aliases),
353
372
  };
354
373
  });
355
- const route = (pairIndex, action) => {
374
+ const route = (pairIndex, action, tier = "normal") => {
375
+ const executorOf = (pair) => tier === "expert" ? pair.hardExecutor : pair.executor;
356
376
  const resolvedIndex = Math.min(pairIndex, pairs.length - 1);
357
377
  const pair = pairs[resolvedIndex];
358
378
  const fallback = pairs.length > 1 ? pairs[(resolvedIndex + 1) % pairs.length] : undefined;
359
379
  return {
360
- executor_by: pair.executor,
380
+ executor_by: executorOf(pair),
361
381
  reporter_by: pair.reporter,
362
382
  on_rate_limit: action === "fallback" && !fallback ? "stop" : action,
363
383
  ...(fallback
364
384
  ? {
365
- fallback_executor_by: fallback.executor,
385
+ fallback_executor_by: executorOf(fallback),
366
386
  fallback_reporter_by: fallback.reporter,
367
387
  }
368
388
  : {}),
@@ -378,7 +398,7 @@ function writeExecConfiguration(repoRoot, packageRoot, providers, dryRun) {
378
398
  const configuredDefaults = {
379
399
  ...commonDefaults,
380
400
  routing: {
381
- hard: route(0, "wait"),
401
+ hard: route(0, "wait", "expert"),
382
402
  medium: route(1, "fallback"),
383
403
  easy: route(2, "fallback"),
384
404
  },
@@ -531,10 +551,14 @@ export async function runInit(options, deps) {
531
551
  packageRoot,
532
552
  repoRoot,
533
553
  config,
554
+ slidevKataPatterns: answers.slidev ? SLIDEV_KATA_PATTERNS : [],
534
555
  force: false,
535
556
  dryRun,
536
557
  });
537
558
  }
559
+ if (answers.slidev) {
560
+ await runSlidevScaffold({ repoRoot, dryRun });
561
+ }
538
562
  const firstProvider = answers.providers[0];
539
563
  const script = firstProvider === "claude"
540
564
  ? "orch:opus"
@@ -570,6 +594,8 @@ export function registerInitCommand(program) {
570
594
  .option("--catalog <size>", "Create a deliverables catalog (small|medium|large)")
571
595
  .option("--devcontainer", "Create a Dev Container for the selected providers", false)
572
596
  .option("--lefthook", "Create pre-commit hooks for SpecDojo repositories", false)
597
+ .option("--slidev", "Set up Slidev and formatting for kata (default with full preset)")
598
+ .option("--no-slidev", "Skip Slidev setup, including with the full preset")
573
599
  .option("--devcontainer-preset <name>", "Apply a Dev Container preset when creating it (minimal|recommended|full; none aliases minimal)")
574
600
  .option("--workspace-name <name>", "Override the Dev Container workspace parent name used under /workspaces")
575
601
  .option("--dry-run", "Show planned files and changes without writing", false)
@@ -274,7 +274,11 @@ fi`);
274
274
  let vscodeExtensions = [];
275
275
  let extensionsFile;
276
276
  if (includesRecommended) {
277
- vscodeExtensions = unique([...RECOMMENDED_VSCODE_EXTENSIONS, ...providerExtensions(providers)]);
277
+ vscodeExtensions = unique([
278
+ ...RECOMMENDED_VSCODE_EXTENSIONS,
279
+ ...providerExtensions(providers),
280
+ ...(full ? ["antfu.slidev"] : []),
281
+ ]);
278
282
  const customizations = (devcontainer.customizations ??= {});
279
283
  const vscode = (customizations.vscode ??= {});
280
284
  const existingExtensions = Array.isArray(vscode.extensions)
@@ -5,6 +5,8 @@ import { gitOutput } from "./worktree.js";
5
5
  const MAX_LOG_BYTES = 64 * 1024;
6
6
  const MAX_CHANGE_FILES = 1_000;
7
7
  const MAX_FINAL_MESSAGE_LENGTH = 4_000;
8
+ const MAX_HANDOFF_ITEMS = 100;
9
+ const MAX_HANDOFF_LENGTH = 4_000;
8
10
  const MAX_DIFF_SUMMARY_LENGTH = 4_000;
9
11
  const MAX_VALIDATIONS = 50;
10
12
  const MAX_VALIDATION_COMMAND_LENGTH = 500;
@@ -107,12 +109,33 @@ export function parseExecutorReport(stdout) {
107
109
  }
108
110
  }
109
111
  const fallback = stdout.replace(REPORT_PATTERN, "").trim();
112
+ const handoff = Array.isArray(report.handoff)
113
+ ? report.handoff
114
+ .slice(0, MAX_HANDOFF_ITEMS)
115
+ .map((item) => boundedText(item, MAX_HANDOFF_LENGTH))
116
+ .filter(Boolean)
117
+ : [];
110
118
  return {
111
119
  finalMessage: boundedText(report.final_message ?? fallback, MAX_FINAL_MESSAGE_LENGTH),
120
+ ...(report.completion_status !== undefined
121
+ ? {
122
+ completionStatus: report.completion_status === "complete"
123
+ ? "complete"
124
+ : "incomplete",
125
+ }
126
+ : {}),
127
+ handoff,
112
128
  validations,
113
129
  targetCoverage,
114
130
  };
115
131
  }
132
+ /** A successful process or validation batch cannot override an explicit incomplete report. */
133
+ export function executorCompletionFailure(evidence) {
134
+ if (evidence.completion_status !== "incomplete")
135
+ return undefined;
136
+ const detail = boundedText(evidence.final_message, MAX_VALIDATION_SUMMARY_LENGTH);
137
+ return boundedText(detail ? `executor reported incomplete: ${detail}` : "executor reported incomplete", MAX_VALIDATION_SUMMARY_LENGTH);
138
+ }
116
139
  function normalizedEvidencePath(value) {
117
140
  const normalized = value.replaceAll("\\", "/").replace(/^\.\//u, "");
118
141
  if (!normalized ||
@@ -313,9 +336,18 @@ export function buildExecutorEvidence(input) {
313
336
  ...(report.targetCoverage.length > 0 ? { target_coverage: report.targetCoverage } : {}),
314
337
  ...(input.rateLimitEvents?.length ? { rate_limit_events: input.rateLimitEvents } : {}),
315
338
  final_message: report.finalMessage,
316
- ...(input.status === "succeeded"
317
- ? {}
318
- : { block_reason: executorBlockReason(input.status, input.stderr) }),
339
+ ...(report.completionStatus ? { completion_status: report.completionStatus } : {}),
340
+ ...(report.handoff.length > 0 ? { handoff: report.handoff } : {}),
341
+ ...(input.status !== "succeeded"
342
+ ? { block_reason: executorBlockReason(input.status, input.stderr) }
343
+ : report.completionStatus === "incomplete"
344
+ ? {
345
+ block_reason: executorCompletionFailure({
346
+ completion_status: "incomplete",
347
+ final_message: report.finalMessage,
348
+ }),
349
+ }
350
+ : {}),
319
351
  log_refs: [
320
352
  {
321
353
  kind: "agent-output-excerpt",
@@ -241,6 +241,7 @@ export function loadPipelineResumeCheckpoint(input) {
241
241
  statePath,
242
242
  executorEvidence: evidence,
243
243
  ...(evidence.stage.status === "succeeded" &&
244
+ evidence.completion_status !== "incomplete" &&
244
245
  (state.stages.executor.status === "succeeded" || state.stages.executor.status === "running")
245
246
  ? { evidence }
246
247
  : {}),
@@ -149,6 +149,17 @@ export function resolveDeliverableByDocId(catalogPath, projectId, targetId) {
149
149
  }
150
150
  return matches[0];
151
151
  }
152
+ /** Resolve a project-repository-relative file path to its catalog entry, if any. */
153
+ export function findDeliverableByPath(catalogPath, targetPath) {
154
+ const normalized = targetPath.replaceAll("\\", "/").replace(/^\/+/, "");
155
+ const matches = resolvedDeliverablesInCatalog(catalogPath).filter((target) => target.info.resolvedPath.replaceAll("\\", "/").replace(/^\/+/, "") === normalized);
156
+ if (matches.length > 1) {
157
+ throw new Error(`ambiguous catalog deliverable target for path ${targetPath}: ${matches
158
+ .map((match) => match.localId)
159
+ .join(", ")}`);
160
+ }
161
+ return matches[0] ?? null;
162
+ }
152
163
  // A kata may be declared by zero, one, or several deliverables. Only a unique declaration is
153
164
  // used as the maintenance plan's evidence context; otherwise the explicitly targeted kata remains
154
165
  // executable without selecting an arbitrary deliverable.
@@ -646,12 +657,17 @@ export function finalizeResultSectionsForDeliverable(catalogPath, localId, appro
646
657
  targetsChecklist: finalizeTargetsChecklist(info, approach),
647
658
  };
648
659
  }
660
+ // owner ロール視点の記述ガイドを構成するデータ値。prose ラベルや見出しは
661
+ // テンプレート側(言語別 docs/<lang>/.../exec-templates)に置き、ここでは値のみを供給する。
662
+ const MISSING_VIEWPOINTS = `- ${MISSING}`;
649
663
  // owner の Role code から、pm-roles.yaml の責務(project_note)と
650
664
  // pm-review-viewpoints.yaml の該当 role 観点を取り出す。owner 未設定や情報欠落時は
651
665
  // 他のプレースホルダと同様に MISSING を返し、表示構造はテンプレート側に委ねる。
666
+ // ただし viewpoints はテンプレートで単独の段落に置かれるため、欠落時も箇条書きの
667
+ // 1 項目(`- _MISSING_`)にする。強調だけの段落は markdownlint MD036 に違反する(PJR-SS72)。
652
668
  export function ownerRoleFields(owner, roleMap, vpMap, rulebook) {
653
669
  if (!owner) {
654
- return { label: MISSING, note: MISSING, viewpoints: MISSING };
670
+ return { label: MISSING, note: MISSING, viewpoints: MISSING_VIEWPOINTS };
655
671
  }
656
672
  const role = roleMap.get(owner);
657
673
  const label = role?.name ? `${owner}(${role.name})` : owner;
@@ -660,7 +676,7 @@ export function ownerRoleFields(owner, roleMap, vpMap, rulebook) {
660
676
  const roleViewpoints = [...vpMap.values()].filter((vp) => vp.role === owner && viewpointAppliesToDocument(vp, metadata));
661
677
  const viewpoints = roleViewpoints.length > 0
662
678
  ? roleViewpoints.map((vp) => `- ${vp.title}: ${vp.check}`).join("\n")
663
- : MISSING;
679
+ : MISSING_VIEWPOINTS;
664
680
  return { label, note, viewpoints };
665
681
  }
666
682
  // edit plan は観点別の自己レビューを行わない。done_criteria は §3 の owner 視点とは別に
@@ -65,7 +65,7 @@ function buildEditPlanMarkdown(template, task, deliverable, roleMap, vpMap, proj
65
65
  _AUTHORING_STANDARD_ID_: planOverrides?.authoring?.standardId ?? MISSING,
66
66
  _AUTHORING_STANDARD_PATH_: planOverrides?.authoring?.standardPath ?? MISSING,
67
67
  _AUTHORING_EXEMPLARS_: planOverrides?.authoring?.exemplars
68
- .map((example) => `- \`${example.id}\`: ${example.name}(\`${example.path}\`、現在の参照: \`${example.currentReference}\`)`)
68
+ .map((example) => `- \`${example.id}\`: ${example.name}(\`${example.path}\`、${example.catalog ? "現在の参照" : "参照更新"}: \`${example.currentReference}\`)`)
69
69
  .join("\n") || "- なし(kata だけを新規作成する)",
70
70
  };
71
71
  const body = expandTemplate(template, values);
@@ -5,6 +5,9 @@ import { safeSlug } from "./shared.js";
5
5
  function executorResumeHandoff(evidence) {
6
6
  if (!evidence)
7
7
  return [];
8
+ if (evidence.completion_status === "incomplete") {
9
+ return [evidence.block_reason || evidence.final_message, ...(evidence.handoff ?? [])].filter((note) => note.trim());
10
+ }
8
11
  const failedParentValidations = evidence.validations
9
12
  .filter((validation) => validation.source === "runner" && validation.status === "failed")
10
13
  .map((validation) => {
@@ -78,13 +81,13 @@ export function selectResumableRegisterRun(candidates, options = {}) {
78
81
  return a.runId < b.runId ? -1 : a.runId > b.runId ? 1 : 0;
79
82
  });
80
83
  const latest = ordered[candidates.length - 1];
81
- // The earliest rate-limited executor attempt is the stable lower bound for every later resume.
84
+ // The earliest interrupted or incomplete attempt is the stable lower bound for later resumes.
82
85
  // Rejected protection-block changes are intentionally excluded; the handoff requires removing
83
86
  // them before resume. `attempt_changes` also excludes runner lifecycle changes that predated the
84
87
  // executor invocation.
85
88
  const firstAttemptEvidence = ordered
86
89
  .map((candidate) => candidate.executorEvidence ?? candidate.evidence)
87
- .find((evidence) => evidence?.stage.status === "rate_limited");
90
+ .find((evidence) => evidence?.stage.status === "rate_limited" || evidence?.completion_status === "incomplete");
88
91
  const initialChanges = [
89
92
  ...new Set((firstAttemptEvidence?.attempt_changes ?? firstAttemptEvidence?.changes ?? [])
90
93
  .map((change) => change.path.trim())
@@ -99,10 +102,11 @@ export function selectResumableRegisterRun(candidates, options = {}) {
99
102
  initialChanges: [...changes],
100
103
  handoff: executorResumeHandoff(candidate.executorEvidence ?? candidate.evidence),
101
104
  });
102
- // rate limit または保護機構の block で打ち切られた executor は、evidence が記録されていても
105
+ // 未完了の申告、rate limit または保護機構の block で打ち切られた executor は、evidence が記録されていても
103
106
  // 作業を完了していない。reporter へ進めず、申し送りを反映できるよう既存 worktree 上で
104
107
  // executor を再開する。通常のプロセス失敗は failed のまま区別し、再開対象にしない。
105
- if (latest.state.stages.executor.status === "rate_limited" ||
108
+ if ((latest.executorEvidence ?? latest.evidence)?.completion_status === "incomplete" ||
109
+ latest.state.stages.executor.status === "rate_limited" ||
106
110
  latest.state.stages.executor.status === "blocked") {
107
111
  return {
108
112
  kind: "resumable",
@@ -1,9 +1,9 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import { extname, join, relative, resolve } from "node:path";
2
+ import { basename, extname, join, relative, resolve } from "node:path";
3
3
  import { findRegisterItem, loadRegisterItems, PJR_ID_RE, resolveRegisterPaths, TERMINAL_STATUSES_SET, VALID_PRIORITIES, VALID_STATUSES, VALID_TYPES, } from "../register/register.js";
4
4
  import { execTemplatePath, injectCommonConventions, MISSING, registerGradeFindingsText, } from "./plans.js";
5
5
  import { generateRegisterApproachPlan } from "./plans-generation.js";
6
- import { findUniqueDeliverableForKataTarget, resolveDeliverableByDocId, } from "./plans-core.js";
6
+ import { findUniqueDeliverableForKataTarget, findDeliverableByPath, resolveDeliverableByDocId, } from "./plans-core.js";
7
7
  import { collectDocIndexEntries } from "../docs/doc-index.js";
8
8
  import { loadRulebookRefs, resolveKataRefs } from "../kata/kata.js";
9
9
  import { authoredKataPath, authoringKind, authoringStandardId, authoringStandardPath, } from "../kata/authoring.js";
@@ -11,7 +11,9 @@ import { validateRegisterApproachTargets } from "../register/approach.js";
11
11
  import { buildSpecdojoFrontmatter } from "../docs/frontmatter-namespace.js";
12
12
  import { escapeMarkdownInline, expandTemplate, inlineCodeAnglePlaceholders, stripTerminalControlSequences, } from "./shared.js";
13
13
  import { formatMarkdownFile } from "./format.js";
14
- import { specdojoRootDir } from "../shared/specdojo-config.js";
14
+ import { loadConfig, specdojoRootDir } from "../shared/specdojo-config.js";
15
+ import { resolveAuthoringSources, } from "../register/authoring-sources.js";
16
+ import { repoEnvironmentVariableName } from "./task-repos.js";
15
17
  const EDIT_TYPES = new Set(["todo", "issue", "change-request"]);
16
18
  const INVESTIGATE_TYPES = new Set(["question", "risk"]);
17
19
  export function registerItemCategory(itemType) {
@@ -302,6 +304,26 @@ function indexedDocumentPath(targetId) {
302
304
  const withoutLine = indexed.replace(/:\d+$/, "");
303
305
  return relative(repoRoot, resolve(repoRoot, withoutLine)).replace(/\\/g, "/");
304
306
  }
307
+ function authoringSourcePlanPath(source) {
308
+ return source.repo ? `$${repoEnvironmentVariableName(source.repo)}/${source.path}` : source.path;
309
+ }
310
+ function catalogSource(catalogPath, projectId, source) {
311
+ if (!catalogPath || source.repo)
312
+ return null;
313
+ if (source.documentId) {
314
+ try {
315
+ return resolveDeliverableByDocId(catalogPath, projectId, source.documentId);
316
+ }
317
+ catch (error) {
318
+ if (error instanceof Error &&
319
+ error.message.startsWith("catalog deliverable target not found")) {
320
+ return null;
321
+ }
322
+ throw error;
323
+ }
324
+ }
325
+ return findDeliverableByPath(catalogPath, source.path);
326
+ }
305
327
  export async function generateRegisterPlan(opts) {
306
328
  const { item } = opts;
307
329
  const category = requireRunnableRegisterItem(item);
@@ -313,6 +335,7 @@ export async function generateRegisterPlan(opts) {
313
335
  ...(opts.catalogPath ? { catalogPath: opts.catalogPath } : {}),
314
336
  approach: item.approach,
315
337
  targets: item.targets,
338
+ sources: item.sources,
316
339
  });
317
340
  const [targetId] = item.targets ?? [];
318
341
  if (!targetId)
@@ -323,14 +346,22 @@ export async function generateRegisterPlan(opts) {
323
346
  let refs;
324
347
  let authoring;
325
348
  if (newKataKind) {
326
- const examples = (item.targets ?? []).slice(1).map((exampleId) => {
327
- if (!opts.catalogPath) {
328
- throw new Error(`Register item ${item.id} approach requires catalog_path to resolve ${exampleId}.`);
329
- }
330
- const resolved = resolveDeliverableByDocId(opts.catalogPath, opts.projectId, exampleId).info;
331
- const rulebookId = resolved.deliverable.rulebook;
349
+ const sourceRefs = [...(item.targets ?? []).slice(1), ...(item.sources ?? [])];
350
+ const project = loadConfig(specdojoRootDir()).config?.projects[opts.projectId] ?? {};
351
+ const resolvedSources = resolveAuthoringSources({
352
+ repoRoot: specdojoRootDir(),
353
+ project,
354
+ sources: sourceRefs,
355
+ });
356
+ const examples = resolvedSources.map((source) => {
357
+ const catalogEntry = catalogSource(opts.catalogPath, opts.projectId, source);
358
+ const resolved = catalogEntry?.info;
359
+ const rulebookId = resolved?.deliverable.rulebook;
332
360
  let currentReference;
333
- if (newKataKind === "rulebook") {
361
+ if (!resolved) {
362
+ currentReference = "カタログ外のため参照の付け替え対象外";
363
+ }
364
+ else if (newKataKind === "rulebook") {
334
365
  currentReference = rulebookId ?? "未記入";
335
366
  }
336
367
  else if (!rulebookId ||
@@ -345,11 +376,13 @@ export async function generateRegisterPlan(opts) {
345
376
  ? declaredReference.join(", ")
346
377
  : (declaredReference ?? "未記入");
347
378
  }
379
+ const planPath = authoringSourcePlanPath(source);
348
380
  return {
349
- id: exampleId,
350
- name: resolved.deliverable.name,
351
- path: resolved.resolvedPath,
381
+ id: source.documentId ?? (source.repo ? `${source.repo}:${source.path}` : source.path),
382
+ name: resolved?.deliverable.name ?? basename(source.path),
383
+ path: planPath,
352
384
  currentReference,
385
+ catalog: resolved !== undefined,
353
386
  };
354
387
  });
355
388
  const exemplarExtension = extname(examples[0]?.path ?? "").slice(1);
@@ -396,7 +429,7 @@ export async function generateRegisterPlan(opts) {
396
429
  description: item.description,
397
430
  ...(item.owner && item.owner !== "-" && item.owner !== "_TODO_" ? { owner: item.owner } : {}),
398
431
  approach: item.approach,
399
- targets: item.targets ?? [],
432
+ targets: targetId ? [targetId] : [],
400
433
  deliverable,
401
434
  ...(refs ? { refs } : {}),
402
435
  ...(authoring ? { authoring } : {}),
@@ -1,5 +1,6 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
2
  import { join, relative, resolve, sep } from "node:path";
3
+ import { executorCompletionFailure } from "./evidence.js";
3
4
  import { PARENT_VALIDATION_PROJECT_REPO, failedParentValidationReason, } from "./parent-validation.js";
4
5
  import { getProjectExecutionPath, resolveRepoRoot, specdojoRootDir, } from "../shared/specdojo-config.js";
5
6
  import { MAX_TEXT_LENGTH, parseReporterOutput, reporterOutputSchemaForMode, } from "./reporter-output.js";
@@ -126,6 +127,10 @@ export function deriveReporterFacts(evidence, options = {}) {
126
127
  : "executor stage failed");
127
128
  return { outcome: "blocked", changed_files: changedFiles, block_reason: blockReason };
128
129
  }
130
+ const completionFailure = executorCompletionFailure(evidence);
131
+ if (completionFailure) {
132
+ return { outcome: "blocked", changed_files: changedFiles, block_reason: completionFailure };
133
+ }
129
134
  const validationFailure = failedParentValidationReason(evidence.validations);
130
135
  if (validationFailure) {
131
136
  return {
@@ -648,7 +653,9 @@ export function buildReporterPrompt(opts) {
648
653
  from the stored grade result. Record that judgement in verdict and put unmet items and improvement
649
654
  instructions in improvements. If evidence.final_message identifies "確認できなかった範囲",
650
655
  record that scope in rationale or improvements and reflect it in the verdict.`
651
- : "";
656
+ : `\n\nThe runner preserves evidence.handoff mechanically in the result's handoff section, even when
657
+ your handoff is empty. Do not omit, reinterpret, or contradict those executor notes. Use your
658
+ handoff only for additional notes supported by evidence; do not repeat evidence.handoff.`;
652
659
  return `You are the reporter stage of a SpecDojo executor/reporter pipeline.
653
660
  Use only the supplied plan and bounded executor evidence. Do not edit or inspect files. Do not
654
661
  invent facts that are absent from evidence. Return exactly one JSON object matching the supplied
@@ -620,7 +620,7 @@ export function renderEditReporterBody(output, evidence, options) {
620
620
  "## 3. 申し送り",
621
621
  "",
622
622
  reporterBulletList([
623
- ...output.handoff,
623
+ ...new Set([...output.handoff, ...(evidence.handoff ?? [])]),
624
624
  ...unchangedTargetNotes,
625
625
  ...notApplicableValidationNotes,
626
626
  ...runnerOwnedValidationNotes,
@@ -1,5 +1,5 @@
1
1
  import { relative, sep } from "node:path";
2
- import { recordExecutorEvidence, recordParentValidationFailureOutput, recordReporterFailureOutput, snapshotWorktreeChanges, writeExecutorEvidence, } from "../evidence.js";
2
+ import { executorCompletionFailure, recordExecutorEvidence, recordParentValidationFailureOutput, recordReporterFailureOutput, snapshotWorktreeChanges, writeExecutorEvidence, } from "../evidence.js";
3
3
  import { failedParentValidationReason, hasRecordedParentValidations, parentValidationRoots, replaceParentValidationResults, } from "../parent-validation.js";
4
4
  import { createPipelineState, pipelineStateLocation, updatePipelineStage, writePipelineState, } from "../pipeline-state.js";
5
5
  import { deriveReporterFacts, evidenceForReporter, runReporterWithFormatRetry, } from "../reporter.js";
@@ -200,7 +200,8 @@ export async function runAgentPipeline(params) {
200
200
  productWorktrees: params.productWorktrees,
201
201
  rateLimitEvents: outcome.rateLimitEvents,
202
202
  });
203
- const coverageFailure = outcome.result === "success"
203
+ const completionFailure = outcome.result === "success" ? executorCompletionFailure(recorded.evidence) : undefined;
204
+ const coverageFailure = outcome.result === "success" && !completionFailure
204
205
  ? resumedTargetCoverageFailure({
205
206
  resumed: !!params.resumedExecutor,
206
207
  plan: planPrompt,
@@ -209,13 +210,13 @@ export async function runAgentPipeline(params) {
209
210
  initialChangeTargets: params.initialChangeTargets,
210
211
  })
211
212
  : undefined;
212
- const executorResult = coverageFailure ? "failure" : outcome.result;
213
+ const executorResult = completionFailure || coverageFailure ? "failure" : outcome.result;
213
214
  const evidenceRef = relative(cwd, recorded.evidencePath).split(sep).join("/");
214
215
  const executorCompletedAt = new Date().toISOString();
215
216
  state = updatePipelineStage(state, "executor", {
216
217
  status: executorResult === "success"
217
218
  ? "succeeded"
218
- : outcome.protectionBlock
219
+ : outcome.protectionBlock || completionFailure
219
220
  ? "blocked"
220
221
  : executorResult === "rate_limit"
221
222
  ? "rate_limited"
@@ -229,7 +230,8 @@ export async function runAgentPipeline(params) {
229
230
  writePipelineState(stateLocation.path, state);
230
231
  process.stdout.write(` Executor evidence: ${evidenceRef}\n`);
231
232
  if (executorResult !== "success") {
232
- const blockReason = coverageFailure ??
233
+ const blockReason = completionFailure ??
234
+ coverageFailure ??
233
235
  (executorResult === "rate_limit"
234
236
  ? "executor rate limit reached"
235
237
  : extractBlockReason(outcome.stderr));
@@ -111,6 +111,19 @@ artifacts required by the plan, but do not create or update the result file. Any
111
111
  that assigns result writing or lifecycle transitions to the agent belongs to the later reporter or
112
112
  runner stage and does not apply here.
113
113
 
114
+ Put unresolved decisions, proposed protected-configuration changes, and next actions in the
115
+ report's optional \`handoff\` array (up to 100 non-empty strings, each at most 4000 characters).
116
+ For register tasks, also record them in the ticket's response/results section. If a completion
117
+ condition asks for a note in the result, write it in both places instead of editing the result.
118
+ The runner preserves \`handoff\` in the edit result's handoff section after the reporter stage.
119
+ Use an empty array when there are no handoff notes. Reports without this field remain valid.
120
+
121
+ Report task completion in \`completion_status\`: use \`complete\` only when all work required by
122
+ the plan is done. If you stop with unfinished work, use \`incomplete\`, summarize the reason in
123
+ \`final_message\`, and list the remaining work in \`handoff\`. A zero exit code and passing parent
124
+ validations do not override \`incomplete\`; the runner preserves the worktree for executor resume.
125
+ Omitting this field is supported for legacy reports and implies \`complete\`.
126
+
114
127
  The parent runner owns Git commits and repository configuration. Do not run git commit or change
115
128
  local, global, or system Git configuration, including user.name and user.email. A Git state change
116
129
  will stop the pipeline before validation, reporting, commit, or merge.
@@ -155,7 +168,7 @@ End the final response with exactly one machine-readable report using this envel
155
168
  Markdown fences around the JSON.
156
169
 
157
170
  <specdojo_executor_evidence>
158
- {"final_message":"concise outcome","validations":[{"command":"exact command","status":"passed|failed|not_run|not_applicable|requires_human","summary":"concise result or required human check","reason":"required when status is not_applicable"}]${targetCoverageExample}}
171
+ {"completion_status":"complete|incomplete","final_message":"concise outcome","handoff":[],"validations":[{"command":"exact command","status":"passed|failed|not_run|not_applicable|requires_human","summary":"concise result or required human check","reason":"required when status is not_applicable"}]${targetCoverageExample}}
159
172
  </specdojo_executor_evidence>
160
173
  `;
161
174
  }