specdojo 0.4.0 → 0.4.1
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.
- package/.github/agents/specdojo-orchestrator.md +61 -2
- package/CHANGELOG.md +43 -0
- package/README.md +8 -7
- package/dist/commands/init.js +72 -15
- package/dist/commands/night-orchestrator.js +287 -0
- package/dist/commands/orchestrator.js +10 -3
- package/dist/devcontainer/command.js +3 -1
- package/dist/devcontainer/scaffold.js +166 -5
- package/dist/exec/agent-config.js +60 -2
- package/dist/exec/parent-validation.js +14 -0
- package/dist/exec/pipeline-state.js +13 -0
- package/dist/exec/register.js +23 -1
- package/dist/exec/repo-integration.js +1 -1
- package/dist/exec/reporter.js +113 -13
- package/dist/exec/results.js +36 -14
- package/dist/exec/run/agent-pipeline.js +3 -0
- package/dist/exec/run/agent.js +40 -5
- package/dist/exec/run/job.js +2 -2
- package/dist/exec/run/lifecycle-commands.js +2 -2
- package/dist/exec/run/register-command.js +23 -4
- package/dist/exec/run/register-core.js +17 -0
- package/dist/exec/run/register-mode.js +39 -16
- package/dist/exec/run/register-post-review.js +420 -0
- package/dist/exec/run/register-resume.js +27 -11
- package/dist/exec/run/register-worktree.js +66 -2
- package/dist/exec/run/run.js +1 -1
- package/dist/exec/run/shared.js +22 -24
- package/dist/exec/task-repos.js +102 -15
- package/dist/register/core.js +14 -2
- package/dist/register/create-commands.js +62 -6
- package/dist/register/event-merge.js +13 -1
- package/dist/register/events.js +4 -0
- package/dist/register/item.js +9 -0
- package/dist/register/migration.js +1 -0
- package/dist/register/register.js +2 -2
- package/dist/shared/git.js +45 -15
- package/dist/shared/provider-scaffold.js +3 -2
- package/dist/shared/specdojo-config.js +69 -16
- package/dist/shared/text.js +4 -1
- package/dist/shared/workspace-scaffold.js +69 -0
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +2 -1
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
- package/docs/ja/specdojo/exec-templates/xrp-register-post-run-template.md +46 -0
- package/docs/ja/specdojo/guides/branch-workflow-guide.md +34 -1
- package/docs/ja/specdojo/guides/docs-structure-guide.md +2 -0
- package/docs/ja/specdojo/guides/exec-config-guide.md +79 -11
- package/docs/ja/specdojo/guides/exec-operation-guide.md +39 -1
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +9 -3
- package/docs/ja/specdojo/guides/quick-start-guide.md +9 -6
- package/docs/ja/specdojo/guides/register-operation-guide.md +42 -0
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +52 -6
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +1 -1
- package/docs/ja/specdojo/guides/waza-guide.md +1 -1
- package/docs/ja/specdojo/references/command-reference.md +101 -56
- package/docs/ja/specdojo/references/specdojo-config-reference.md +33 -7
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +5 -2
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +92 -18
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +6 -1
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +12 -0
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +21 -0
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +35 -0
- package/package.json +17 -17
- package/templates/antigravity/README.md +1 -1
- package/templates/antigravity/orchestrator.md +61 -2
- package/templates/claude/agents/specdojo-orchestrator.md +61 -2
- package/templates/codex/README.md +17 -0
- package/templates/codex/agents/specdojo-orchestrator.toml +61 -2
- package/templates/codex/orchestrator.md +61 -2
- package/templates/devcontainer/devcontainer.json +3 -0
- package/templates/devcontainer/post-create.sh +15 -7
- package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +38 -5
- package/templates/devcontainer/remote-host/ssh-config.sample +3 -0
- package/templates/devcontainer/vim/vimrc +37 -0
- package/templates/init-agent-members.yaml +3 -3
- package/templates/init-exec-defaults.yaml +20 -1
- package/templates/opencode/agents/specdojo-orchestrator.md +61 -2
package/dist/shared/git.js
CHANGED
|
@@ -9,14 +9,24 @@ export { GIT_LOCAL_ENV_VARS, gitEnvironment } from "./git-environment.js";
|
|
|
9
9
|
// concurrent worktree commits (each firing lefthook pre-commit hooks that invoke git) contend
|
|
10
10
|
// for that lock, surfacing as "Unable to create '.../index.lock'". A failed lock acquisition
|
|
11
11
|
// happens before git mutates anything, so retrying the same command is safe and idempotent.
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
// 並行の run の統合や記帳と重なると、ロックは数百ミリ秒より長く保持される(PJR-G90K)。
|
|
13
|
+
// 1.5 秒間隔で 10 回までやり直し、ロックのファイルは消さない(実際に動いている git がありうる)。
|
|
14
|
+
export const INDEX_LOCK_RETRY_ATTEMPTS = 10;
|
|
15
|
+
export const INDEX_LOCK_RETRY_WAIT_MS = 1500;
|
|
14
16
|
// dubious ownership と、`.git` がある cwd での not-a-repository は一時的に起き、すぐの
|
|
15
17
|
// 再試行では収まらないことがある(並行実行中の統合段で確認した)。両方で上限を共有する。
|
|
16
18
|
const TRANSIENT_GIT_RETRY_DELAYS_MS = [2000, 5000, 10000];
|
|
19
|
+
// 英語の `Unable to create '<path>/index.lock': File exists.` に加え、翻訳された git の
|
|
20
|
+
// メッセージ(日本語など)でも引用符で囲まれた index.lock のパスが出るため、それも拾う。
|
|
21
|
+
const INDEX_LOCK_QUOTED_PATH = /['"‘’“「]([^'"‘’“”「」\r\n]*index\.lock)['"’”」]/u;
|
|
22
|
+
export function gitIndexLockPath(stderr) {
|
|
23
|
+
return INDEX_LOCK_QUOTED_PATH.exec(stderr)?.[1];
|
|
24
|
+
}
|
|
17
25
|
export function isGitIndexLockContention(stderr) {
|
|
18
26
|
return (/Unable to create '[^']*index\.lock'/.test(stderr) ||
|
|
19
|
-
/Another git process seems to be running/.test(stderr)
|
|
27
|
+
/Another git process seems to be running/.test(stderr) ||
|
|
28
|
+
/別の\s*git\s*プロセス/iu.test(stderr) ||
|
|
29
|
+
gitIndexLockPath(stderr) !== undefined);
|
|
20
30
|
}
|
|
21
31
|
export function isGitDubiousOwnership(stderr) {
|
|
22
32
|
return /fatal:\s+detected dubious ownership in repository\b/i.test(stderr);
|
|
@@ -75,7 +85,13 @@ export function runGitWithTransientRetry(run, onTransientFailureRetry = () => un
|
|
|
75
85
|
}
|
|
76
86
|
if (indexLockRetries < INDEX_LOCK_RETRY_ATTEMPTS && isGitIndexLockContention(stderr)) {
|
|
77
87
|
indexLockRetries += 1;
|
|
78
|
-
|
|
88
|
+
onTransientFailureRetry({
|
|
89
|
+
attempt: indexLockRetries,
|
|
90
|
+
maxAttempts: INDEX_LOCK_RETRY_ATTEMPTS,
|
|
91
|
+
waitMilliseconds: INDEX_LOCK_RETRY_WAIT_MS,
|
|
92
|
+
reason: "index.lock contention",
|
|
93
|
+
});
|
|
94
|
+
sleep(INDEX_LOCK_RETRY_WAIT_MS);
|
|
79
95
|
result = run();
|
|
80
96
|
continue;
|
|
81
97
|
}
|
|
@@ -175,7 +191,11 @@ export function formatGitCommandFailure(args, stderr, processFailure = "") {
|
|
|
175
191
|
? args
|
|
176
192
|
: [...args.slice(0, subcommandIndex), ...args.slice(subcommandIndex + 1)]);
|
|
177
193
|
const detail = summary ? ` (args: ${summary})` : "";
|
|
178
|
-
|
|
194
|
+
// gitResult は index.lock の取り合いをやり直したうえで失敗を返す。どのロックが残っていたかを
|
|
195
|
+
// 要約の切り詰めに左右されず先頭に残す(ロックは runner が消さないため、人が確かめる手掛かり)。
|
|
196
|
+
const lockPath = isGitIndexLockContention(stderr) ? gitIndexLockPath(stderr) : undefined;
|
|
197
|
+
const lockNotice = lockPath ? `index.lock is still held (lock: ${lockPath})` : "";
|
|
198
|
+
const cause = [processFailure.trim(), lockNotice, summarizeGitStderr(stderr)]
|
|
179
199
|
.filter((part) => part !== "")
|
|
180
200
|
.join(" / ");
|
|
181
201
|
return cause ? `${label} failed: ${cause}${detail}` : `${label} failed${detail}`;
|
|
@@ -203,21 +223,31 @@ export function summarizeGitHookFailure(output) {
|
|
|
203
223
|
.filter(Boolean);
|
|
204
224
|
if (lines.length === 0)
|
|
205
225
|
return "unknown hook failure";
|
|
206
|
-
|
|
207
|
-
let stepIndex = -1;
|
|
226
|
+
const stepHeaders = [];
|
|
208
227
|
for (const [index, line] of lines.entries()) {
|
|
209
228
|
const match = line.match(/^(.+?)\s*[❯▶]\s*$/u);
|
|
210
|
-
if (
|
|
211
|
-
|
|
212
|
-
step = match[1].trim();
|
|
213
|
-
stepIndex = index;
|
|
214
|
-
break;
|
|
229
|
+
if (match)
|
|
230
|
+
stepHeaders.push({ step: match[1].trim(), index });
|
|
215
231
|
}
|
|
232
|
+
// parallel: true の lefthook は成功した step の出力も並べるため、最初の step 見出しが
|
|
233
|
+
// 失敗した step とは限らない。末尾の summary で失敗印(🥊 など)が付いた step を優先する。
|
|
234
|
+
const failedSteps = lines
|
|
235
|
+
.map((line) => line.match(/^(?:🥊|✗|✘|✕|❌)️?\s*([^\s(]+)/u)?.[1])
|
|
236
|
+
.filter((name) => name !== undefined && name !== "lefthook");
|
|
237
|
+
const selected = stepHeaders.find((header) => failedSteps.includes(header.step)) ?? stepHeaders[0];
|
|
238
|
+
const step = selected?.step ?? failedSteps[0] ?? "";
|
|
239
|
+
const stepIndex = selected?.index ?? -1;
|
|
240
|
+
const sectionEnd = selected === undefined
|
|
241
|
+
? lines.length
|
|
242
|
+
: (stepHeaders.find((header) => header.index > selected.index)?.index ?? lines.length);
|
|
216
243
|
const isDecoration = (line) => /^(?:hook output|summary:|exit status\b|failed steps?:|skip(?:ped)?\b)/i.test(line) ||
|
|
217
244
|
/^[✓✔✗✘✕❯▶]+$/u.test(line);
|
|
218
|
-
const
|
|
219
|
-
|
|
220
|
-
|
|
245
|
+
const isCandidate = (line) => line !== step && !isDecoration(line) && !/[❯▶]\s*$/u.test(line);
|
|
246
|
+
const sectionLines = lines.slice(stepIndex + 1, sectionEnd).filter(isCandidate);
|
|
247
|
+
// 整形ツールが出す "(unchanged)" などの進捗行より、error を含む行を最初のエラーとして選ぶ。
|
|
248
|
+
const errorLine = sectionLines.find((line) => /\berror\b/i.test(line)) ??
|
|
249
|
+
sectionLines[0] ??
|
|
250
|
+
lines.slice(stepIndex + 1).find(isCandidate);
|
|
221
251
|
const primary = step && errorLine
|
|
222
252
|
? `${step}: ${errorLine}`
|
|
223
253
|
: step ||
|
|
@@ -12,10 +12,11 @@ export const ORCHESTRATOR_NPM_SCRIPTS = {
|
|
|
12
12
|
"orch:sonnet": "specdojo orchestrator launch --provider claude -- --agent specdojo-orchestrator --model sonnet",
|
|
13
13
|
},
|
|
14
14
|
codex: {
|
|
15
|
-
"orch:
|
|
15
|
+
"orch:sol": 'specdojo orchestrator launch --provider codex -- -m gpt-5.6-sol "$(cat .specdojo/codex/orchestrator.md)"',
|
|
16
|
+
"orch:terra": 'specdojo orchestrator launch --provider codex -- -m gpt-5.6-terra "$(cat .specdojo/codex/orchestrator.md)"',
|
|
16
17
|
},
|
|
17
18
|
antigravity: {
|
|
18
|
-
"orch:
|
|
19
|
+
"orch:flash": 'specdojo orchestrator launch --provider antigravity -- --add-dir "$(pwd)" --model gemini-3.8-flash-high -i "$(cat .specdojo/antigravity/orchestrator.md)"',
|
|
19
20
|
},
|
|
20
21
|
opencode: {
|
|
21
22
|
"orch:opencode": "specdojo orchestrator launch --provider opencode -- --agent specdojo-orchestrator",
|
|
@@ -4,6 +4,7 @@ import dotenv from "dotenv";
|
|
|
4
4
|
import { dump, load } from "./yaml.js";
|
|
5
5
|
import Ajv2020Module from "ajv/dist/2020.js";
|
|
6
6
|
import { runProviderScaffold, specdojoPackageRootDir } from "./provider-scaffold.js";
|
|
7
|
+
import { runWorkspaceScaffold } from "./workspace-scaffold.js";
|
|
7
8
|
import { ensureGitignore, formatGitignoreReport, gitignorePatternsForLayouts, } from "./specdojo-gitignore.js";
|
|
8
9
|
/** Default IANA time zone for register date derivation when run.register_date_timezone is unset. */
|
|
9
10
|
export const DEFAULT_REGISTER_DATE_TIMEZONE = "UTC";
|
|
@@ -56,6 +57,14 @@ export function resolveRepoRoot(rootDir, repo) {
|
|
|
56
57
|
return resolve(rootDir, repo.path);
|
|
57
58
|
}
|
|
58
59
|
export const DEFAULT_PROJECT_CONTEXT = ["prj-overview"];
|
|
60
|
+
// Register events also have a small set of product-owned actors that do not represent a
|
|
61
|
+
// roster member. Keep this list closed: accepting arbitrary strings would make the audit log
|
|
62
|
+
// impossible to trace back to either a person, an agent, or a known SpecDojo component.
|
|
63
|
+
export const RESERVED_REGISTER_ACTORS = [
|
|
64
|
+
"SpecDojo",
|
|
65
|
+
"specdojo-orchestrator",
|
|
66
|
+
"night-orchestrator",
|
|
67
|
+
];
|
|
59
68
|
// Resolve either a concrete agent nickname or a backward-compatible alias to the concrete
|
|
60
69
|
// member. Alias validity is checked while loading the roster, but keep the traversal guarded so
|
|
61
70
|
// callers and tests that construct a roster directly cannot loop forever on malformed input.
|
|
@@ -83,6 +92,32 @@ export function resolveAgentMember(roster, nickname) {
|
|
|
83
92
|
}
|
|
84
93
|
return undefined;
|
|
85
94
|
}
|
|
95
|
+
export function resolveRegisterActor(actor, roster) {
|
|
96
|
+
const normalized = actor.trim();
|
|
97
|
+
if (!normalized) {
|
|
98
|
+
throw new Error("Register event actor must not be empty");
|
|
99
|
+
}
|
|
100
|
+
if (RESERVED_REGISTER_ACTORS.includes(normalized))
|
|
101
|
+
return normalized;
|
|
102
|
+
const agent = resolveAgentMember(roster, normalized);
|
|
103
|
+
if (agent)
|
|
104
|
+
return agent.nickname;
|
|
105
|
+
const humans = roster?.members.filter((member) => member.type === "human" && member.nickname === normalized) ??
|
|
106
|
+
[];
|
|
107
|
+
if (humans.length === 1)
|
|
108
|
+
return humans[0].nickname;
|
|
109
|
+
if (humans.length > 1) {
|
|
110
|
+
throw new Error(`Duplicate human actor nickname in members_path: ${normalized}`);
|
|
111
|
+
}
|
|
112
|
+
const rosterNames = [
|
|
113
|
+
...(roster?.members.map((member) => member.nickname) ?? []),
|
|
114
|
+
...(roster?.aliases?.map((alias) => alias.nickname) ?? []),
|
|
115
|
+
];
|
|
116
|
+
const accepted = [...new Set([...rosterNames, ...RESERVED_REGISTER_ACTORS])].sort();
|
|
117
|
+
throw new Error(`Unknown register actor: "${normalized}". Use a human nickname from members_path, ` +
|
|
118
|
+
`an agent nickname or alias from agent_members_path, or a reserved actor: ` +
|
|
119
|
+
accepted.join(", "));
|
|
120
|
+
}
|
|
86
121
|
export const DEFAULT_AGENT_MEMBERS_PATH = ".specdojo/agent-members.yaml";
|
|
87
122
|
function findUpward(startDir, name) {
|
|
88
123
|
let currentDir = resolve(startDir);
|
|
@@ -109,13 +144,13 @@ export function specdojoRootDir() {
|
|
|
109
144
|
export function defaultWorktreeBase(rootDir = specdojoRootDir()) {
|
|
110
145
|
return `../${basename(resolve(rootDir))}-worktrees`;
|
|
111
146
|
}
|
|
112
|
-
export function loadEnv() {
|
|
147
|
+
export function loadEnv(rootDir = specdojoRootDir()) {
|
|
113
148
|
// Load .env from the repository root if present.
|
|
114
149
|
// Safe if missing.
|
|
115
|
-
dotenv.config({ path: resolve(
|
|
150
|
+
dotenv.config({ path: resolve(rootDir, ".env"), quiet: true });
|
|
116
151
|
}
|
|
117
|
-
export function defaultConfigPath() {
|
|
118
|
-
return join(
|
|
152
|
+
export function defaultConfigPath(rootDir = specdojoRootDir()) {
|
|
153
|
+
return join(resolve(rootDir), ".specdojo", "specdojo.config.json");
|
|
119
154
|
}
|
|
120
155
|
// Join a project document path with the project's base_path, returning a repo-root-relative path.
|
|
121
156
|
// An empty/undefined base_path leaves the path unchanged (full backward compatibility).
|
|
@@ -507,9 +542,9 @@ function isValidProjectConfig(project) {
|
|
|
507
542
|
}
|
|
508
543
|
return true;
|
|
509
544
|
}
|
|
510
|
-
export function loadConfig() {
|
|
511
|
-
loadEnv();
|
|
512
|
-
const configPath = defaultConfigPath();
|
|
545
|
+
export function loadConfig(configRootDir = specdojoRootDir()) {
|
|
546
|
+
loadEnv(configRootDir);
|
|
547
|
+
const configPath = defaultConfigPath(configRootDir);
|
|
513
548
|
if (!existsSync(configPath)) {
|
|
514
549
|
return { configPath, config: null };
|
|
515
550
|
}
|
|
@@ -641,20 +676,38 @@ export function registerConfigCommands(program) {
|
|
|
641
676
|
});
|
|
642
677
|
cfg
|
|
643
678
|
.command("scaffold")
|
|
644
|
-
.description("Scaffold agent/settings templates for a provider")
|
|
645
|
-
.
|
|
679
|
+
.description("Scaffold agent/settings templates for a provider or VS Code multi-root workspace")
|
|
680
|
+
.option("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
|
|
681
|
+
.option("--workspace", "Generate VS Code multi-root workspace (<project-id>.code-workspace) from repos config", false)
|
|
682
|
+
.option("--project <id>", "Target project ID for workspace scaffolding (defaults to current_project)")
|
|
646
683
|
.option("--force", "Overwrite existing files", false)
|
|
647
684
|
.option("--dry-run", "Show planned files without writing", false)
|
|
648
685
|
.option("--global", "Merge provider permissions into user-level settings (currently antigravity only)", false)
|
|
649
686
|
.action(async (opts) => {
|
|
650
687
|
try {
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
688
|
+
if (!opts.provider && !opts.workspace) {
|
|
689
|
+
throw new Error("Specify --provider <name> or --workspace to scaffold.");
|
|
690
|
+
}
|
|
691
|
+
if (opts.global && !opts.provider) {
|
|
692
|
+
throw new Error("--global requires --provider antigravity");
|
|
693
|
+
}
|
|
694
|
+
if (opts.provider) {
|
|
695
|
+
await runProviderScaffold(String(opts.provider), {
|
|
696
|
+
packageRoot: specdojoPackageRootDir(),
|
|
697
|
+
repoRoot: specdojoRootDir(),
|
|
698
|
+
force: !!opts.force,
|
|
699
|
+
dryRun: !!opts.dryRun,
|
|
700
|
+
global: !!opts.global,
|
|
701
|
+
});
|
|
702
|
+
}
|
|
703
|
+
if (opts.workspace) {
|
|
704
|
+
await runWorkspaceScaffold({
|
|
705
|
+
repoRoot: specdojoRootDir(),
|
|
706
|
+
projectId: opts.project ? String(opts.project) : undefined,
|
|
707
|
+
force: !!opts.force,
|
|
708
|
+
dryRun: !!opts.dryRun,
|
|
709
|
+
});
|
|
710
|
+
}
|
|
658
711
|
}
|
|
659
712
|
catch (error) {
|
|
660
713
|
const message = error instanceof Error ? error.message : String(error);
|
package/dist/shared/text.js
CHANGED
|
@@ -45,7 +45,10 @@ export function expandTemplate(template, values) {
|
|
|
45
45
|
// `: _PLACEHOLDER_` の空白が行末に残る。生成 plan は prettier の整形対象外
|
|
46
46
|
// (.prettierignore)で checkpoint commit 時に markdownlint の MD009 が直接効くため、
|
|
47
47
|
// ここで行末の空白を取り除く。
|
|
48
|
-
|
|
48
|
+
// 置換値が空のとき(夜間の承認の印がない register 個票の _AUTOPILOT_CONSTRAINTS_、
|
|
49
|
+
// agent の Job の _JOB_EXECUTION_、保守系の _PROJECT_CONTEXT_ など)、前後の空行が重なって
|
|
50
|
+
// MD012 で checkpoint commit が止まるため、2 行以上続く空行を 1 行にまとめる(PJR-283N)。
|
|
51
|
+
return result.replace(/[ \t]+$/gm, "").replace(/\n{3,}/g, "\n\n");
|
|
49
52
|
}
|
|
50
53
|
// 登録簿の自由記述(title / description 列など)を Markdown 本文へ埋め込む際の安全化。
|
|
51
54
|
// `register_date_timezone` のようなアンダースコア入り識別子や `_TODO_` / `_ASSUMPTION_` が、
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { existsSync, readFileSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { basename, join, resolve } from "node:path";
|
|
3
|
+
import { specdojoRootDir } from "./specdojo-config.js";
|
|
4
|
+
export function buildWorkspaceData(repoName, repos) {
|
|
5
|
+
return {
|
|
6
|
+
folders: [
|
|
7
|
+
{ name: repoName, path: "." },
|
|
8
|
+
...repos.map((repo) => ({ name: repo.name, path: repo.path })),
|
|
9
|
+
],
|
|
10
|
+
};
|
|
11
|
+
}
|
|
12
|
+
export function renderWorkspaceContent(repoName, repos) {
|
|
13
|
+
const data = buildWorkspaceData(repoName, repos);
|
|
14
|
+
return `${JSON.stringify(data, null, 2)}\n`;
|
|
15
|
+
}
|
|
16
|
+
export async function runWorkspaceScaffold(options = {}) {
|
|
17
|
+
const repoRoot = options.repoRoot ? resolve(options.repoRoot) : specdojoRootDir();
|
|
18
|
+
const configPath = join(repoRoot, ".specdojo", "specdojo.config.json");
|
|
19
|
+
if (!existsSync(configPath)) {
|
|
20
|
+
throw new Error(`No config found: ${configPath}`);
|
|
21
|
+
}
|
|
22
|
+
let config;
|
|
23
|
+
try {
|
|
24
|
+
config = JSON.parse(readFileSync(configPath, "utf8"));
|
|
25
|
+
}
|
|
26
|
+
catch (error) {
|
|
27
|
+
throw new Error(`Failed to parse config: ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
|
|
28
|
+
}
|
|
29
|
+
const projectId = options.projectId || config.current_project;
|
|
30
|
+
if (!projectId) {
|
|
31
|
+
throw new Error("No current_project configured. Specify --project <id>.");
|
|
32
|
+
}
|
|
33
|
+
const project = config.projects?.[projectId];
|
|
34
|
+
if (!project) {
|
|
35
|
+
throw new Error(`Unknown project: ${projectId}`);
|
|
36
|
+
}
|
|
37
|
+
if (!project.repos || project.repos.length === 0) {
|
|
38
|
+
throw new Error(`Project '${projectId}' has no 'repos' configured in ${configPath}. Declare 'repos' in the project configuration before scaffolding a multi-root workspace.`);
|
|
39
|
+
}
|
|
40
|
+
const repoName = basename(repoRoot);
|
|
41
|
+
const fileName = `${projectId}.code-workspace`;
|
|
42
|
+
const filePath = join(repoRoot, fileName);
|
|
43
|
+
if (existsSync(filePath) && !options.force) {
|
|
44
|
+
if (options.dryRun) {
|
|
45
|
+
process.stdout.write(`[dry-run] skipped: ${fileName} already exists (use --force to overwrite)\n`);
|
|
46
|
+
}
|
|
47
|
+
else {
|
|
48
|
+
process.stdout.write(`Skipped (already exists): ${fileName}\n`);
|
|
49
|
+
}
|
|
50
|
+
return {
|
|
51
|
+
status: "skipped",
|
|
52
|
+
relativePath: fileName,
|
|
53
|
+
absolutePath: filePath,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
const content = renderWorkspaceContent(repoName, project.repos);
|
|
57
|
+
if (options.dryRun) {
|
|
58
|
+
process.stdout.write(`[dry-run] would write: ${fileName}\n`);
|
|
59
|
+
}
|
|
60
|
+
else {
|
|
61
|
+
writeFileSync(filePath, content, "utf8");
|
|
62
|
+
process.stdout.write(`Written: ${fileName}\n`);
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
status: "written",
|
|
66
|
+
relativePath: fileName,
|
|
67
|
+
absolutePath: filePath,
|
|
68
|
+
};
|
|
69
|
+
}
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
- 検査を実行する前に、リポジトリの `package.json`、`.specdojo/specdojo.config.json`、hook 設定(`lefthook.yml` など)を読み、本共通規約の詳細にある検査表の適用条件で、実行する検査を決める。
|
|
18
18
|
- 適用条件を満たさない検査は実行せず、executor evidence の validations に `not_applicable` と非適用の理由を `reason` へ記録する。適用される検査が 1 つもない場合も同じく、該当する検査ごとに `not_applicable` と理由を記録する。
|
|
19
19
|
- `not_run` は、適用される検査を実行できたのに実行しなかった場合だけに使う。runner は `not_run` を検証失敗として扱い、タスクを先へ進めない。
|
|
20
|
+
- `pipeline.parent_validations` に設定された検査は executor evidence の validations に含めなくてよい。executor が同じ検査を `not_run` または `not_applicable` として含めても、同じリポジトリで実行した親 runner の結果を正とする。
|
|
20
21
|
- YAML 成果物を編集した場合、対応 schema `_SCHEMA_REF_` に従って記述する。`package.json` に `validate:schema:file` script がある場合だけ、`npm run validate:schema:file -- --schema _SCHEMA_REF_ --data <対象ファイル>` で schema 検査を実施する。適用した検査でエラーが出た場合は修正してから完了とする。
|
|
21
22
|
|
|
22
23
|
<!-- plan-essentials:end -->
|
|
@@ -30,7 +31,7 @@
|
|
|
30
31
|
- 編集・書き込みが作業ディレクトリ外(`external_directory`)として拒否された場合、原因はパス指定の誤り(誤った絶対パス・ディレクトリ名の取り違え)である。bash の heredoc などへ回避的に切り替えず、相対パスに直したうえで同じ編集ツールで再実行する。
|
|
31
32
|
- 作業用のファイル(編集用スクリプト、検証用の一時データなど)はリポジトリの外(一時ディレクトリ)または worktree の `tmp/` 配下に置き、終了前に削除する。使い捨てのファイルを最上位に作らない。`tmp/` 配下のファイルは commit の対象から除外される。
|
|
32
33
|
- 整形・静的検査は、この plan の完了手順または本共通規約で明示されたコマンドを実行する。変更対象に必要な test、build、schema 検証は、plan に個別記載がなくても実行してよい。同じ test script では対象限定と全件を同一 executor run 内で連続実行せず、どちらか一方に絞る。下表、plan、またはプロジェクト標準が全件 test を求める場合は、全件を1回だけ実行して対象限定の実行を省く。この制約は executor が sandbox 内で実行する test script の回数に対するものであり、親検証に設定された ID のコマンドは対象外である(親 runner が別途実行する)。実行したコマンド・対象・結果は result に記録する。
|
|
33
|
-
- executor / reporter pipeline で親 runner の検証が設定されている場合、executor は設定済み ID に対応するコマンドを sandbox 内で実行せず、executor 終了後に親 runner が固定許可リストから実行して evidence へ追記する。`validate-schema` は `npm run validate:schema`、`test-unit` は `npm run test:unit`、`test-integration` は `npm run test:integration` に対応する。executor は親検証と同じコマンドの対象限定版も追加せず、二重実行しない。
|
|
34
|
+
- executor / reporter pipeline で親 runner の検証が設定されている場合、executor は設定済み ID に対応するコマンドを sandbox 内で実行せず、executor 終了後に親 runner が固定許可リストから実行して evidence へ追記する。`validate-schema` は `npm run validate:schema`、`test-unit` は `npm run test:unit`、`test-integration` は `npm run test:integration` に対応する。executor は親検証と同じコマンドの対象限定版も追加せず、二重実行しない。executor が親検証のコマンドを validations に含めた場合も、同じリポジトリで実行された親 runner の結果を正とし、executor の `not_run` / `not_applicable` は pipeline を失敗させない。
|
|
34
35
|
- 適用条件の判定と `not_applicable` / `not_run` の使い分けは、要点に記した規則に従う。誤って `not_run` と記録しても、npm script・依存 package の不在、または SpecDojo サブコマンドの設定上の非適用を runner が機械的に確定できる場合は適用外として扱われるが、この救済を前提に記録を省略しない。
|
|
35
36
|
- 依存パッケージの有無は、対象リポジトリの `package.json` の `dependencies` / `devDependencies` と、リポジトリに固定された package manager の設定を基準に判断する。`npx` が未導入パッケージをネットワークから一時取得できることは、導入済みとはみなさない。設定ファイルがない、壊れているなどの理由で適用条件を確定できない検査は実行せず、validations に `not_applicable` として理由と次の確認事項を記録する。
|
|
36
37
|
- `npm init` が `package.json` に入れる仮の `test` script(`echo "Error: no test specified" && exit 1` と、引用符の有無・種類や空白だけが違う変種)は、常に失敗する仮置きであり、`test` script がないものとみなす。`npm test` は実行せず、validations に `not_applicable` と、仮の script である旨を `reason` に記録する。runner も同じ判断で `not_applicable` を受け付ける。本物の test script がある場合は適用される。
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
_FRONTMATTER_
|
|
2
|
+
|
|
3
|
+
# Register Post-run Review Plan: _ITEM_ID_ _ITEM_TITLE_
|
|
4
|
+
|
|
5
|
+
## 1. このフェーズで行うこと
|
|
6
|
+
|
|
7
|
+
`exec run --register` が統合した変更を読み取り専用で確認し、登録項目を自動で close できるかを判定する。
|
|
8
|
+
|
|
9
|
+
この review は成果物の grade ではなく、登録項目の完了判定である。grade サイドカーの有無や鮮度は判定条件にしない。verdict は `complete`、`complete-with-findings`、`incomplete` のいずれかにする。
|
|
10
|
+
|
|
11
|
+
## 2. 確認対象
|
|
12
|
+
|
|
13
|
+
- 登録項目: `_ITEM_PATH_`
|
|
14
|
+
- edit plan: `_EDIT_PLAN_REF_`
|
|
15
|
+
- edit result: `_EDIT_RESULT_REF_`
|
|
16
|
+
- executor evidence: `_EDIT_EVIDENCE_REF_`
|
|
17
|
+
- 統合前 commit: `_BASE_COMMIT_`
|
|
18
|
+
- 統合後 commit: `_OUTPUT_COMMIT_`
|
|
19
|
+
- review result: `_RESULT_REF_`
|
|
20
|
+
|
|
21
|
+
## 3. 完了条件
|
|
22
|
+
|
|
23
|
+
1. 登録項目の「完了条件」を edit result、統合差分、検証結果と照合している。
|
|
24
|
+
2. `_BASE_COMMIT_.._OUTPUT_COMMIT_` の差分に対象外の変更が混入していない。
|
|
25
|
+
3. edit result と executor evidence に、完了を妨げる失敗、未実施の必須検証、未解消の申し送りがない。
|
|
26
|
+
4. 完了条件を満たす場合は `complete`、軽微な finding を残して完了できる場合は `complete-with-findings`、未充足・根拠不足・検証失敗がある場合は `incomplete` とする。
|
|
27
|
+
5. review executor は、確認のための読み取り専用コマンドだけを実行し、成果物、登録項目、edit plan/result を変更しない。
|
|
28
|
+
|
|
29
|
+
## 4. 判断手順
|
|
30
|
+
|
|
31
|
+
1. 登録項目の概要と完了条件、edit plan、edit result を読む。
|
|
32
|
+
2. `git diff --stat _BASE_COMMIT_.._OUTPUT_COMMIT_` と `git diff --name-status _BASE_COMMIT_.._OUTPUT_COMMIT_` を実行し、必要に応じて同じ範囲の差分本文を読む。
|
|
33
|
+
3. executor evidence がある場合は、変更一覧、検証結果、block 理由、申し送りを確認する。`_EDIT_EVIDENCE_REF_` が `-` の場合は、edit result と差分から確認できる範囲を判断根拠に明記する。
|
|
34
|
+
4. 個票の各完了条件について、満たした根拠または未充足事項を具体的に記録する。
|
|
35
|
+
5. result の「評価結果の確認」には、この review では grade を使わず、edit の検証結果を確認したことを書く。
|
|
36
|
+
|
|
37
|
+
## 5. 完了手順
|
|
38
|
+
|
|
39
|
+
1. review result の全セクションを埋める。
|
|
40
|
+
2. `decision` に `complete`、`complete-with-findings`、`incomplete` のいずれかを記録する。
|
|
41
|
+
3. verdict にかかわらず、review 自体を完了できた場合は終了コード 0 とする。
|
|
42
|
+
|
|
43
|
+
## 6. 異常終了の条件
|
|
44
|
+
|
|
45
|
+
- 登録項目、edit plan/result、または統合差分を読めず review 自体を完了できない場合は終了コード 1 とする。
|
|
46
|
+
- review executor は review result を含むファイルを編集しない。result の記入は reporter が行う。
|
|
@@ -340,7 +340,40 @@ git push origin --delete feature/branch-policy
|
|
|
340
340
|
|
|
341
341
|
レビュー中または共同作業中の branch は無理に改名せず、完了後に新しい命名へ切り替える方が安全です。
|
|
342
342
|
|
|
343
|
-
## 10.
|
|
343
|
+
## 10. プロダクトリポジトリの統合先を指定する
|
|
344
|
+
|
|
345
|
+
別リポジトリ構成では、SpecDojo はプロダクトリポジトリにブランチ戦略を求めません。求めるのは、プロダクト側のルール(GitHub flow・git flow など)で決めた統合先を `repos[].integration_branch` に指定することだけで、ブランチ名に project ID を入れる必要はありません。`main` への取り込み方と merge の方式は、プロダクト側のルールに任せます。
|
|
346
|
+
|
|
347
|
+
### 10.1. GitHub flow と git flow での `integration_branch` の選び方
|
|
348
|
+
|
|
349
|
+
| プロダクト側の運用 | `repos[].integration_branch` の指定例 | 解説 |
|
|
350
|
+
| ------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
351
|
+
| GitHub flow | トピックのブランチ名(例: `feature/<topic>`) | トピックのブランチから統合先へ統合し、最終的に `main` へは PR で取り込む。トピックごとに書き換える場合もある |
|
|
352
|
+
| git flow | `develop` | feature を `develop` に統合し、`develop` から `main` へ release する。既存の `project/<id>/develop` の仕組みと同じ型で動く |
|
|
353
|
+
|
|
354
|
+
GitHub flow で register の worktree 実行ごとにトピックを変える場合は、`exec run --integration-branch <repo>=<branch>` で設定ファイルを書き換えずに統合先を指定できます。指定がない場合は `repos[].integration_branch`、それも省略した場合はそのリポジトリの現在のブランチを使います。
|
|
355
|
+
|
|
356
|
+
### 10.2. merge の方式ごとの `Refs:` の残り方
|
|
357
|
+
|
|
358
|
+
プロダクト側の exec branch 上の commit と merge commit には trace key `Refs: <project-id>:<item-id>` が付きます。merge の方式ごとに、この `Refs:` と記録した SHA の残り方が次のとおりです。
|
|
359
|
+
|
|
360
|
+
| merge の方式 | `Refs:`(プロダクト → プロジェクト) | 記録した SHA(プロジェクト → プロダクト) |
|
|
361
|
+
| ------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
362
|
+
| merge commit | 残る | 統合先の祖先として残る |
|
|
363
|
+
| rebase merge | exec branch 上の commit の `Refs:` は残る。runner の merge commit は直線化で落ちる | SHA が変わると先祖ではなくなる |
|
|
364
|
+
| squash merge | GitHub の設定次第。「Pull request title」だけでは消え、「Pull request title and commit details」なら残る | 統合先の祖先ではなくなる。GitHub では PR の参照から辿れる |
|
|
365
|
+
|
|
366
|
+
squash merge を使う場合は、squash の commit メッセージに `Refs:` の行を残す設定(GitHub で「Pull request title and commit details」を選ぶなど)にします。`Refs: <project-id>:<item-id>` が消えると追跡が切れるためです。
|
|
367
|
+
|
|
368
|
+
### 10.3. 追跡を trace key で行う
|
|
369
|
+
|
|
370
|
+
追跡は SHA ではなく trace key(`Refs: <project-id>:<item-id>`)を主にします。`git log --grep` で辿れます。
|
|
371
|
+
|
|
372
|
+
```bash
|
|
373
|
+
git log --grep "Refs: <project-id>:<item-id>" --oneline
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
## 11. 作業前後のチェックリスト
|
|
344
377
|
|
|
345
378
|
| 時点 | 確認内容 |
|
|
346
379
|
| -------------------- | -------------------------------------------------------------------- |
|
|
@@ -375,6 +375,8 @@ app1-workspace/
|
|
|
375
375
|
|
|
376
376
|
`.specdojo/specdojo.config.json` の project パスは `app1-specdojo/` を基準とします。`config init` はリポジトリのディレクトリ名から `run.worktree_base` を作るため、この例では `../app1-specdojo-worktrees` になります。SpecDojo CLI の実行、プロジェクト成果物の解決、doc index の生成、運用記録の検証は `app1-specdojo/` 側で行います。
|
|
377
377
|
|
|
378
|
+
VS Code でプロジェクトリポジトリとプロダクトリポジトリを同時に開く場合は、`specdojo config scaffold --workspace` を実行して `<project-id>.code-workspace` を作成します。ワークスペースにはプロジェクトリポジトリ自身(`.`)と宣言した各プロダクトリポジトリ(`repos[].path`)が含まれ、worktree や隣接するリポジトリをシームレスに操作できます。
|
|
379
|
+
|
|
378
380
|
### 10.3. プロダクト文書の配置
|
|
379
381
|
|
|
380
382
|
プロダクト文書は実装と同期して改訂するため、`app1/docs/ja/product/` に置きます。README、ソースコードから生成する API リファレンス、パッケージ利用者向けの手順など、コードと同じ revision で読む付属文書も `app1/` に置きます。
|