@elvis1513/auto-coding-skill 2.1.4 → 2.2.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.
Files changed (30) hide show
  1. package/README.md +163 -554
  2. package/cli/assets/agents/browser-debugger.toml +0 -1
  3. package/cli/assets/agents/docs-researcher.toml +0 -1
  4. package/cli/assets/agents/explorer.toml +1 -2
  5. package/cli/assets/agents/fixer.toml +2 -3
  6. package/cli/assets/agents/reviewer.toml +1 -2
  7. package/cli/assets/skill/SKILL.md +98 -207
  8. package/cli/assets/skill/data/templates/ENGINEERING.md +113 -468
  9. package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +11 -22
  10. package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +16 -39
  11. package/cli/assets/skill/data/templates/tools/ap.py +16 -0
  12. package/cli/assets/skill/scripts/ap.py +703 -138
  13. package/cli/assets/skill/scripts/scaffold_templates.py +136 -0
  14. package/cli/src/index.js +317 -42
  15. package/cli/tests/ap_profiles_test.py +428 -0
  16. package/cli/tests/index.test.js +376 -87
  17. package/package.json +3 -3
  18. package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +0 -38
  19. package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +0 -92
  20. package/cli/assets/skill/data/templates/docs/bugs/bug-list.md +0 -5
  21. package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +0 -19
  22. package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +0 -11
  23. package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +0 -49
  24. package/cli/assets/skill/data/templates/docs/interfaces/api-change-log.md +0 -11
  25. package/cli/assets/skill/data/templates/docs/interfaces/api.md +0 -36
  26. package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +0 -36
  27. package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +0 -25
  28. package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +0 -66
  29. package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +0 -35
  30. package/cli/assets/skill/data/templates/docs/testing/regression-matrix.md +0 -11
@@ -7,12 +7,12 @@ import { fileURLToPath } from "node:url";
7
7
  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
8
8
  const cli = path.join(repoRoot, "cli", "src", "index.js");
9
9
  const assetAp = path.join(repoRoot, "cli", "assets", "skill", "scripts", "ap.py");
10
- const managedAgentProfiles = {
11
- "browser-debugger.toml": { model: "gpt-5.6-sol", effort: "xhigh" },
12
- "docs-researcher.toml": { model: "gpt-5.6-terra", effort: "medium" },
13
- "explorer.toml": { model: "gpt-5.6-terra", effort: "medium" },
14
- "fixer.toml": { model: "gpt-5.3-codex-spark", effort: "medium" },
15
- "reviewer.toml": { model: "gpt-5.6-sol", effort: "xhigh" },
10
+ const managedAgentEfforts = {
11
+ "browser-debugger.toml": "xhigh",
12
+ "docs-researcher.toml": "medium",
13
+ "explorer.toml": "medium",
14
+ "fixer.toml": "medium",
15
+ "reviewer.toml": "xhigh",
16
16
  };
17
17
 
18
18
  function assert(condition, message) {
@@ -30,6 +30,7 @@ function tmpdir(name) {
30
30
  function run(command, args, options = {}) {
31
31
  const result = spawnSync(command, args, {
32
32
  cwd: options.cwd ?? repoRoot,
33
+ env: options.env ? { ...process.env, ...options.env } : process.env,
33
34
  encoding: "utf8",
34
35
  stdio: "pipe",
35
36
  });
@@ -45,6 +46,17 @@ function run(command, args, options = {}) {
45
46
  return result;
46
47
  }
47
48
 
49
+ function pythonEnvWithHome(home) {
50
+ const yamlSite = run(
51
+ "python3",
52
+ ["-c", "import pathlib, yaml; print(pathlib.Path(yaml.__file__).resolve().parent.parent)"],
53
+ ).stdout.trim();
54
+ return {
55
+ HOME: home,
56
+ PYTHONPATH: [yamlSite, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter),
57
+ };
58
+ }
59
+
48
60
  function writeFile(file, text) {
49
61
  fs.mkdirSync(path.dirname(file), { recursive: true });
50
62
  fs.writeFileSync(file, text);
@@ -56,14 +68,33 @@ function readTomlString(text, key, file) {
56
68
  return match[1];
57
69
  }
58
70
 
59
- function assertManagedAgentProfiles(agentsDir) {
60
- for (const [filename, expected] of Object.entries(managedAgentProfiles)) {
71
+ function managedAgentHeader(text) {
72
+ return text.split(/^developer_instructions\s*=\s*(?:"""|''')/m, 1)[0];
73
+ }
74
+
75
+ function assertManagedAgents(agentsDir, expectedModel = null) {
76
+ for (const [filename, effort] of Object.entries(managedAgentEfforts)) {
61
77
  const file = path.join(agentsDir, filename);
62
78
  assert(exists(file), `missing managed agent: ${filename}`);
63
79
  const text = fs.readFileSync(file, "utf8");
64
- assert(readTomlString(text, "model", file) === expected.model, `${filename}: unexpected model`);
65
- assert(readTomlString(text, "model_reasoning_effort", file) === expected.effort, `${filename}: unexpected reasoning effort`);
80
+ assert(readTomlString(text, "model_reasoning_effort", file) === effort, `${filename}: unexpected effort`);
81
+ const model = managedAgentHeader(text).match(/^model\s*=\s*"([^"]+)"\s*$/m)?.[1] ?? null;
82
+ assert(model === expectedModel, `${filename}: expected model ${expectedModel ?? "inherit"}, got ${model}`);
83
+ }
84
+ }
85
+
86
+ function listProjectFiles(root) {
87
+ const out = [];
88
+ function walk(current) {
89
+ for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
90
+ if (entry.name === ".git" || entry.name === "__pycache__" || entry.name.endsWith(".pyc")) continue;
91
+ const file = path.join(current, entry.name);
92
+ if (entry.isDirectory()) walk(file);
93
+ else out.push(file);
94
+ }
66
95
  }
96
+ walk(root);
97
+ return out;
67
98
  }
68
99
 
69
100
  function assertStatusOk(repo) {
@@ -83,26 +114,11 @@ function testPreflightAvoidsPartialInstall() {
83
114
 
84
115
  function testDestVariants() {
85
116
  const variants = [
86
- {
87
- name: "repo-root",
88
- dest(root) { return root; },
89
- },
90
- {
91
- name: "agents-root",
92
- dest(root) { return path.join(root, ".agents"); },
93
- },
94
- {
95
- name: "skills-dir",
96
- dest(root) { return path.join(root, ".agents", "skills"); },
97
- },
98
- {
99
- name: "agents-dir",
100
- dest(root) { return path.join(root, ".agents", "agents"); },
101
- },
102
- {
103
- name: "direct-skill",
104
- dest(root) { return path.join(root, ".agents", "skills", "auto-coding-skill"); },
105
- },
117
+ { name: "repo-root", dest(root) { return root; } },
118
+ { name: "agents-root", dest(root) { return path.join(root, ".agents"); } },
119
+ { name: "skills-dir", dest(root) { return path.join(root, ".agents", "skills"); } },
120
+ { name: "agents-dir", dest(root) { return path.join(root, ".agents", "agents"); } },
121
+ { name: "direct-skill", dest(root) { return path.join(root, ".agents", "skills", "auto-coding-skill"); } },
106
122
  ];
107
123
 
108
124
  for (const variant of variants) {
@@ -116,59 +132,187 @@ function testDestVariants() {
116
132
  }
117
133
  }
118
134
 
119
- function testSyncCreatesScaffoldAndStatusConverges() {
120
- const repo = tmpdir("sync-converges");
135
+ function testLauncherFallsBackToGlobalRuntime() {
136
+ const fakeHome = tmpdir("global-runtime-home");
137
+ const project = tmpdir("global-runtime-project");
138
+ const env = pythonEnvWithHome(fakeHome);
139
+ run("node", [cli, "init", "--mode", "global", "--dest", fakeHome, "--force"]);
140
+ const globalAp = path.join(fakeHome, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
141
+ run("python3", [globalAp, "--repo", project, "install"], { env });
142
+ assert(!exists(path.join(project, ".agents", "skills", "auto-coding-skill")), "fixture should rely on the global runtime only");
143
+ const launcher = path.join(project, "docs", "tools", "autopipeline", "ap.py");
144
+ const help = run("python3", [launcher, "--help"], { env });
145
+ assert(help.stdout.includes("autopipeline"), "project launcher should execute the global runtime when no project copy exists");
146
+ }
147
+
148
+ function testMinimalSyncConvergesWithinBudget() {
149
+ const repo = tmpdir("minimal-sync");
121
150
  run("node", [cli, "init"], { cwd: repo });
122
151
  const before = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
123
- assert(before.status !== 0, "status should fail before docs/tooling scaffold exists");
124
- assert(before.stdout.includes("autocoding sync"), "status should point to sync for missing scaffold");
152
+ assert(before.status !== 0, "status should fail before core scaffold exists");
125
153
  run("node", [cli, "sync", "--projects", repo]);
126
- assert(exists(path.join(repo, "docs", "ENGINEERING.md")), "sync should create docs/ENGINEERING.md when missing");
154
+
155
+ for (const rel of ["docs/ENGINEERING.md", "docs/tasks/taskbook.md", "docs/tasks/closure-log.md", "docs/tools/autopipeline/ap.py"]) {
156
+ assert(exists(path.join(repo, rel)), `missing core scaffold file: ${rel}`);
157
+ }
158
+ for (const rel of ["docs/interfaces/api.md", "docs/design/_TEMPLATE-DD.md", "docs/testing/regression-matrix.md", "docs/tools/autopipeline/core.py", "docs/tools/autopipeline/http_checks.py"]) {
159
+ assert(!exists(path.join(repo, rel)), `optional/duplicate file should not be installed: ${rel}`);
160
+ }
161
+
162
+ const files = listProjectFiles(repo);
163
+ const lines = files.reduce((total, file) => total + fs.readFileSync(file, "utf8").split(/\r?\n/).length, 0);
164
+ assert(files.length <= 20, `minimal scaffold file budget exceeded: ${files.length}`);
165
+ assert(lines <= 5500, `minimal scaffold line budget exceeded: ${lines}`);
166
+ const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
167
+ assert(engineering.includes("profile: \"auto\""), "engineering should enable adaptive profiles");
168
+ assert(engineering.includes("target_env_required: false"), "target verification should be opt-in in generic scaffold");
169
+ assert(engineering.includes(`name: "${path.basename(repo)}"`), "project name should be initialized automatically");
127
170
  assertStatusOk(repo);
171
+
172
+ const doctor = run("python3", [path.join(repo, "docs", "tools", "autopipeline", "ap.py"), "--repo", repo, "doctor"], { check: false });
173
+ const doctorOutput = `${doctor.stdout}\n${doctor.stderr}`;
174
+ assert(doctor.status !== 0 && doctorOutput.includes("gate command"), "empty generic repo should require only a real gate command");
175
+ for (const unexpected of ["target_env.name", "backend_root", "jenkins.base_url", "docs.api_doc"]) {
176
+ assert(!doctorOutput.includes(unexpected), `default doctor should not require optional field: ${unexpected}`);
177
+ }
128
178
  }
129
179
 
130
- function testSyncRefreshesManagedAgentProfiles() {
131
- const repo = tmpdir("sync-agent-profiles");
180
+ function testOrdinaryNodeTestIsNotPromotedToFullGate() {
181
+ const repo = tmpdir("node-gate-inference");
182
+ writeFile(path.join(repo, "package.json"), JSON.stringify({ scripts: { test: "node --test" } }, null, 2) + "\n");
132
183
  run("node", [cli, "init"], { cwd: repo });
133
- const agentsDir = path.join(repo, ".agents", "agents");
134
- assertManagedAgentProfiles(agentsDir);
135
184
  run("node", [cli, "sync", "--projects", repo]);
185
+ const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
186
+ assert(engineering.includes('gate_changed: "npm test"'), "ordinary test should seed the changed gate");
187
+ assert(engineering.includes('gate_standard: "npm test"'), "ordinary test should seed the standard gate");
188
+ assert(engineering.includes('gate_full: ""'), "ordinary test must not be promoted to the full gate");
136
189
 
137
- for (const filename of Object.keys(managedAgentProfiles)) {
190
+ run("git", ["init", "-q"], { cwd: repo });
191
+ run("git", ["config", "user.email", "test@example.com"], { cwd: repo });
192
+ run("git", ["config", "user.name", "Auto Coding Test"], { cwd: repo });
193
+ run("git", ["add", "-A"], { cwd: repo });
194
+ run("git", ["commit", "-qm", "baseline"], { cwd: repo });
195
+ writeFile(path.join(repo, "migrations", "001.sql"), "-- migration\n");
196
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
197
+ const doctor = run("python3", [launcher, "--repo", repo, "doctor"], { check: false });
198
+ assert(doctor.status !== 0 && `${doctor.stdout}\n${doctor.stderr}`.includes("full gate command"), "high-risk work should block until a dedicated full gate is configured");
199
+ }
200
+
201
+ function testManagedAgentModelsInheritAndOverridesSurvive() {
202
+ const repo = tmpdir("agent-models");
203
+ run("node", [cli, "init"], { cwd: repo });
204
+ const agentsDir = path.join(repo, ".agents", "agents");
205
+ assertManagedAgents(agentsDir);
206
+
207
+ const custom = path.join(agentsDir, "custom-local.toml");
208
+ const customText = 'name = "custom-local"\ndescription = "custom"\nmodel = "vendor/custom"\n';
209
+ writeFile(custom, customText);
210
+ for (const filename of Object.keys(managedAgentEfforts)) {
138
211
  const file = path.join(agentsDir, filename);
139
212
  const stale = fs.readFileSync(file, "utf8")
140
- .replace(/^model\s*=.*$/m, 'model = "gpt-5.5"')
213
+ .replace(/^description\s*=.*$/m, '$&\nmodel = "vendor/project-model"')
141
214
  .replace(/^model_reasoning_effort\s*=.*$/m, 'model_reasoning_effort = "low"');
142
215
  writeFile(file, stale);
143
216
  }
144
- const custom = path.join(agentsDir, "custom-local.toml");
145
- const customText = 'name = "custom-local"\ndescription = "custom"\nmodel = "gpt-5.5"\n';
146
- writeFile(custom, customText);
147
217
 
148
- const before = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
149
- assert(before.status !== 0, "status should detect stale managed agent profiles");
150
218
  run("node", [cli, "sync", "--projects", repo]);
151
-
152
- assertManagedAgentProfiles(agentsDir);
219
+ assertManagedAgents(agentsDir, "vendor/project-model");
153
220
  assert(fs.readFileSync(custom, "utf8") === customText, "sync should preserve custom agent contents");
154
221
  assertStatusOk(repo);
222
+
223
+ run("node", [cli, "sync", "--projects", repo, "--reset-agent-models"]);
224
+ assertManagedAgents(agentsDir);
225
+ assert(fs.readFileSync(custom, "utf8") === customText, "model reset must not touch custom agents");
155
226
  }
156
227
 
157
- function testForcePreservesCustomAgents() {
158
- const repo = tmpdir("custom-agent");
228
+ function testForcePreservesCustomAgentsAndModelOverrides() {
229
+ const repo = tmpdir("force-agent");
159
230
  run("node", [cli, "init", "--force"], { cwd: repo });
160
- const custom = path.join(repo, ".agents", "agents", "custom-local.toml");
161
- const customText = 'name = "custom-local"\ndescription = "custom"\nmodel = "gpt-5.5"\n';
231
+ const agentsDir = path.join(repo, ".agents", "agents");
232
+ const custom = path.join(agentsDir, "custom-local.toml");
233
+ const customText = 'name = "custom-local"\ndescription = "custom"\n';
162
234
  writeFile(custom, customText);
235
+ const explorer = path.join(agentsDir, "explorer.toml");
236
+ writeFile(explorer, fs.readFileSync(explorer, "utf8").replace(/^description\s*=.*$/m, '$&\nmodel = "vendor/override"'));
163
237
  run("node", [cli, "init", "--force"], { cwd: repo });
164
- assert(fs.readFileSync(custom, "utf8") === customText, "init --force should preserve custom agent contents");
238
+ assert(fs.readFileSync(custom, "utf8") === customText, "init --force should preserve custom agents");
239
+ assert(fs.readFileSync(explorer, "utf8").includes('model = "vendor/override"'), "init --force should preserve explicit managed-agent model overrides");
240
+ }
241
+
242
+ function testInvalidManagedAgentModelsFailStatusAndAreDroppedOnSync() {
243
+ const repo = tmpdir("invalid-agent-model");
244
+ run("node", [cli, "init"], { cwd: repo });
245
+ run("node", [cli, "sync", "--projects", repo]);
246
+ const explorer = path.join(repo, ".agents", "agents", "explorer.toml");
247
+
248
+ for (const invalidLine of ["model = [", 'model = ""']) {
249
+ const canonical = fs.readFileSync(explorer, "utf8").replace(/^model\s*=.*(?:\r?\n|$)/m, "");
250
+ writeFile(explorer, canonical.replace(/^description\s*=.*$/m, `$&\n${invalidLine}`));
251
+
252
+ const status = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
253
+ assert(status.status !== 0, `status should fail for invalid managed model: ${invalidLine}`);
254
+ const parsed = JSON.parse(status.stdout).results[0];
255
+ const finding = parsed.agentDiffs.find(item => item.path === "explorer.toml");
256
+ assert(finding?.status === "invalid-model", `status should report invalid-model: ${status.stdout}`);
257
+ assert(finding.detail?.includes("model"), `invalid model should include a useful detail: ${status.stdout}`);
258
+ assert(parsed.agentBindings.find(item => item.agent === "explorer.toml")?.model === "invalid", "invalid binding should be explicit in status JSON");
259
+
260
+ run("node", [cli, "sync", "--projects", repo]);
261
+ assert(!/^model\s*=/m.test(managedAgentHeader(fs.readFileSync(explorer, "utf8"))), "sync must not preserve an invalid model override");
262
+ assertStatusOk(repo);
263
+ }
264
+ }
265
+
266
+ function testModelTextInsideInstructionsIsNotPromotedToOverride() {
267
+ const repo = tmpdir("model-in-instructions");
268
+ run("node", [cli, "init"], { cwd: repo });
269
+ run("node", [cli, "sync", "--projects", repo]);
270
+ const explorer = path.join(repo, ".agents", "agents", "explorer.toml");
271
+ const withExample = fs.readFileSync(explorer, "utf8").replace(
272
+ 'developer_instructions = """',
273
+ 'developer_instructions = """\nmodel = "example/in-docs"',
274
+ );
275
+ writeFile(explorer, withExample);
276
+
277
+ run("node", [cli, "sync", "--projects", repo]);
278
+ const synced = fs.readFileSync(explorer, "utf8");
279
+ assert(!/^model\s*=/m.test(managedAgentHeader(synced)), "instruction text must not become a top-level model override");
280
+ assert(!synced.includes('model = "example/in-docs"'), "sync should refresh stale managed instructions without promoting their example model");
281
+ assertStatusOk(repo);
282
+ }
283
+
284
+ function testCommandSpecificArgumentsAreRejectedBeforeWrites() {
285
+ const dryRunDest = tmpdir("invalid-init-dry-run");
286
+ const invalidInit = run("node", [cli, "init", "--dest", dryRunDest, "--dry-run"], { check: false });
287
+ assert(invalidInit.status !== 0 && invalidInit.stderr.includes("not valid for 'init'"), "init should reject --dry-run");
288
+ assert(!exists(path.join(dryRunDest, ".agents")), "invalid init arguments must not write files");
289
+
290
+ const positionalDest = tmpdir("invalid-init-positional");
291
+ const invalidPositional = run("node", [cli, "init", "unexpected-project"], { cwd: positionalDest, check: false });
292
+ assert(invalidPositional.status !== 0 && invalidPositional.stderr.includes("not valid for 'init'"), "init should reject positional project arguments");
293
+ assert(!exists(path.join(positionalDest, ".agents")), "invalid positional init must not write files");
294
+
295
+ const repo = tmpdir("invalid-command-options");
296
+ run("node", [cli, "init"], { cwd: repo });
297
+ run("node", [cli, "sync", "--projects", repo]);
298
+ const explorer = path.join(repo, ".agents", "agents", "explorer.toml");
299
+ writeFile(explorer, fs.readFileSync(explorer, "utf8").replace(/^description\s*=.*$/m, '$&\nmodel = "vendor/keep"'));
300
+
301
+ const invalidStatus = run("node", [cli, "status", "--projects", repo, "--reset-agent-models"], { check: false });
302
+ assert(invalidStatus.status !== 0 && invalidStatus.stderr.includes("not valid for 'status'"), "status should reject --reset-agent-models");
303
+ assert(managedAgentHeader(fs.readFileSync(explorer, "utf8")).includes('model = "vendor/keep"'), "rejected status command must not reset models");
304
+
305
+ const invalidSync = run("node", [cli, "sync", "--projects", repo, "--force"], { check: false });
306
+ assert(invalidSync.status !== 0 && invalidSync.stderr.includes("not valid for 'sync'"), "sync should reject --force");
307
+ const validDryRun = run("node", [cli, "sync", "--projects", repo, "--dry-run", "--reset-agent-models"]);
308
+ assert(validDryRun.status === 0, "sync should accept its documented dry-run/reset options together");
309
+ assert(managedAgentHeader(fs.readFileSync(explorer, "utf8")).includes('model = "vendor/keep"'), "dry-run must not reset models on disk");
165
310
  }
166
311
 
167
312
  function testBridgeIsGeneric() {
168
313
  const repo = tmpdir("bridge");
169
314
  run("node", [cli, "init", "--force"], { cwd: repo });
170
- const ap = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
171
- run("python3", [ap, "--repo", repo, "install", "--bridges"]);
315
+ run("python3", [assetAp, "--repo", repo, "install", "--bridges"]);
172
316
  assert(exists(path.join(repo, "AGENTS.md")), "generic bridge should be created");
173
317
  for (const filename of [`CO${"DEX.md"}`, `CLA${"UDE.md"}`]) {
174
318
  assert(!exists(path.join(repo, filename)), "client-named bridge should not be created");
@@ -187,56 +331,201 @@ function testUpgradeCleansManagedBridgeExtrasOnly() {
187
331
  assert(exists(path.join(repo, ".agents", "skills", "auto-coding-skill", "custom.txt")), "non-managed extra should remain");
188
332
  }
189
333
 
334
+ function testOptionalDocsAndLegacyToolsDoNotCauseDrift() {
335
+ const repo = tmpdir("legacy-extras");
336
+ run("node", [cli, "init"], { cwd: repo });
337
+ run("node", [cli, "sync", "--projects", repo]);
338
+ writeFile(path.join(repo, "docs", "interfaces", "api.md"), "# Existing API\n");
339
+ writeFile(path.join(repo, "docs", "tools", "autopipeline", "core.py"), "# legacy copy\n");
340
+ writeFile(path.join(repo, "docs", "tools", "autopipeline", "http_checks.py"), "# legacy copy\n");
341
+ assertStatusOk(repo);
342
+ }
343
+
344
+ function testOptionalScaffoldIsOnDemandAndIdempotent() {
345
+ const repo = tmpdir("optional-scaffold");
346
+ run("node", [cli, "init"], { cwd: repo });
347
+ run("node", [cli, "sync", "--projects", repo]);
348
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
349
+ run("python3", [launcher, "--repo", repo, "scaffold", "api", "--write"]);
350
+ const api = path.join(repo, "docs", "interfaces", "api.md");
351
+ assert(exists(api), "api scaffold should be created on demand");
352
+ writeFile(api, "# User API\n");
353
+ run("python3", [launcher, "--repo", repo, "scaffold", "api", "--write"]);
354
+ assert(fs.readFileSync(api, "utf8") === "# User API\n", "scaffold should not overwrite existing docs without --force");
355
+ }
356
+
357
+ function testTestingScaffoldMatchesCheckMatrixSchema() {
358
+ const repo = tmpdir("testing-scaffold");
359
+ run("node", [cli, "init"], { cwd: repo });
360
+ run("node", [cli, "sync", "--projects", repo]);
361
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
362
+ run("python3", [launcher, "--repo", repo, "scaffold", "testing", "--write"]);
363
+
364
+ const matrix = path.join(repo, "docs", "testing", "regression-matrix.md");
365
+ const initial = fs.readFileSync(matrix, "utf8");
366
+ const row = initial.split(/\r?\n/).find(line => line.startsWith("| R-001 |"));
367
+ assert(row, "testing scaffold should include R-001");
368
+ const columns = row.split("|").slice(1, -1).map(value => value.trim());
369
+ assert(columns.length === 8, `regression row should have 8 columns, got ${columns.length}`);
370
+
371
+ const pending = run("python3", [launcher, "--repo", repo, "check-matrix"], { check: false });
372
+ const pendingOutput = `${pending.stdout}\n${pending.stderr}`;
373
+ assert(pending.status !== 0 && pendingOutput.includes("R-001: TODO"), `generated matrix should be parsed as pending: ${pendingOutput}`);
374
+ assert(!pendingOutput.includes("No regression rows found"), "generated matrix must not be rejected as malformed");
375
+
376
+ writeFile(matrix, initial.replace("| TODO | <evidence> |", "| PASS | logs/regression.txt |"));
377
+ run("python3", [launcher, "--repo", repo, "check-matrix"]);
378
+ }
379
+
380
+ function testReviewScaffoldLeavesBaselineGenerationToBaselineCommand() {
381
+ const repo = tmpdir("review-scaffold");
382
+ run("node", [cli, "init"], { cwd: repo });
383
+ run("node", [cli, "sync", "--projects", repo]);
384
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
385
+
386
+ run("python3", [launcher, "--repo", repo, "scaffold", "review", "--write"]);
387
+ assert(exists(path.join(repo, "docs", "reviews", "_TEMPLATE-REVIEW.md")), "review scaffold should create its review template");
388
+ for (const rel of ["docs/reviews/project-health-baseline.md", "docs/reviews/optimization-backlog.md"]) {
389
+ assert(!exists(path.join(repo, rel)), `review scaffold must leave generated baseline output absent: ${rel}`);
390
+ }
391
+
392
+ run("git", ["init", "-q"], { cwd: repo });
393
+ run("git", ["config", "user.email", "test@example.com"], { cwd: repo });
394
+ run("git", ["config", "user.name", "Auto Coding Test"], { cwd: repo });
395
+ run("git", ["add", "-A"], { cwd: repo });
396
+ run("git", ["commit", "-qm", "baseline"], { cwd: repo });
397
+ run("python3", [launcher, "--repo", repo, "baseline", "init", "--write"]);
398
+ assert(fs.readFileSync(path.join(repo, "docs", "reviews", "project-health-baseline.md"), "utf8").includes("Generated by `ap.py baseline init`"), "baseline command should generate the health baseline");
399
+ assert(fs.readFileSync(path.join(repo, "docs", "reviews", "optimization-backlog.md"), "utf8").includes("Generated by `ap.py baseline init`"), "baseline command should generate the optimization backlog");
400
+ }
401
+
402
+ function testUpgradePrefersModernProjectAssetsAndIgnoresRetiredTemplates() {
403
+ const repo = tmpdir("upgrade-modern-source");
404
+ const fakeHome = tmpdir("upgrade-stale-home");
405
+ run("git", ["init", "-q"], { cwd: repo });
406
+ run("node", [cli, "init"], { cwd: repo });
407
+ run("node", [cli, "sync", "--projects", repo]);
408
+
409
+ const projectSkill = path.join(repo, ".agents", "skills", "auto-coding-skill");
410
+ writeFile(path.join(projectSkill, "data", "templates", "docs", "interfaces", "api.md"), "# Retired project template\n");
411
+
412
+ const staleGlobal = path.join(fakeHome, ".agents", "skills", "auto-coding-skill");
413
+ writeFile(path.join(staleGlobal, "scripts", "ap.py"), "# legacy runtime\n");
414
+ writeFile(path.join(staleGlobal, "data", "templates", "ENGINEERING.md"), "---\n---\n");
415
+ writeFile(path.join(staleGlobal, "data", "templates", "docs", "interfaces", "api.md"), "# Retired global template\n");
416
+
417
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
418
+ const result = run(
419
+ "python3",
420
+ [launcher, "--repo", repo, "upgrade", "--write", "--json"],
421
+ { env: pythonEnvWithHome(fakeHome) },
422
+ );
423
+ const parsed = JSON.parse(result.stdout);
424
+ assert(fs.realpathSync(parsed.source_root) === fs.realpathSync(projectSkill), `upgrade should prefer the modern project asset root: ${result.stdout}`);
425
+ assert(!exists(path.join(repo, "docs", "interfaces", "api.md")), "upgrade must not materialize retired optional templates");
426
+ }
427
+
428
+ function testUpgradeInitializesNewEngineeringDefaults() {
429
+ const repo = tmpdir("upgrade-engineering-defaults");
430
+ const fakeHome = tmpdir("upgrade-engineering-home");
431
+ run("git", ["init", "-q"], { cwd: repo });
432
+ writeFile(path.join(repo, "package.json"), JSON.stringify({ scripts: { test: "node --test", "test:full": "node --test" } }, null, 2) + "\n");
433
+ run("node", [cli, "init"], { cwd: repo });
434
+
435
+ const projectAp = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
436
+ run("python3", [projectAp, "--repo", repo, "upgrade", "--write"], { env: pythonEnvWithHome(fakeHome) });
437
+
438
+ const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
439
+ assert(engineering.includes(`name: "${path.basename(repo)}"`), "upgrade should initialize a newly created project name");
440
+ for (const key of ["gate_changed", "gate_standard"]) {
441
+ assert(engineering.includes(`${key}: "npm test"`), `upgrade should initialize commands.${key} from the ordinary Node test script`);
442
+ }
443
+ assert(engineering.includes('gate_full: "npm run test:full"'), "upgrade should infer full only from a dedicated test:full script");
444
+ }
445
+
446
+ function testUpgradeInstallsRuntimeRequiredByLauncher() {
447
+ const repo = tmpdir("upgrade-missing-runtime");
448
+ run("git", ["init", "-q"], { cwd: repo });
449
+ run("python3", [assetAp, "--repo", repo, "upgrade", "--write"]);
450
+ const projectRuntime = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
451
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
452
+ assert(exists(projectRuntime), "upgrade should install the runtime required by the new launcher");
453
+ const help = run("python3", [launcher, "--help"]);
454
+ assert(help.stdout.includes("autopipeline"), "upgraded launcher should remain executable");
455
+ }
456
+
190
457
  function testLedgerArchiveRecognizesSettledStatuses() {
191
458
  const repo = tmpdir("ledger-status");
192
459
  run("git", ["init", "-q"], { cwd: repo });
193
460
  run("node", [cli, "init", "--force"], { cwd: repo });
194
461
  run("node", [cli, "sync", "--projects", repo]);
195
462
  writeFile(path.join(repo, "docs", "tasks", "taskbook.md"), [
196
- "# Taskbook",
197
- "",
198
- "## Task T001 - superseded work",
199
- "- Status: Superseded by T002",
200
- "",
201
- "## Task T002 - external dependency",
202
- "- Status: External Dependency",
203
- "",
204
- "## Task T003 - deployed work",
205
- "- Status: Deployed / Jenkins #123 SUCCESS",
206
- "",
207
- "## Task T004 - local pass",
208
- "- Status: Local PASS,待生产迁移窗口",
209
- "",
463
+ "# Taskbook", "", "## Task T001 - superseded work", "- Status: Superseded by T002", "",
464
+ "## Task T002 - external dependency", "- Status: External Dependency", "",
465
+ "## Task T003 - deployed work", "- Status: Deployed / Jenkins #123 SUCCESS", "",
466
+ "## Task T004 - local pass", "- Status: Local PASS,待生产迁移窗口", "",
467
+ "## Task T005 - markdown done", "- Status: `Done / PASS`", "",
468
+ "## Task T006 - localized done", "- 状态:Done(PASS)", "",
210
469
  ].join("\n"));
211
470
  writeFile(path.join(repo, "docs", "tasks", "closure-log.md"), [
212
- "# Closure Log",
213
- "",
214
- "## T001 - superseded work",
215
- "- Result: DEV-CLOSED",
216
- "",
217
- "## T002 - external dependency",
218
- "- Result: PARTIAL",
219
- "",
220
- "## T003 - deployed work",
221
- "- Result: PASS",
222
- "",
223
- "## T004 - local pass",
224
- "- Result: DEV-CLOSED",
225
- "",
471
+ "# Closure Log", "", "## T001 - superseded work", "- Result: DEV-CLOSED", "",
472
+ "## T002 - external dependency", "- Result: PARTIAL", "",
473
+ "## T003 - deployed work", "- Result: PASS", "",
474
+ "## T004 - local pass", "- Result: DEV-CLOSED", "",
475
+ "## T005 - markdown done", "- Result: PASS", "",
476
+ "## T006 - localized done", "- Result: PASS", "",
226
477
  ].join("\n"));
227
478
  const result = run("python3", [assetAp, "--repo", repo, "docs-ledger-archive", "--plan", "--period", "2026-06", "--json"]);
228
479
  const parsed = JSON.parse(result.stdout);
229
- assert(parsed.counts.taskbook_sections === 4, `settled task sections should archive: ${result.stdout}`);
480
+ assert(parsed.counts.taskbook_sections === 6, `settled task sections should archive: ${result.stdout}`);
230
481
  assert(parsed.active_task_conflicts.length === 0, `settled statuses should not conflict: ${result.stdout}`);
231
482
  }
232
483
 
484
+ function testLedgerArchiveUpdatesExistingPeriodIndex() {
485
+ const repo = tmpdir("ledger-index-update");
486
+ run("git", ["init", "-q"], { cwd: repo });
487
+ run("node", [cli, "init", "--force"], { cwd: repo });
488
+ run("node", [cli, "sync", "--projects", repo]);
489
+
490
+ const taskbook = path.join(repo, "docs", "tasks", "taskbook.md");
491
+ const closure = path.join(repo, "docs", "tasks", "closure-log.md");
492
+ const designDir = path.join(repo, "docs", "design");
493
+ writeFile(taskbook, "# Taskbook\n\n## Task T001 - first\n- Status: Done\n");
494
+ writeFile(closure, "# Closure Log\n\n## T001 - first\n- Result: PASS\n");
495
+ writeFile(path.join(designDir, "T001-first.md"), "# T001\n");
496
+ run("python3", [assetAp, "--repo", repo, "docs-ledger-archive", "--write", "--period", "2026-06", "--json"]);
497
+
498
+ fs.appendFileSync(taskbook, "\n## Task T002 - second\n- Status: `Done / PASS`\n");
499
+ fs.appendFileSync(closure, "\n## T002 - second\n- Result: PASS\n");
500
+ writeFile(path.join(designDir, "T002-second.md"), "# T002\n");
501
+ run("python3", [assetAp, "--repo", repo, "docs-ledger-archive", "--write", "--period", "2026-06", "--json"]);
502
+
503
+ const index = fs.readFileSync(path.join(repo, "docs", "tasks", "archive-index.md"), "utf8");
504
+ assert((index.match(/^## 2026-06$/gm) || []).length === 1, `archive period should be unique: ${index}`);
505
+ assert(index.includes("(2 sections)"), `archive index should report cumulative task/closure counts: ${index}`);
506
+ assert(index.includes("(2 files)"), `archive index should report cumulative design count: ${index}`);
507
+ }
508
+
233
509
  testPreflightAvoidsPartialInstall();
234
510
  testDestVariants();
235
- testSyncCreatesScaffoldAndStatusConverges();
236
- testSyncRefreshesManagedAgentProfiles();
237
- testForcePreservesCustomAgents();
511
+ testLauncherFallsBackToGlobalRuntime();
512
+ testMinimalSyncConvergesWithinBudget();
513
+ testOrdinaryNodeTestIsNotPromotedToFullGate();
514
+ testManagedAgentModelsInheritAndOverridesSurvive();
515
+ testForcePreservesCustomAgentsAndModelOverrides();
516
+ testInvalidManagedAgentModelsFailStatusAndAreDroppedOnSync();
517
+ testModelTextInsideInstructionsIsNotPromotedToOverride();
518
+ testCommandSpecificArgumentsAreRejectedBeforeWrites();
238
519
  testBridgeIsGeneric();
239
520
  testUpgradeCleansManagedBridgeExtrasOnly();
521
+ testOptionalDocsAndLegacyToolsDoNotCauseDrift();
522
+ testOptionalScaffoldIsOnDemandAndIdempotent();
523
+ testTestingScaffoldMatchesCheckMatrixSchema();
524
+ testReviewScaffoldLeavesBaselineGenerationToBaselineCommand();
525
+ testUpgradePrefersModernProjectAssetsAndIgnoresRetiredTemplates();
526
+ testUpgradeInitializesNewEngineeringDefaults();
527
+ testUpgradeInstallsRuntimeRequiredByLauncher();
240
528
  testLedgerArchiveRecognizesSettledStatuses();
529
+ testLedgerArchiveUpdatesExistingPeriodIndex();
241
530
 
242
531
  console.log("cli-installer-regression-ok");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvis1513/auto-coding-skill",
3
- "version": "2.1.4",
3
+ "version": "2.2.1",
4
4
  "description": "CLI installer for a generic .agents engineering workflow with optional CI/Jenkins and target-environment verification.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -15,8 +15,8 @@
15
15
  "LICENSE"
16
16
  ],
17
17
  "scripts": {
18
- "test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js && python3 -c \"import ast, pathlib; files = ['cli/assets/skill/scripts/ap.py', 'cli/assets/skill/scripts/core.py', 'cli/assets/skill/scripts/http_checks.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-asset-grammar-ok')\" && python3 -m py_compile cli/assets/skill/scripts/ap.py cli/assets/skill/scripts/core.py cli/assets/skill/scripts/http_checks.py && python3 -c \"import pathlib, tomllib; files = sorted(pathlib.Path('cli/assets/agents').glob('*.toml')); [tomllib.loads(path.read_text(encoding='utf-8')) for path in files]; print('asset-agent-toml-ok')\" && find cli -type d -name '__pycache__' -prune -exec rm -rf {} +",
19
- "test:src": "python3 -c \"import ast, pathlib; files = ['src/auto-coding-skill/scripts/ap.py', 'src/auto-coding-skill/scripts/core.py', 'src/auto-coding-skill/scripts/http_checks.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-src-grammar-ok')\" && python3 -m py_compile src/auto-coding-skill/scripts/ap.py src/auto-coding-skill/scripts/core.py src/auto-coding-skill/scripts/http_checks.py && python3 -c \"import pathlib, tomllib; files = sorted(pathlib.Path('src/agents').glob('*.toml')); [tomllib.loads(path.read_text(encoding='utf-8')) for path in files]; print('src-agent-toml-ok')\" && find src -type d -name '__pycache__' -prune -exec rm -rf {} +",
18
+ "test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js && python3 -c \"import ast, pathlib; files = ['cli/assets/skill/scripts/ap.py', 'cli/assets/skill/scripts/core.py', 'cli/assets/skill/scripts/http_checks.py', 'cli/assets/skill/scripts/scaffold_templates.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-asset-grammar-ok')\" && python3 -m py_compile cli/assets/skill/scripts/ap.py cli/assets/skill/scripts/core.py cli/assets/skill/scripts/http_checks.py cli/assets/skill/scripts/scaffold_templates.py && python3 cli/tests/ap_profiles_test.py && python3 -c \"import pathlib, tomllib; files = sorted(pathlib.Path('cli/assets/agents').glob('*.toml')); [tomllib.loads(path.read_text(encoding='utf-8')) for path in files]; print('asset-agent-toml-ok')\" && find cli -type d -name '__pycache__' -prune -exec rm -rf {} +",
19
+ "test:src": "python3 -c \"import ast, pathlib; files = ['src/auto-coding-skill/scripts/ap.py', 'src/auto-coding-skill/scripts/core.py', 'src/auto-coding-skill/scripts/http_checks.py', 'src/auto-coding-skill/scripts/scaffold_templates.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-src-grammar-ok')\" && python3 -m py_compile src/auto-coding-skill/scripts/ap.py src/auto-coding-skill/scripts/core.py src/auto-coding-skill/scripts/http_checks.py src/auto-coding-skill/scripts/scaffold_templates.py && python3 -c \"import pathlib, tomllib; files = sorted(pathlib.Path('src/agents').glob('*.toml')); [tomllib.loads(path.read_text(encoding='utf-8')) for path in files]; print('src-agent-toml-ok')\" && find src -type d -name '__pycache__' -prune -exec rm -rf {} +",
20
20
  "check:assets": "node cli/src/sync-assets.js --check",
21
21
  "sync-assets": "node cli/src/sync-assets.js",
22
22
  "release:check": "npm run sync-assets && npm run check:assets && npm run test:src && npm run test && npm pack --dry-run"
@@ -1,38 +0,0 @@
1
- # ADR-0000 — <Decision Title>
2
-
3
- - Status: Proposed | Accepted | Superseded
4
- - Date: YYYY-MM-DD
5
- - Owner: <name / team>
6
- - Related task: <task id / link>
7
-
8
- ## 1. Context
9
-
10
- What problem or structural pressure requires an architectural decision?
11
-
12
- ## 2. Decision
13
-
14
- What decision is being made? Keep it specific and actionable.
15
-
16
- ## 3. Alternatives Considered
17
-
18
- | Option | Pros | Cons | Reason not selected |
19
- | --- | --- | --- | --- |
20
- | A | | | |
21
- | B | | | |
22
-
23
- ## 4. Consequences
24
-
25
- - Positive:
26
- - Negative / tradeoffs:
27
- - Migration impact:
28
- - Compatibility impact:
29
-
30
- ## 5. Validation
31
-
32
- - Tests:
33
- - Gate:
34
- - Runtime / benchmark / security evidence:
35
-
36
- ## 6. Rollback
37
-
38
- How can this decision be reverted or superseded if it proves wrong?