@elvis1513/auto-coding-skill 4.2.8 → 4.3.0

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.
@@ -1,13 +1,16 @@
1
1
  import fs from "node:fs";
2
2
  import os from "node:os";
3
3
  import path from "node:path";
4
+ import crypto from "node:crypto";
4
5
  import zlib from "node:zlib";
5
- import { spawnSync } from "node:child_process";
6
+ import { spawn, spawnSync } from "node:child_process";
6
7
  import { fileURLToPath } from "node:url";
7
8
 
8
9
  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
9
10
  const cli = path.join(repoRoot, "cli", "src", "index.js");
10
11
  const assetAp = path.join(repoRoot, "cli", "assets", "skill", "scripts", "ap.py");
12
+ const projectConfigRelativePath = path.join("docs", "project", "auto-coding-skill.yaml");
13
+ const projectConfigSchema = "auto-coding-skill/project-config/v1";
11
14
  // Frozen gzip/base64 fixture of the official v2.2.0 ENGINEERING body (frontmatter excluded).
12
15
  const officialV220EngineeringBody = zlib.gunzipSync(Buffer.from(
13
16
  "H4sIAAAAAAAAE51YwY7bOBK98ysKk8PuApaMnezuoTMYwNPuzfZObyboJDPHFk2WJMYUqWGR7mjQH78oUpLdQA6ZviRtWSSrXr33qmjxCm5cZxxiMK6D33w4ttY/CvGxNwStsQiGIPYIZFxnEQbpkrR2gkEaF6VxqOFxXgXKu9Z0KchovKvhZ8QRTATjxFsTa9hpDX7k76QFQsV/EXhnJ3js0eVjxuA/o4qATh4slqMDWhlRA6XQSoW1EK9ewc0XVIl34CUcKAnRLJHU87MrkCn6BggtqshnIfgWYh8QAduWYzjhusOVEE/wvnyAJ/g4jUZJm/ODJ3grIz+9tp5SQBi8RngST1BVFXzlX/EEzWBU8A08gfaKthEpUsX5buCEYQIapLVgyJf85nNUL12HmlfhqexDUTotg+atfNDGyTBBizJyINJp0Mi5LDssr19u0Zuur4KhI++x/2krU+y3o5wGdHGrcbR+2h6SsXquIvgAGpWVATXwYuDF8ARtshaeOAHTTvAkRFMwNnMp5Yy2DzV87L8CM78p7aOcaAFoc5HhRvhwGW0NO1g/AZmOyaOkcz7CAUH7R9cFqRk+E3uQcH13C62VOQEpFj6FZLGGnQP8MlqjTATnXcWRr2EFHK1USJkzfyGw/nHrfBikhYMktMZhfUExrv/VDEMD0pKHgL8nE2bWZpw6GZmv7+comvyZY6EGBjktCEMzytgTA6H8MEin89+k/IjNJldYulU7oplDbmq4niWH55U1H/LAxzfwVx/AYifVdPE9f/XALzV/g9YHcYaXk3sDEqzp+sgArkyaF4P2SMDYK59cBEkgn2X66hX8zzjDoD1zAyHuCziaj4QZV40ntH5kDl4JUcFzdJsraDSeGg6kmYF+9tICwxUUDm6+Sih4TijeYWZF7eSA/EBGsCgpZoNIxNaTE1rSfrMmg8CSLQZy+QatFiZgNTElmW8YlCFcZL1ZMS11zeDlQhNHltM0qjholKHD+IDu9DBTSzd50fPXPqM7Gkfnd4S4KzVfqnbEiYCS6rlgZyLkMhcmbKD5PRl1fGCT4k/z/9Jp0WRfaCAgmz5QGkcfIuoa7pODRnsWe5Pril+kijAY4nZRtQatBm1k5zxFo6gW4rcMU04MLrNgVyimz8BoDc05+7pHaWP/wDJ8SME2Jaz5KUunKd2lDd5FdHp7kOqITsOn+7vZljg6BgiJrRadHr1xEVSP6kglT+s747aEKmCEgC0GdOwH5w51kGQU+0PP4a7b1ZCz+m+pAxgSzzOZC9QUizKRsqFsP/tDDnADhyCd6jcgQzStVIshw4BRahnlRkQzoE9xA59ut7v3t5AIQwkbRkn06IOGk7SJww2A7mSCd6yri0Rq+OQSoRZr76XeJ6uXwsoD5QUy9hgg9tLxBGAXa83u2HurMVBR+h5bmWxcBwAh9s8E/fca7lFqiOswwfGyOcrSEaKkI6CLYarF94VOuUySPGsp+NT10CgribjZVFUWSmnqtXjN2yvOPA8o3EyRIkPTJvYWbhbsVfgGVEAW636/3e3vLwpqnGb+oa7FP2q4HUaLGTTe0KFCIu60RbqQmNSAXwxF/mNROcWQ1NqJAyZCyOSiWvyzJFWmGPL2hHrtN8Ux/7Um0exvfq2u7375cLNvNlm6Js4VTtTXQvxn9emstLmPXYpoxnw9UdpLc/6e2wXverHp6xp+LZ18pixc324XIudqZRVWl4ya5zDKmC3Bv999+MC+8e/d7d3sue939x9vd3cNy3LgkidpAU9GMxtrnjFzKXsfTJSZDz5oDDMdCW7evb19d3Nzf/vu7SZT5eD9cSuD6s0JabNUmKVrXMQcFIQcD20gYBeQyHi3PaTu/FzN89sSCO/DYpvFUt4SMbNj4cM80O59bn2DDEdIDvMEinr2ELZWBqFI48NKitFboyYh3qLDYNQFXZZ1zBx9MuTDBAeeCbKq8vQ05SkhIBtuURCZP3Aj2uSyhMvHIpoOv1TsK5rj9iFWB5+40Uzz1MQ+kzK1JzhYr45nHYhmjapG1/qgctpX5T3jujzeLZSz07kdchPA0ZOJPkyVy2UUuUQRz6JQfhiNxZBH4BV5iPLIUyEqLJ/9CQN0M05ODsZ1oscUTGkecJ+1tQqwRztiKDSVJ280uy1/kdxyZQhIo3dkDsaaaJBE9CBtQKknsMzsDCq9AV1KS6M1PNtohAED2gmiB5LRUDvluchhmXxqIT4RQrNMhmCciVBVj8FEhKpKo5YRq4JTM3efFadHo3ElwnzDqMVOKRxjHrcp+pDvHhoPPOda7zoCU3SdEcrpLafnfmd9V7h37WfY18uW9ipxQamIbmYYkJJt68vIH7PkMiNWuz6rrvjQIh0+Ca6zpQoaURlpzR+oz8ec73PZ4R2izkPxcCVE0zBovRin2Hv3er4aeW+J7yR+NGNJSY71OJ1DlKNZ4P2zS2efeOHqZ2R+4R4BTwYfX7qaRcO0fnH6q729cIdD6ujF8Fm7Lm2aRojnkpnn2Q5dRWkYZJiald/MGBPApzimSKBNQBXtVK6VZYIQZ4JekLOwNfqxsjyPwH5fZJ6tNrvifNtmVC3qDgO94blB8DBLVXlUzZ0Gqmq00jVwwDYrKz/mpXzkKtdpEd8weLdeC/4s38sw/Y0vf3Uw+sa1efav8hXmcjVUFdu8NO5bC700jiq3s5eEUkadigcS+OHj7sPPD7f7H6GqBurgu/XBFfwwM+TH774dzLWYObpvXMeoVPOYVkjLjLMyOcWTMfMn5HvP1/ZoQCNfuSP/DuAvfzsLyfEYz7+HNbXs2Ci3dDR23qBSnrtXlR9tSQUzRmrW1qQTd98iCxmXzWrxf3x8K0DDEwAA",
@@ -34,6 +37,8 @@ const exactDocs = [
34
37
  "docs/project/repository-map.md",
35
38
  "docs/project/runtime.md",
36
39
  "docs/reviews/_TEMPLATE-REVIEW.md",
40
+ "docs/skill-feedback/README.md",
41
+ "docs/skill-feedback/_TEMPLATE-SKILL-FEEDBACK.md",
37
42
  "docs/testing/regression-matrix.md",
38
43
  "docs/tools/autopipeline/ap.py",
39
44
  ];
@@ -85,6 +90,30 @@ function writeFile(file, text) {
85
90
  fs.writeFileSync(file, text);
86
91
  }
87
92
 
93
+ function installTrustedEngineeringDefault(repo, content, version) {
94
+ const installedRelative = path.join(
95
+ ".agents",
96
+ "skills",
97
+ "auto-coding-skill",
98
+ "data",
99
+ "templates",
100
+ "ENGINEERING.md",
101
+ );
102
+ writeFile(path.join(repo, installedRelative), content);
103
+ const manifestPath = path.join(repo, ".agents", "managed-install.json");
104
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
105
+ manifest.skill_version = version;
106
+ const entry = manifest.entries.find(item => item.path === installedRelative);
107
+ assert(entry, "installed manifest must contain the managed ENGINEERING source template");
108
+ Object.assign(entry, {
109
+ source: "skill/data/templates/ENGINEERING.md",
110
+ ownership: "exact",
111
+ sha256: crypto.createHash("sha256").update(content).digest("hex"),
112
+ version,
113
+ });
114
+ writeFile(manifestPath, `${JSON.stringify(manifest)}\n`);
115
+ }
116
+
88
117
  function readEngineeringConfig(file) {
89
118
  const script = [
90
119
  "import json, pathlib, sys, yaml",
@@ -96,6 +125,42 @@ function readEngineeringConfig(file) {
96
125
  return JSON.parse(run("python3", ["-c", script, file]).stdout);
97
126
  }
98
127
 
128
+ function readYamlConfig(file) {
129
+ const script = [
130
+ "import json, pathlib, sys, yaml",
131
+ "value = yaml.safe_load(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8'))",
132
+ "print(json.dumps(value, sort_keys=True))",
133
+ ].join("; ");
134
+ return JSON.parse(run("python3", ["-c", script, file]).stdout);
135
+ }
136
+
137
+ function projectConfigPath(repo) {
138
+ return path.join(repo, projectConfigRelativePath);
139
+ }
140
+
141
+ function writeProjectConfig(repo, overrides) {
142
+ writeFile(projectConfigPath(repo), `${JSON.stringify({ schema: projectConfigSchema, overrides }, null, 2)}\n`);
143
+ }
144
+
145
+ function renderYaml(value) {
146
+ const script = [
147
+ "import json, sys, yaml",
148
+ "print(yaml.safe_dump(json.loads(sys.argv[1]), allow_unicode=True, sort_keys=False), end='')",
149
+ ].join("; ");
150
+ return run("python3", ["-c", script, JSON.stringify(value)]).stdout;
151
+ }
152
+
153
+ function readEffectiveConfig(repo) {
154
+ const script = [
155
+ "import json, pathlib, sys",
156
+ "repo = pathlib.Path(sys.argv[1]).resolve()",
157
+ "sys.path.insert(0, str(repo / '.agents' / 'skills' / 'auto-coding-skill' / 'scripts'))",
158
+ "import core",
159
+ "print(json.dumps(core.load_effective_config(repo), sort_keys=True))",
160
+ ].join("; ");
161
+ return JSON.parse(run("python3", ["-c", script, repo]).stdout);
162
+ }
163
+
99
164
  function canonicalJson(value) {
100
165
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
101
166
  if (value && typeof value === "object") {
@@ -139,7 +204,7 @@ function listProjectFiles(root) {
139
204
  return out;
140
205
  }
141
206
 
142
- function fillRequiredAccess(repo, password = "local-dev-password") {
207
+ function fillLegacyEngineeringAccess(repo, password = "local-dev-password") {
143
208
  const engineering = path.join(repo, "docs", "ENGINEERING.md");
144
209
  const text = fs.readFileSync(engineering, "utf8");
145
210
  const block = [
@@ -189,6 +254,54 @@ function fillRequiredAccess(repo, password = "local-dev-password") {
189
254
  fs.writeFileSync(engineering, updated);
190
255
  }
191
256
 
257
+ function fillRequiredAccess(repo, password = "local-dev-password") {
258
+ const overlay = projectConfigPath(repo);
259
+ const existing = exists(overlay) ? (readYamlConfig(overlay).overrides ?? {}) : {};
260
+ const required = requiredProjectOverrides(existing.project?.name ?? path.basename(repo), password);
261
+ writeProjectConfig(repo, {
262
+ ...existing,
263
+ project: { ...required.project, ...(existing.project ?? {}) },
264
+ access: required.access,
265
+ commands: { ...(existing.commands ?? {}), ...required.commands },
266
+ validation: { ...(existing.validation ?? {}), ...required.validation },
267
+ });
268
+ }
269
+
270
+ function requiredProjectOverrides(projectName, password = "overlay-local-dev-password") {
271
+ return {
272
+ project: {
273
+ name: projectName,
274
+ },
275
+ access: {
276
+ project: {
277
+ frontend: { url: "http://project-frontend.local", username: "project-frontend-user", password },
278
+ backend: { url: "http://project-backend.local", username: "project-backend-user", password },
279
+ },
280
+ jenkins: {
281
+ frontend: { url: "http://jenkins-frontend.local", username: "jenkins-frontend-user", password },
282
+ backend: { url: "http://jenkins-backend.local", username: "jenkins-backend-user", password },
283
+ },
284
+ gitlab: { url: "http://gitlab.local", username: "gitlab-user", password },
285
+ nexus: {
286
+ frontend: { url: "http://nexus-frontend.local", username: "nexus-frontend-user", password },
287
+ },
288
+ },
289
+ commands: {
290
+ project_fast: "true",
291
+ },
292
+ validation: {
293
+ routes: [
294
+ {
295
+ name: "project-code",
296
+ paths: ["**"],
297
+ exclude: ["*.md", "docs/**"],
298
+ commands: ["project_fast"],
299
+ },
300
+ ],
301
+ },
302
+ };
303
+ }
304
+
192
305
  function assertStatusOk(repo) {
193
306
  fillRequiredAccess(repo);
194
307
  const result = run("node", [cli, "status", "--projects", repo, "--json"]);
@@ -199,7 +312,6 @@ function assertStatusOk(repo) {
199
312
  function testInitFullyConvergesExistingProject() {
200
313
  const repo = tmpdir("full-init");
201
314
  run("node", [cli, "init"], { cwd: repo });
202
- fillRequiredAccess(repo, "preserved-project-secret");
203
315
  const engineering = path.join(repo, "docs", "ENGINEERING.md");
204
316
  const structureStandard = path.join(repo, "docs", "architecture", "structure-standard.md");
205
317
  assert(
@@ -242,50 +354,22 @@ function testInitFullyConvergesExistingProject() {
242
354
  ],
243
355
  },
244
356
  };
245
- const customRiskYaml = [
246
- "risk:",
247
- " rules:",
248
- " - name: frontend-manifest-and-extension-policy",
249
- " paths:",
250
- " - package.json",
251
- " - frontend/package.json",
252
- " - frontend/extensions/**",
253
- " profile: high-risk",
254
- " review: required",
255
- " design: required",
256
- ].join("\n");
257
- const customStructureYaml = [
258
- "structure:",
259
- " enabled: false",
260
- " enforcement: blocking",
261
- " architecture_standard: xjmate-clean-architecture",
262
- " exclude: [docs/**]",
263
- " allow_large_files: [generated/**]",
264
- " reusable_tool_dirs: [tools/**]",
265
- " max_file_lines_warn: 701",
266
- " max_file_lines_block: 1401",
267
- " max_function_lines_warn: 101",
268
- " max_added_lines_to_large_file: 41",
269
- " require_reuse_search: false",
270
- " block_new_responsibility_in_large_file: false",
271
- " accepted_debt_paths: [legacy/accepted/**]",
272
- " layer_rules:",
273
- " enabled: false",
274
- " block: true",
275
- " rules:",
276
- " - name: project-domain",
277
- " paths: [src/domain/**]",
278
- " forbidden_imports: [src/infrastructure/**]",
279
- ].join("\n");
357
+ writeProjectConfig(repo, {
358
+ ...requiredProjectOverrides(path.basename(repo), "preserved-project-secret"),
359
+ risk: { rules: expectedRiskRules },
360
+ structure: expectedStructure,
361
+ });
362
+ const overlayBefore = fs.readFileSync(projectConfigPath(repo));
280
363
  writeFile(engineering, fs.readFileSync(engineering, "utf8")
281
- .replace("concurrency:\n", "legacy_extra:\n forbidden: true\n\nconcurrency:\n")
282
- .replace(/^risk:\r?\n[\s\S]*?(?=^structure:)/m, `${customRiskYaml}\n`)
283
- .replace(/^structure:\r?\n[\s\S]*?(?=^optimization:)/m, `${customStructureYaml}\n`)
284
364
  .replace("# Project Facts", "# Obsolete workflow rules\n\nRun a full build every time.\n\n# Project Facts"));
285
365
  writeFile(path.join(repo, "docs", "legacy", "old-taskbook.md"), "historical\n");
286
366
  writeFile(path.join(repo, "docs", "architecture", "system-context.md"), "# System context\n\nKeep me.\n");
287
367
  writeFile(path.join(repo, "docs", "architecture", "adr", "0042-project-choice.md"), "# ADR-0042\n\nKeep me.\n");
288
368
  writeFile(path.join(repo, "docs", "interfaces", "event-contracts.md"), "# Events\n\nKeep me.\n");
369
+ writeFile(path.join(repo, "docs", "project", "operations.md"), "# Project operations\n\nKeep me.\n");
370
+ const skillFeedback = path.join(repo, "docs", "skill-feedback", "reports", "2026-07-18-review-timeout-a13f82c1.md");
371
+ const skillFeedbackContent = "project-owned feedback bytes\n";
372
+ writeFile(skillFeedback, skillFeedbackContent);
289
373
  writeFile(structureStandard, customStructureStandard);
290
374
  writeFile(path.join(repo, ".agents", "agents", "custom.toml"), 'name = "custom"\n');
291
375
  writeFile(path.join(repo, ".agents", "skills", "auto-coding-skill", "obsolete.txt"), "obsolete\n");
@@ -299,12 +383,16 @@ function testInitFullyConvergesExistingProject() {
299
383
  "docs/architecture/adr/0042-project-choice.md",
300
384
  "docs/architecture/system-context.md",
301
385
  "docs/interfaces/event-contracts.md",
386
+ "docs/project/auto-coding-skill.yaml",
387
+ "docs/project/operations.md",
388
+ "docs/skill-feedback/reports/2026-07-18-review-timeout-a13f82c1.md",
302
389
  ].sort();
303
390
  assert(JSON.stringify(installedDocs) === JSON.stringify(expectedInstalledDocs), `docs framework must converge while preserving valid artifacts: ${installedDocs.join(", ")}`);
304
391
  const converged = fs.readFileSync(engineering, "utf8");
305
- const convergedConfig = readEngineeringConfig(engineering);
306
- assert(converged.includes("preserved-project-secret"), "supported access values must survive init");
307
- assert(!converged.includes("legacy_extra") && !converged.includes("Run a full build every time"), "unknown fields and legacy workflow text must be removed");
392
+ const convergedConfig = readEffectiveConfig(repo);
393
+ assert(convergedConfig.access?.project?.frontend?.password === "preserved-project-secret", "project access values must survive init in the overlay");
394
+ assert(!converged.includes("preserved-project-secret"), "managed ENGINEERING must not retain project access values");
395
+ assert(!converged.includes("Run a full build every time"), "legacy workflow text must be removed");
308
396
  assert(canonicalJson(convergedConfig.risk?.rules) === canonicalJson(expectedRiskRules), "project risk.rules must survive init path-for-path");
309
397
  for (const [key, expected] of Object.entries(expectedStructure)) {
310
398
  assert(
@@ -314,15 +402,20 @@ function testInitFullyConvergesExistingProject() {
314
402
  }
315
403
  assert(exists(path.join(repo, ".agents", "agents", "custom.toml")), "project-owned custom agents must survive init");
316
404
  assert(!exists(path.join(repo, ".agents", "skills", "auto-coding-skill", "obsolete.txt")), "extra Skill files must be removed");
317
- assert(exists(path.join(repo, ".agents", "archive", "auto-coding-skill", "4.2.8", "docs", "legacy", "old-taskbook.md")), "removed docs must be archived outside active docs");
405
+ assert(exists(path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs", "legacy", "old-taskbook.md")), "removed docs must be archived outside active docs");
318
406
  assert(fs.readFileSync(structureStandard, "utf8") === customStructureStandard, "init must preserve a project-owned structure standard");
319
407
  assert(fs.readFileSync(path.join(repo, "docs", "architecture", "adr", "0042-project-choice.md"), "utf8").includes("Keep me"), "numbered ADR artifacts must survive init");
320
408
  assert(fs.readFileSync(path.join(repo, "docs", "architecture", "system-context.md"), "utf8").includes("Keep me"), "architecture artifacts must survive init");
321
409
  assert(fs.readFileSync(path.join(repo, "docs", "interfaces", "event-contracts.md"), "utf8").includes("Keep me"), "interface artifacts must survive init");
410
+ assert(fs.readFileSync(path.join(repo, "docs", "project", "operations.md"), "utf8").includes("Keep me"), "project fact documents promised by the manifest must survive init");
411
+ assert(fs.readFileSync(skillFeedback, "utf8") === skillFeedbackContent, "project Skill feedback must survive init byte-for-byte");
412
+ assert(fs.readFileSync(projectConfigPath(repo)).equals(overlayBefore), "init must preserve the project configuration overlay byte-for-byte");
322
413
 
323
414
  run("node", [cli, "init"], { cwd: repo });
324
415
  assert(fs.readFileSync(engineering, "utf8") === converged, "repeated init must be byte-idempotent for ENGINEERING.md");
416
+ assert(fs.readFileSync(projectConfigPath(repo)).equals(overlayBefore), "repeated init must preserve the project configuration overlay byte-for-byte");
325
417
  assert(fs.readFileSync(structureStandard, "utf8") === customStructureStandard, "repeated init must preserve the project structure standard byte-for-byte");
418
+ assert(fs.readFileSync(skillFeedback, "utf8") === skillFeedbackContent, "repeated init must preserve project Skill feedback byte-for-byte");
326
419
  const secondDocs = listProjectFiles(path.join(repo, "docs"))
327
420
  .map(file => path.relative(repo, file).split(path.sep).join("/"))
328
421
  .sort();
@@ -340,32 +433,34 @@ function testStructureBlockWarningsDefaultsPreserveAndConverge() {
340
433
  "new projects must default structure.block_warnings to false",
341
434
  );
342
435
 
343
- const customized = initialized.replace(
344
- /^ block_warnings: false$/m,
345
- " block_warnings: true",
346
- );
347
- assert(customized !== initialized, "block_warnings must be present in canonical frontmatter");
348
- writeFile(engineering, customized);
436
+ const initialOverrides = readYamlConfig(projectConfigPath(repo)).overrides;
437
+ writeProjectConfig(repo, {
438
+ ...initialOverrides,
439
+ structure: { ...(initialOverrides.structure ?? {}), block_warnings: true },
440
+ });
441
+ const customized = fs.readFileSync(projectConfigPath(repo));
349
442
 
350
443
  run("node", [cli, "init"], { cwd: repo });
351
444
  const converged = fs.readFileSync(engineering, "utf8");
352
445
  assert(
353
- readEngineeringConfig(engineering).structure?.block_warnings === true,
354
- "init must preserve an explicit true structure.block_warnings value",
446
+ readEffectiveConfig(repo).structure?.block_warnings === true,
447
+ "init must apply an explicit true project structure.block_warnings override",
355
448
  );
449
+ assert(fs.readFileSync(projectConfigPath(repo)).equals(customized), "init must preserve the block_warnings overlay byte-for-byte");
356
450
  run("node", [cli, "init"], { cwd: repo });
357
451
  assert(
358
452
  fs.readFileSync(engineering, "utf8") === converged,
359
- "repeated init must be byte-idempotent with block_warnings=true",
453
+ "repeated init must be byte-idempotent for managed defaults",
360
454
  );
361
455
 
362
456
  run("node", [cli, "sync", "--projects", repo]);
363
457
  const synced = fs.readFileSync(engineering, "utf8");
364
458
  assert(
365
- readEngineeringConfig(engineering).structure?.block_warnings === true,
366
- "sync must preserve an explicit true structure.block_warnings value",
459
+ readEffectiveConfig(repo).structure?.block_warnings === true,
460
+ "sync must preserve an explicit true project structure.block_warnings override",
367
461
  );
368
462
  assert(synced === converged, "sync must not rewrite a converged block_warnings=true config");
463
+ assert(fs.readFileSync(projectConfigPath(repo)).equals(customized), "sync must preserve the block_warnings overlay byte-for-byte");
369
464
  run("node", [cli, "sync", "--projects", repo]);
370
465
  assert(
371
466
  fs.readFileSync(engineering, "utf8") === synced,
@@ -376,13 +471,19 @@ function testStructureBlockWarningsDefaultsPreserveAndConverge() {
376
471
  function testManagedPolicySummaryPreservesProjectConfiguration() {
377
472
  const repo = tmpdir("managed-policy-summary");
378
473
  run("node", [cli, "init"], { cwd: repo });
474
+ fs.unlinkSync(projectConfigPath(repo));
379
475
  const engineering = path.join(repo, "docs", "ENGINEERING.md");
380
476
  const current = fs.readFileSync(engineering, "utf8");
381
- const neutralSummary = "- `structure` and `optimization`: project-selected enforcement and completion policy; frontmatter values are authoritative.";
477
+ const neutralSummary = "- `structure` and `optimization`: managed defaults that the project overlay may\n replace explicitly.";
382
478
  const legacySummary = "- `structure` and `optimization`: advisory architecture and no-new-debt policy.";
479
+ const installedOldDefault = current
480
+ .replace(/^ skill_version:.*$/m, " skill_version: 4.2.5")
481
+ .replace("managed-workflow:start version=4.3.0", "managed-workflow:start version=4.2.5")
482
+ .replace(neutralSummary, legacySummary);
483
+ installTrustedEngineeringDefault(repo, installedOldDefault, "4.2.5");
383
484
  const customized = current
384
485
  .replace(/^ skill_version:.*$/m, " skill_version: 4.2.5")
385
- .replace("managed-workflow:start version=4.2.8", "managed-workflow:start version=4.2.5")
486
+ .replace("managed-workflow:start version=4.3.0", "managed-workflow:start version=4.2.5")
386
487
  .replace(neutralSummary, legacySummary)
387
488
  .replace(/^ enforcement:.*$/m, " enforcement: blocking")
388
489
  .replace(" block_warnings: false", " block_warnings: true")
@@ -399,15 +500,18 @@ function testManagedPolicySummaryPreservesProjectConfiguration() {
399
500
 
400
501
  run("node", [cli, "init"], { cwd: repo });
401
502
  const upgraded = fs.readFileSync(engineering, "utf8");
402
- const afterUpgrade = readEngineeringConfig(engineering);
403
- assert(afterUpgrade.workflow?.skill_version === "4.2.8", "init must upgrade the workflow version");
503
+ const managedAfterUpgrade = readEngineeringConfig(engineering);
504
+ const afterUpgrade = readEffectiveConfig(repo);
505
+ assert(managedAfterUpgrade.workflow?.skill_version === "4.3.0", "init must upgrade the managed workflow version");
404
506
  assert(canonicalJson(afterUpgrade.structure) === canonicalJson(beforeUpgrade.structure), "init must preserve the complete project structure policy");
405
507
  assert(canonicalJson(afterUpgrade.optimization) === canonicalJson(beforeUpgrade.optimization), "init must preserve the complete project optimization policy");
406
508
  assert(upgraded.includes(neutralSummary), "upgraded managed text must defer to frontmatter policy");
407
509
  assert(!upgraded.includes(legacySummary), "upgraded managed text must remove the hard-coded default policy description");
408
510
 
511
+ const migratedOverlay = fs.readFileSync(projectConfigPath(repo));
409
512
  run("node", [cli, "init"], { cwd: repo });
410
513
  assert(fs.readFileSync(engineering, "utf8") === upgraded, "repeated init must be byte-idempotent after the policy-summary upgrade");
514
+ assert(fs.readFileSync(projectConfigPath(repo)).equals(migratedOverlay), "repeated init must preserve the migrated project policy overlay byte-for-byte");
411
515
  }
412
516
 
413
517
  function testInitRejectsMissingPythonRuntimeBeforeWrites() {
@@ -475,18 +579,22 @@ function testMinimalInitConvergesWithinBudget() {
475
579
  const lines = files.reduce((total, file) => total + fs.readFileSync(file, "utf8").split(/\r?\n/).length, 0);
476
580
  assert(files.length <= 40, `minimal scaffold file budget exceeded: ${files.length}`);
477
581
  // Integrity, staging, fail-closed classification, immutable Reviewer snapshots,
478
- // bounded runtime supervision, failure-evidence binding, contract helpers, and
479
- // the language-aware structure scanner are executable support code, not prompt
480
- // context. Keep a measured ceiling while leaving safety checks readable.
481
- assert(lines <= 17200, `minimal scaffold line budget exceeded: ${lines}`);
582
+ // bounded runtime supervision, failure-evidence binding, contract helpers,
583
+ // effective-config overlay parsing/migration, metadata-only feedback
584
+ // collection, and the language-aware structure scanner are executable
585
+ // support code, not prompt context. Keep a measured ceiling while leaving
586
+ // safety checks readable.
587
+ assert(lines <= 20000, `minimal scaffold line budget exceeded: ${lines}`);
482
588
  const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
483
- assert(engineering.includes("profile: auto"), "engineering should enable adaptive profiles");
484
- assert(engineering.includes("isolation: adaptive"), "engineering should default to adaptive clean-branch/worktree isolation");
485
- assert(engineering.includes("completion: push"), "engineering should complete normal development at push");
486
- assert(engineering.includes("project_fast: ''"), "generic projects should expose an optional project-fast command");
487
- assert(engineering.includes("max_command_seconds: 120"), "engineering should bound each final route command");
488
- assert(engineering.includes("max_total_seconds: 180"), "engineering should bound the complete final gate");
489
- assert(engineering.includes(`name: ${path.basename(repo)}`), "project name should be initialized automatically");
589
+ const managedConfig = readEngineeringConfig(path.join(repo, "docs", "ENGINEERING.md"));
590
+ assert(managedConfig.workflow?.profile === "auto", "engineering should enable adaptive profiles");
591
+ assert(managedConfig.concurrency?.isolation === "adaptive", "engineering should default to adaptive clean-branch/worktree isolation");
592
+ assert(managedConfig.workflow?.completion === "push", "engineering should complete normal development at push");
593
+ assert(managedConfig.commands?.project_fast === "", "generic projects should expose an optional project-fast command");
594
+ assert(managedConfig.validation?.max_command_seconds === 120, "engineering should bound each final route command");
595
+ assert(managedConfig.validation?.max_total_seconds === 180, "engineering should bound the complete final gate");
596
+ assert(readYamlConfig(projectConfigPath(repo)).overrides?.project?.name === path.basename(repo), "project name should be initialized in the project-owned overlay");
597
+ assert(managedConfig.project?.name === "", "managed ENGINEERING must keep the neutral project-name default");
490
598
  assert(!engineering.includes("## Design, review, and subagents"), "engineering must not duplicate the behavioral protocol");
491
599
  const agentsProtocol = fs.readFileSync(path.join(repo, "AGENTS.md"), "utf8");
492
600
  assert(agentsProtocol.includes("## Minimum mechanism budget"), "AGENTS should own the shared behavioral protocol");
@@ -530,17 +638,72 @@ function testMinimalInitConvergesWithinBudget() {
530
638
  }
531
639
  }
532
640
 
641
+ function testSkillFeedbackTemplatesAndReportsSurviveSync() {
642
+ const repo = tmpdir("skill-feedback-sync");
643
+ run("node", [cli, "init"], { cwd: repo });
644
+ fillRequiredAccess(repo);
645
+ const feedbackReadme = path.join(repo, "docs", "skill-feedback", "README.md");
646
+ const feedbackTemplate = path.join(repo, "docs", "skill-feedback", "_TEMPLATE-SKILL-FEEDBACK.md");
647
+ const report = path.join(repo, "docs", "skill-feedback", "reports", "2026-07-18-installer-gap-a13f82c1.md");
648
+ const reportBytes = Buffer.from("project-owned\u0000feedback\n", "utf8");
649
+ fs.mkdirSync(path.dirname(report), { recursive: true });
650
+ fs.writeFileSync(report, reportBytes);
651
+ assert(exists(feedbackReadme) && exists(feedbackTemplate), "init must install managed Skill feedback guidance and template");
652
+
653
+ writeFile(feedbackReadme, "managed template drift\n");
654
+ const dry = run("node", [cli, "sync", "--projects", repo, "--dry-run", "--json"]);
655
+ const dryResult = JSON.parse(dry.stdout).results[0];
656
+ assert(
657
+ dryResult.actions.some(item => item.path === "docs/skill-feedback/README.md" && item.action === "would-replace"),
658
+ "sync dry-run must report managed feedback template drift",
659
+ );
660
+ assert(fs.readFileSync(feedbackReadme, "utf8") === "managed template drift\n", "sync dry-run must not write feedback templates");
661
+ assert(fs.readFileSync(report).equals(reportBytes), "sync dry-run must not touch project feedback reports");
662
+
663
+ run("node", [cli, "sync", "--projects", repo, "--json"]);
664
+ assert(fs.readFileSync(feedbackReadme, "utf8").includes("Auto Coding Skill Feedback"), "sync must restore the managed feedback README");
665
+ assert(fs.readFileSync(report).equals(reportBytes), "sync must preserve project feedback reports byte-for-byte");
666
+ assertStatusOk(repo);
667
+
668
+ if (process.platform !== "win32") {
669
+ const external = path.join(tmpdir("feedback-managed-symlink"), "external.md");
670
+ const installedSkill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
671
+ const skillBefore = fs.readFileSync(installedSkill);
672
+ writeFile(external, "external must not change\n");
673
+ fs.unlinkSync(feedbackReadme);
674
+ fs.symlinkSync(external, feedbackReadme);
675
+ const unsafeInit = run("node", [cli, "init"], { cwd: repo, check: false });
676
+ assert(unsafeInit.status !== 0 && unsafeInit.stderr.includes("non-symlink"), "init must reject a managed feedback template symlink before writes");
677
+ assert(fs.readFileSync(external, "utf8") === "external must not change\n", "init must never follow a managed feedback template symlink");
678
+ assert(fs.readFileSync(installedSkill).equals(skillBefore), "managed feedback symlink preflight must happen before install writes");
679
+ fs.unlinkSync(feedbackReadme);
680
+ run("node", [cli, "init"], { cwd: repo });
681
+ assert(fs.readFileSync(report).equals(reportBytes), "feedback report must survive repair of a managed template symlink");
682
+
683
+ const parentLinkRepo = tmpdir("feedback-managed-parent-symlink");
684
+ const externalDir = tmpdir("feedback-managed-parent-external");
685
+ run("node", [cli, "init"], { cwd: parentLinkRepo });
686
+ const parentInstalledSkill = path.join(parentLinkRepo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
687
+ const parentSkillBefore = fs.readFileSync(parentInstalledSkill);
688
+ fs.rmSync(path.join(parentLinkRepo, "docs", "skill-feedback"), { recursive: true, force: true });
689
+ fs.symlinkSync(externalDir, path.join(parentLinkRepo, "docs", "skill-feedback"));
690
+ const unsafeParentInit = run("node", [cli, "init"], { cwd: parentLinkRepo, check: false });
691
+ assert(unsafeParentInit.status !== 0 && unsafeParentInit.stderr.includes("real directory"), "init must reject a symlink in the managed feedback parent chain");
692
+ assert(fs.readdirSync(externalDir).length === 0, "init must not write through a managed feedback parent symlink");
693
+ assert(fs.readFileSync(parentInstalledSkill).equals(parentSkillBefore), "parent symlink preflight must happen before install writes");
694
+ }
695
+ }
696
+
533
697
  function testStatusRejectsLegacyIsolation() {
534
698
  const repo = tmpdir("legacy-isolation-status");
535
699
  run("node", [cli, "init"], { cwd: repo });
536
700
  run("node", [cli, "sync", "--projects", repo]);
537
701
  fillRequiredAccess(repo);
538
- const engineeringPath = path.join(repo, "docs", "ENGINEERING.md");
539
- const engineering = fs.readFileSync(engineeringPath, "utf8").replace(
540
- "isolation: adaptive",
541
- "isolation: legacy",
542
- );
543
- fs.writeFileSync(engineeringPath, engineering);
702
+ const overrides = readYamlConfig(projectConfigPath(repo)).overrides;
703
+ writeProjectConfig(repo, {
704
+ ...overrides,
705
+ concurrency: { ...(overrides.concurrency ?? {}), isolation: "legacy" },
706
+ });
544
707
 
545
708
  const result = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
546
709
  assert(result.status !== 0, "status must reject legacy isolation");
@@ -556,17 +719,20 @@ function testStatusRejectsLegacyGateEscalation() {
556
719
  const repo = tmpdir("legacy-gate-status");
557
720
  run("node", [cli, "init"], { cwd: repo });
558
721
  run("node", [cli, "sync", "--projects", repo]);
559
- const engineeringPath = path.join(repo, "docs", "ENGINEERING.md");
560
- const engineering = fs.readFileSync(engineeringPath, "utf8").replace(
561
- "validation:\n",
562
- 'gate:\n full_on_unknown: "true"\n full_on: ["prod_config"]\n rules:\n - match: ["Jenkinsfile"]\n scope: "full"\n commands: ["gate_full"]\n\nvalidation:\n',
563
- );
564
- fs.writeFileSync(engineeringPath, engineering);
722
+ const overrides = readYamlConfig(projectConfigPath(repo)).overrides;
723
+ writeProjectConfig(repo, {
724
+ ...overrides,
725
+ gate: {
726
+ full_on_unknown: "true",
727
+ full_on: ["prod_config"],
728
+ rules: [{ match: ["Jenkinsfile"], scope: "full", commands: ["gate_full"] }],
729
+ },
730
+ });
565
731
  const status = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
566
732
  assert(status.status === 2, "legacy automatic gate escalation must make status non-zero");
567
733
  const invalid = JSON.parse(status.stdout).results[0].invalidConfigTokens;
568
- for (const expected of ["gate.full_on", "gate.full_on_unknown", "gate.rules[].scope", "gate.rules[].commands"]) {
569
- assert(invalid.some(item => item.includes(expected)), `status should report ${expected}`);
734
+ for (const expected of ["gate.full_on", "gate.full_on_unknown", "gate.rules[0].scope", "gate.rules[0].commands"]) {
735
+ assert(invalid.some(item => item.includes(expected)), `status should report ${expected}: ${status.stdout}`);
570
736
  }
571
737
  }
572
738
 
@@ -574,12 +740,11 @@ function testStatusAcceptsValidIndentlessYamlRoutes() {
574
740
  const repo = tmpdir("indentless-routes");
575
741
  run("node", [cli, "init"], { cwd: repo });
576
742
  fillRequiredAccess(repo);
577
- const engineering = path.join(repo, "docs", "ENGINEERING.md");
578
- const text = fs.readFileSync(engineering, "utf8").replace(
579
- /(^ routes:\n)([\s\S]*?)(?=^risk:)/m,
580
- (_match, heading, body) => heading + body.replace(/^ /gm, " "),
581
- );
582
- writeFile(engineering, text);
743
+ const overlay = projectConfigPath(repo);
744
+ const parsed = readYamlConfig(overlay);
745
+ const text = renderYaml(parsed);
746
+ assert(/^ routes:\r?\n - /m.test(text), "fixture must use a valid indentless YAML route sequence");
747
+ writeFile(overlay, text);
583
748
  const status = run("node", [cli, "status", "--projects", repo, "--json"]);
584
749
  assert(JSON.parse(status.stdout).results[0].ok === true, "valid indentless YAML routes must not be reported as empty");
585
750
  }
@@ -589,10 +754,10 @@ function testOrdinaryNodeTestIsNotPromotedToAutomaticGate() {
589
754
  writeFile(path.join(repo, "package.json"), JSON.stringify({ scripts: { test: "node --test" } }, null, 2) + "\n");
590
755
  run("node", [cli, "init"], { cwd: repo });
591
756
  run("node", [cli, "sync", "--projects", repo]);
592
- const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
593
- assert(engineering.includes("project_fast: ''"), "ordinary test must not be promoted to the project-fast command");
594
- assert(!engineering.includes("gate_standard:"), "ordinary test must not seed an automatic standard gate");
595
- assert(!engineering.includes("gate_full:"), "ordinary test must not seed an automatic full gate");
757
+ const effective = readEffectiveConfig(repo);
758
+ assert(effective.commands?.project_fast === "", "ordinary test must not be promoted to the project-fast command");
759
+ assert(effective.commands?.gate_standard === undefined, "ordinary test must not seed an automatic standard gate");
760
+ assert(effective.commands?.gate_full === undefined, "ordinary test must not seed an automatic full gate");
596
761
 
597
762
  fillRequiredAccess(repo);
598
763
  run("git", ["init", "-q"], { cwd: repo });
@@ -621,31 +786,1004 @@ function testAccessPasswordsAreRequiredButNeverPrintedByStatus() {
621
786
  const healthy = run("node", [cli, "status", "--projects", repo, "--json"]);
622
787
  assert(!healthy.stdout.includes(secret), "status JSON must not echo configured passwords");
623
788
 
624
- const engineering = path.join(repo, "docs", "ENGINEERING.md");
625
- writeFile(engineering, fs.readFileSync(engineering, "utf8").replace(
626
- ` password: ${JSON.stringify(secret)}`,
627
- ' password: "" # direct value required\n password_env: "PROJECT_FRONTEND_PASSWORD"',
628
- ));
789
+ const overlay = projectConfigPath(repo);
790
+ const missingPassword = readYamlConfig(overlay).overrides;
791
+ missingPassword.access.project.frontend.password = "";
792
+ missingPassword.access.project.frontend.password_env = "PROJECT_FRONTEND_PASSWORD";
793
+ writeProjectConfig(repo, missingPassword);
629
794
  const missing = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
630
795
  assert(missing.status !== 0, "an environment reference must not replace the required direct password");
631
796
  assert(JSON.parse(missing.stdout).results[0].missingConfigTokens.includes("access.project.frontend.password"), "status should name the missing direct password field");
632
797
  assert(!missing.stdout.includes(secret), "failed status JSON must not echo other configured passwords");
633
798
  assert(!JSON.parse(missing.stdout).results[0].next.includes("upgrade"), "present but blank fields should not trigger a no-op upgrade recommendation");
634
799
 
800
+ fillRequiredAccess(repo);
801
+ const validOverlaySource = fs.readFileSync(overlay, "utf8");
635
802
  for (const yamlValue of ["false", "[]", "{}", "2026-07-13", "0x10", "|"]) {
636
- fillRequiredAccess(repo);
637
- writeFile(engineering, fs.readFileSync(engineering, "utf8").replace(' password: "local-dev-password"', ` password: ${yamlValue}`));
803
+ const invalid = validOverlaySource.replace('"password": "local-dev-password"', `"password": ${yamlValue}`);
804
+ assert(invalid !== validOverlaySource, `${yamlValue}: fixture must replace one overlay password`);
805
+ writeFile(overlay, invalid);
638
806
  const nonString = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
639
- assert(JSON.parse(nonString.stdout).results[0].missingConfigTokens.includes("access.project.frontend.password"), `YAML non-string ${yamlValue} must not count as a credential string`);
807
+ assert(JSON.parse(nonString.stdout).results[0].missingConfigTokens.includes("access.project.frontend.password"), `YAML non-string ${yamlValue} must not count as a credential string: ${nonString.stdout}`);
640
808
  }
641
- fillRequiredAccess(repo);
642
- writeFile(engineering, fs.readFileSync(engineering, "utf8").replace(' password: "local-dev-password"', ' password: "TO\\u0044O"'));
809
+ writeFile(overlay, validOverlaySource.replace('"password": "local-dev-password"', '"password": "TO\\u0044O"'));
643
810
  const escapedPlaceholder = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
644
811
  assert(JSON.parse(escapedPlaceholder.stdout).results[0].missingConfigTokens.includes("access.project.frontend.password"), "escaped YAML placeholders must be decoded before validation");
645
812
 
646
- writeFile(engineering, fs.readFileSync(engineering, "utf8").replace(/^access:\r?\n[\s\S]*?(?=^concurrency:)/m, ""));
813
+ const absentOverrides = readYamlConfig(overlay).overrides;
814
+ delete absentOverrides.access;
815
+ writeProjectConfig(repo, absentOverrides);
647
816
  const absent = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
648
- assert(JSON.parse(absent.stdout).results[0].next.includes("autocoding init"), "missing access paths should recommend authoritative init");
817
+ const absentStatus = JSON.parse(absent.stdout).results[0];
818
+ assert(absentStatus.unfilledConfigTokens.includes("access.project.frontend.password"), `status must retain its redacted required-field summary: ${absent.stdout}`);
819
+ assert(absentStatus.invalidConfigTokens.some(item => item.includes("access.project.frontend.password") && item.includes("explicitly filled string")), `status must consume the complete doctor contract: ${absent.stdout}`);
820
+ assert(absentStatus.next.includes("doctor"), `invalid effective configuration must direct the user through doctor: ${absent.stdout}`);
821
+ }
822
+
823
+ function testProjectConfigOverlayMigratesLegacyEngineeringAndStaysByteStable() {
824
+ const repo = tmpdir("project-config-migration");
825
+ const secret = "legacy-overlay-secret-6e2f";
826
+ run("git", ["init", "-q"], { cwd: repo });
827
+ run("node", [cli, "init"], { cwd: repo });
828
+ const overlay = projectConfigPath(repo);
829
+ assert(exists(overlay), "new project init must create the project-owned config overlay");
830
+ const initializedOverlay = readYamlConfig(overlay);
831
+ assert(initializedOverlay.schema === projectConfigSchema, "new project overlay must use the versioned schema");
832
+ assert(initializedOverlay.overrides?.project?.name === path.basename(repo), "new project overlay must own the inferred project name");
833
+
834
+ // Simulate the last pre-overlay release: project values lived directly in the
835
+ // otherwise managed ENGINEERING frontmatter and no overlay existed yet.
836
+ fs.unlinkSync(overlay);
837
+ fillLegacyEngineeringAccess(repo, secret);
838
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
839
+ const current = fs.readFileSync(engineering, "utf8");
840
+ const legacy = current
841
+ .replace(/^ name:.*$/m, ' name: "legacy-specialized-project"')
842
+ .replace(/^ stack:.*$/m, ' stack: "node-go-specialized"')
843
+ .replace(/^ target_branch:.*$/m, ' target_branch: "dev"')
844
+ .replace(/^ cleanup_merged: true$/m, " cleanup_merged: 1")
845
+ .replace(/^ max_command_seconds: 120$/m, " max_command_seconds: 120.0")
846
+ .replace(/^risk:\r?\n rules: \[\]$/m, [
847
+ "risk:",
848
+ " rules:",
849
+ " - name: project-device-credentials",
850
+ " paths: [src/device-credentials/**]",
851
+ " profile: high-risk",
852
+ " review: required",
853
+ ].join("\n"))
854
+ .replace(/^structure:\r?\n enabled: true$/m, "structure:\n enabled: false")
855
+ .replace(/^ block_warnings: false$/m, " block_warnings: true")
856
+ .replace(/^ block: false$/m, " block: 0")
857
+ .replace(/^ api_docs_required: false$/m, " api_docs_required: true");
858
+ assert(legacy !== current, "legacy migration fixture must contain project-specific frontmatter changes");
859
+ writeFile(engineering, legacy);
860
+
861
+ run("node", [cli, "init"], { cwd: repo });
862
+ const migrated = readYamlConfig(overlay);
863
+ assert(migrated.schema === projectConfigSchema, "migration must create the current project overlay schema");
864
+ assert(migrated.overrides?.project?.name === "legacy-specialized-project", "migration must extract project.name from legacy ENGINEERING");
865
+ assert(migrated.overrides?.project?.stack === "node-go-specialized", "migration must extract the project stack");
866
+ assert(migrated.overrides?.concurrency?.target_branch === "dev", "migration must extract the target branch");
867
+ assert(migrated.overrides?.concurrency?.cleanup_merged === 1, "migration must distinguish integer 1 from boolean true");
868
+ assert(migrated.overrides?.validation?.max_command_seconds === 120, "migration must retain the numeric timeout value");
869
+ assert(migrated.overrides?.access?.project?.frontend?.password === secret, "migration must extract project access without printing it");
870
+ assert(migrated.overrides?.risk?.rules?.[0]?.name === "project-device-credentials", "migration must extract project risk rules");
871
+ assert(migrated.overrides?.structure?.enabled === false && migrated.overrides?.structure?.block_warnings === true, "migration must extract explicit project structure policy");
872
+ assert(migrated.overrides?.structure?.layer_rules?.block === 0, "migration must distinguish integer 0 from boolean false");
873
+ assert(migrated.overrides?.docs?.api_docs_required === true, "migration must extract project documentation policy");
874
+ assert(migrated.overrides?.workflow?.skill_version === undefined, "migration must never copy the managed Skill version into project overrides");
875
+ const migratedOverlaySource = fs.readFileSync(overlay, "utf8");
876
+ assert(migratedOverlaySource.includes("max_command_seconds: 120.0"), "migration must distinguish float 120.0 from integer 120");
877
+
878
+ const managed = readEngineeringConfig(engineering);
879
+ assert(managed.project?.name === "" && managed.project?.stack === "generic", "ENGINEERING must converge to managed defaults after migration");
880
+ assert(managed.access?.project?.frontend?.password === "", "ENGINEERING must no longer retain project access after migration");
881
+ assert(managed.risk?.rules?.length === 0 && managed.structure?.enabled === true, "ENGINEERING policy defaults must remain release-owned");
882
+ const effective = readEffectiveConfig(repo);
883
+ assert(effective.project?.name === "legacy-specialized-project", "effective config must retain the migrated project identity");
884
+ assert(effective.concurrency?.cleanup_merged === 1, "effective config must preserve integer 1 instead of restoring boolean true");
885
+ assert(effective.structure?.layer_rules?.block === 0, "effective config must preserve integer 0 instead of restoring boolean false");
886
+ assert(effective.access?.project?.frontend?.password === secret, "effective config must retain migrated access values");
887
+ assert(effective.docs?.api_docs_required === true, "effective config must apply migrated project overrides");
888
+ assert(effective.docs?.api_change_log === "docs/interfaces/api-change-log.md", "fields absent from the legacy project config must inherit the new managed default");
889
+
890
+ const stableOverlay = fs.readFileSync(overlay);
891
+ const stableEngineering = fs.readFileSync(engineering);
892
+ run("node", [cli, "init"], { cwd: repo });
893
+ assert(fs.readFileSync(overlay).equals(stableOverlay), "repeated init must preserve the project overlay byte-for-byte");
894
+ assert(fs.readFileSync(engineering).equals(stableEngineering), "repeated init must keep the managed default document stable");
895
+ run("node", [cli, "sync", "--projects", repo]);
896
+ assert(fs.readFileSync(overlay).equals(stableOverlay), "sync must preserve the project overlay byte-for-byte");
897
+ run("node", [cli, "sync", "--projects", repo]);
898
+ assert(fs.readFileSync(overlay).equals(stableOverlay), "repeated sync must preserve the project overlay byte-for-byte");
899
+ run("node", [cli, "sync", "--projects", repo]);
900
+ assert(fs.readFileSync(overlay).equals(stableOverlay), "transactional sync must preserve an existing project overlay byte-for-byte");
901
+ }
902
+
903
+ function testProjectConfigOverlayMergeKeepsExplicitFalseZeroEmptyAndList() {
904
+ const repo = tmpdir("project-config-merge");
905
+ run("node", [cli, "init"], { cwd: repo });
906
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
907
+ const managedDefault = fs.readFileSync(engineering, "utf8");
908
+ const base = managedDefault
909
+ .replace(/^ target_branch: (?:(?:""|'')|null)$/m, ' target_branch: "release-default"')
910
+ .replace(/^risk:\r?\n rules: \[\]$/m, [
911
+ "risk:",
912
+ " rules:",
913
+ " - name: new-managed-default",
914
+ " paths: [managed-default/**]",
915
+ " profile: high-risk",
916
+ " review: required",
917
+ ].join("\n"))
918
+ .replace(/^structure:\r?\n enabled: true$/m, "structure:\n enabled: true\n max_file_lines_warn: 777")
919
+ .replace(/^ api_docs_required: false$/m, " api_docs_required: true");
920
+ writeFile(engineering, base);
921
+ writeProjectConfig(repo, {
922
+ project: { name: "explicit-overlay-values" },
923
+ concurrency: { target_branch: "" },
924
+ risk: { rules: [] },
925
+ structure: { enabled: false, max_file_lines_warn: 0 },
926
+ });
927
+
928
+ const effective = readEffectiveConfig(repo);
929
+ assert(effective.project?.name === "explicit-overlay-values", "project scalar must override the managed default");
930
+ assert(effective.structure?.enabled === false, "explicit false must override a true managed default");
931
+ assert(effective.structure?.max_file_lines_warn === 0, "explicit zero must not fall back to a non-zero managed default");
932
+ assert(effective.concurrency?.target_branch === "", "explicit empty string must override a non-empty managed default");
933
+ assert(Array.isArray(effective.risk?.rules) && effective.risk.rules.length === 0, "explicit empty list must replace the managed list instead of merging it");
934
+ assert(effective.docs?.api_docs_required === true, "an unoverridden field must inherit a new managed default");
935
+
936
+ const overlay = projectConfigPath(repo);
937
+ const stableOverlay = fs.readFileSync(overlay);
938
+ writeFile(engineering, managedDefault);
939
+ run("node", [cli, "init"], { cwd: repo });
940
+ run("node", [cli, "sync", "--projects", repo]);
941
+ assert(fs.readFileSync(overlay).equals(stableOverlay), "managed convergence must never normalize or rewrite an existing valid overlay");
942
+ const convergedEffective = readEffectiveConfig(repo);
943
+ assert(convergedEffective.structure?.enabled === false && convergedEffective.structure?.max_file_lines_warn === 0, "project scalar overrides must survive managed convergence");
944
+ assert(convergedEffective.concurrency?.target_branch === "" && convergedEffective.risk?.rules?.length === 0, "project empty values must survive managed convergence");
945
+ }
946
+
947
+ function testOversizedLegacyMigrationFailsBeforeCreatingAnInvalidOverlay() {
948
+ const repo = tmpdir("project-config-oversized-migration");
949
+ run("git", ["init", "-q"], { cwd: repo });
950
+ run("node", [cli, "init"], { cwd: repo });
951
+ const overlay = projectConfigPath(repo);
952
+ fs.unlinkSync(overlay);
953
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
954
+ const current = fs.readFileSync(engineering, "utf8");
955
+ const oversized = current.replace(
956
+ /^project:\r?\n/m,
957
+ `project:\n oversized_legacy_value: ${JSON.stringify("x".repeat(140 * 1024))}\n`,
958
+ );
959
+ assert(oversized !== current, "oversized legacy migration fixture must modify managed frontmatter");
960
+ writeFile(engineering, oversized);
961
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
962
+ const manifest = path.join(repo, ".agents", "managed-install.json");
963
+ const before = {
964
+ engineering: fs.readFileSync(engineering),
965
+ skill: fs.readFileSync(skill),
966
+ manifest: fs.readFileSync(manifest),
967
+ };
968
+
969
+ const failed = run("node", [cli, "init"], { cwd: repo, check: false });
970
+ const output = `${failed.stdout}\n${failed.stderr}`;
971
+ assert(failed.status !== 0 && output.includes("exceeds its size limit"), `oversized migrated overlay must fail before writes: ${output}`);
972
+ assert(!exists(overlay), "installer must not create an overlay that violates its own size contract");
973
+ assert(fs.readFileSync(engineering).equals(before.engineering), "oversized migration failure must preserve legacy ENGINEERING bytes");
974
+ assert(fs.readFileSync(skill).equals(before.skill), "oversized migration failure must not switch the installed Skill");
975
+ assert(fs.readFileSync(manifest).equals(before.manifest), "oversized migration failure must not replace the install manifest");
976
+ }
977
+
978
+ function testInvalidProjectConfigOverlayFailsBeforeAnyWrites() {
979
+ const invalidCases = [
980
+ {
981
+ name: "null",
982
+ content: `${JSON.stringify({ schema: projectConfigSchema, overrides: { structure: { enabled: null } } }, null, 2)}\n`,
983
+ hints: ["null"],
984
+ },
985
+ {
986
+ name: "duplicate",
987
+ content: [
988
+ `schema: ${projectConfigSchema}`,
989
+ "overrides:",
990
+ " project:",
991
+ " name: duplicate-one",
992
+ " name: duplicate-two",
993
+ "",
994
+ ].join("\n"),
995
+ hints: ["duplicate"],
996
+ },
997
+ {
998
+ name: "alias",
999
+ content: [
1000
+ `schema: ${projectConfigSchema}`,
1001
+ "overrides:",
1002
+ " project: &shared_project",
1003
+ " name: alias-project",
1004
+ " docs: *shared_project",
1005
+ "",
1006
+ ].join("\n"),
1007
+ hints: ["alias", "anchor"],
1008
+ },
1009
+ ];
1010
+ for (const invalid of invalidCases) {
1011
+ const repo = tmpdir(`project-config-invalid-${invalid.name}`);
1012
+ run("node", [cli, "init"], { cwd: repo });
1013
+ const overlay = projectConfigPath(repo);
1014
+ writeFile(overlay, invalid.content);
1015
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1016
+ writeFile(skill, `must-stay-${invalid.name}\n`);
1017
+ const engineeringBefore = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"));
1018
+ const result = run("node", [cli, "init"], { cwd: repo, check: false });
1019
+ const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
1020
+ assert(result.status !== 0, `${invalid.name}: invalid project overlay must reject init`);
1021
+ assert(invalid.hints.some(hint => output.includes(hint)), `${invalid.name}: failure must identify the unsafe YAML construct: ${output}`);
1022
+ assert(fs.readFileSync(skill, "utf8") === `must-stay-${invalid.name}\n`, `${invalid.name}: overlay validation must happen before managed Skill writes`);
1023
+ assert(fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md")).equals(engineeringBefore), `${invalid.name}: overlay validation must happen before managed document writes`);
1024
+ assert(fs.readFileSync(overlay, "utf8") === invalid.content, `${invalid.name}: rejected init must not rewrite the project overlay`);
1025
+ }
1026
+
1027
+ const batchFirst = tmpdir("project-config-invalid-batch-first");
1028
+ const batchSecond = tmpdir("project-config-invalid-batch-second");
1029
+ run("node", [cli, "init"], { cwd: batchFirst });
1030
+ run("node", [cli, "init"], { cwd: batchSecond });
1031
+ const firstSkill = path.join(batchFirst, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1032
+ writeFile(firstSkill, "batch-must-stay\n");
1033
+ writeFile(projectConfigPath(batchSecond), invalidCases[0].content);
1034
+ const batch = run("node", [cli, "sync", "--projects", `${batchFirst},${batchSecond}`], { check: false });
1035
+ assert(batch.status !== 0, "one invalid overlay must reject the complete multi-project sync batch");
1036
+ assert(fs.readFileSync(firstSkill, "utf8") === "batch-must-stay\n", "multi-project overlay preflight must run before writing an earlier valid project");
1037
+ assert(fs.readFileSync(projectConfigPath(batchSecond), "utf8") === invalidCases[0].content, "multi-project rejection must not rewrite the invalid overlay");
1038
+
1039
+ if (process.platform !== "win32") {
1040
+ const repo = tmpdir("project-config-invalid-symlink");
1041
+ run("node", [cli, "init"], { cwd: repo });
1042
+ const overlay = projectConfigPath(repo);
1043
+ const external = path.join(tmpdir("project-config-external"), "outside.yaml");
1044
+ const externalBytes = `${JSON.stringify({ schema: projectConfigSchema, overrides: { project: { name: "outside" } } }, null, 2)}\n`;
1045
+ writeFile(external, externalBytes);
1046
+ fs.unlinkSync(overlay);
1047
+ fs.symlinkSync(external, overlay);
1048
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1049
+ writeFile(skill, "must-stay-symlink\n");
1050
+ const result = run("node", [cli, "sync", "--projects", repo], { check: false });
1051
+ const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
1052
+ assert(result.status !== 0 && (output.includes("symlink") || output.includes("non-symlink")), "overlay symlink must reject sync before writes");
1053
+ assert(fs.readFileSync(skill, "utf8") === "must-stay-symlink\n", "overlay symlink preflight must happen before managed Skill writes");
1054
+ assert(fs.readFileSync(external, "utf8") === externalBytes, "overlay validation must never follow or rewrite a symlink target");
1055
+ assert(fs.lstatSync(overlay).isSymbolicLink(), "rejected sync must leave the project-owned symlink untouched");
1056
+ }
1057
+ }
1058
+
1059
+ function testStatusRejectsManagedAgentSymlinksWithoutLeakingExternalContent() {
1060
+ if (process.platform === "win32") return;
1061
+ for (const target of ["agents-directory", "agents-parent"]) {
1062
+ const repo = tmpdir(`status-agent-symlink-${target}`);
1063
+ const secret = `UNIQUE_STATUS_AGENT_SYMLINK_SECRET_${target}_7f42`;
1064
+ run("node", [cli, "init"], { cwd: repo });
1065
+ fillRequiredAccess(repo);
1066
+ const agentsRoot = path.join(repo, ".agents");
1067
+ const agentsDir = path.join(agentsRoot, "agents");
1068
+
1069
+ if (target === "agents-directory") {
1070
+ const external = path.join(tmpdir("status-external-agents-directory"), "agents");
1071
+ fs.mkdirSync(external);
1072
+ writeFile(path.join(external, "explorer.toml"), `description = ${JSON.stringify(secret)}\n`);
1073
+ fs.rmSync(agentsDir, { recursive: true });
1074
+ fs.symlinkSync(external, agentsDir);
1075
+ } else {
1076
+ const external = path.join(tmpdir("status-external-agents-parent"), "agents-root");
1077
+ fs.renameSync(agentsRoot, external);
1078
+ fs.appendFileSync(path.join(external, "agents", "explorer.toml"), `\n# ${secret}\n`);
1079
+ fs.symlinkSync(external, agentsRoot);
1080
+ }
1081
+
1082
+ const status = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
1083
+ const output = `${status.stdout}\n${status.stderr}`;
1084
+ assert(status.status !== 0, `${target}: status must reject a managed-agent path that escapes through a symlink`);
1085
+ assert(!output.includes(secret), `${target}: status must never echo content read from the external symlink target: ${output}`);
1086
+ assert(/symlink|junction|real directory|non-directory/i.test(output), `${target}: status must explain the unsafe managed target shape: ${output}`);
1087
+ }
1088
+ }
1089
+
1090
+ function testMultiProjectSyncRejectsManagedTargetSymlinksBeforeAnyProjectWrite() {
1091
+ if (process.platform === "win32") return;
1092
+ for (const target of ["parent", "leaf"]) {
1093
+ const first = tmpdir(`managed-target-batch-first-${target}`);
1094
+ const second = tmpdir(`managed-target-batch-second-${target}`);
1095
+ run("node", [cli, "init"], { cwd: first });
1096
+ run("node", [cli, "init"], { cwd: second });
1097
+
1098
+ const firstProtected = [
1099
+ path.join(first, ".agents", "skills", "auto-coding-skill", "SKILL.md"),
1100
+ path.join(first, ".agents", "managed-install.json"),
1101
+ path.join(first, ".agents", "agents", "explorer.toml"),
1102
+ path.join(first, "docs", "ENGINEERING.md"),
1103
+ ];
1104
+ writeFile(firstProtected[0], `first-project-zero-write-sentinel-${target}\n`);
1105
+ const before = new Map(firstProtected.map(file => [file, fs.readFileSync(file)]));
1106
+ const secret = `UNIQUE_BATCH_MANAGED_TARGET_SECRET_${target}_98d1`;
1107
+ const external = path.join(tmpdir(`managed-target-external-${target}`), "target");
1108
+ let linked;
1109
+ let externalFile;
1110
+ if (target === "parent") {
1111
+ fs.mkdirSync(external);
1112
+ externalFile = path.join(external, "explorer.toml");
1113
+ writeFile(externalFile, `description = ${JSON.stringify(secret)}\n`);
1114
+ linked = path.join(second, ".agents", "agents");
1115
+ fs.rmSync(linked, { recursive: true });
1116
+ fs.symlinkSync(external, linked);
1117
+ } else {
1118
+ externalFile = external;
1119
+ writeFile(external, `description = ${JSON.stringify(secret)}\n`);
1120
+ linked = path.join(second, ".agents", "agents", "explorer.toml");
1121
+ fs.unlinkSync(linked);
1122
+ fs.symlinkSync(external, linked);
1123
+ }
1124
+
1125
+ const sync = run("node", [cli, "sync", "--projects", `${first},${second}`], { check: false });
1126
+ const output = `${sync.stdout}\n${sync.stderr}`;
1127
+ assert(sync.status !== 0, `${target}: one unsafe managed target must reject multi-project sync`);
1128
+ assert(/symlink|junction|non-directory/i.test(output), `${target}: batch rejection must identify the unsafe target shape: ${output}`);
1129
+ assert(!output.includes(secret), `${target}: batch rejection must not echo the external managed-target content: ${output}`);
1130
+ for (const file of firstProtected) {
1131
+ assert(fs.readFileSync(file).equals(before.get(file)), `${target}: second-project preflight failure must leave first project untouched: ${path.relative(first, file)}`);
1132
+ }
1133
+ assert(fs.lstatSync(linked).isSymbolicLink(), `${target}: rejected batch must leave the unsafe second-project link untouched`);
1134
+ assert(fs.readFileSync(externalFile, "utf8").includes(secret), `${target}: rejected batch must leave the external target untouched`);
1135
+ }
1136
+ }
1137
+
1138
+ function testTamperedInstalledDefaultRejectsInitAndSyncWithoutWrites() {
1139
+ const repo = tmpdir("project-config-tampered-old-default");
1140
+ run("node", [cli, "init"], { cwd: repo });
1141
+ const overlay = projectConfigPath(repo);
1142
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
1143
+ const installedTemplate = path.join(
1144
+ repo,
1145
+ ".agents",
1146
+ "skills",
1147
+ "auto-coding-skill",
1148
+ "data",
1149
+ "templates",
1150
+ "ENGINEERING.md",
1151
+ );
1152
+ const manifest = path.join(repo, ".agents", "managed-install.json");
1153
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1154
+ const oldDefault = fs.readFileSync(engineering, "utf8")
1155
+ .replace(/^ skill_version:.*$/m, ' skill_version: "4.2.7"')
1156
+ .replace("managed-workflow:start version=4.3.0", "managed-workflow:start version=4.2.7");
1157
+ installTrustedEngineeringDefault(repo, oldDefault, "4.2.7");
1158
+ writeFile(engineering, oldDefault);
1159
+ fs.unlinkSync(overlay);
1160
+ fillLegacyEngineeringAccess(repo, "tampered-old-default-secret");
1161
+ fs.appendFileSync(installedTemplate, "\n# untrusted template mutation\n");
1162
+ writeFile(skill, "tampered-template-zero-write-sentinel\n");
1163
+
1164
+ const protectedPaths = [engineering, installedTemplate, manifest, skill];
1165
+ for (const args of [["init"], ["sync", "--projects", repo]]) {
1166
+ const before = new Map(protectedPaths.map(file => [file, fs.readFileSync(file)]));
1167
+ const result = run("node", [cli, ...args], { cwd: repo, check: false });
1168
+ const output = `${result.stdout}\n${result.stderr}`;
1169
+ assert(result.status !== 0, `${args[0]} must reject a tampered installed old default`);
1170
+ assert(output.includes("managed manifest identity check"), `${args[0]} must identify the untrusted installed template: ${output}`);
1171
+ for (const file of protectedPaths) {
1172
+ assert(fs.readFileSync(file).equals(before.get(file)), `${args[0]} must perform zero writes before rejecting ${path.relative(repo, file)}`);
1173
+ }
1174
+ assert(!exists(overlay), `${args[0]} must not create an overlay from an untrusted installed default`);
1175
+ }
1176
+ }
1177
+
1178
+ function testExistingOverlayConflictRejectsInitAndSyncWithoutWrites() {
1179
+ const repo = tmpdir("project-config-existing-conflict");
1180
+ run("node", [cli, "init"], { cwd: repo });
1181
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
1182
+ const overlay = projectConfigPath(repo);
1183
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1184
+ const conflicting = fs.readFileSync(engineering, "utf8")
1185
+ .replace(/^ name:.*$/m, ' name: "legacy-conflicting-name"');
1186
+ writeFile(engineering, conflicting);
1187
+ writeFile(skill, "overlay-conflict-zero-write-sentinel\n");
1188
+
1189
+ const protectedPaths = [engineering, overlay, skill, path.join(repo, ".agents", "managed-install.json")];
1190
+ for (const args of [["init"], ["sync", "--projects", repo]]) {
1191
+ const before = new Map(protectedPaths.map(file => [file, fs.readFileSync(file)]));
1192
+ const result = run("node", [cli, ...args], { cwd: repo, check: false });
1193
+ const output = `${result.stdout}\n${result.stderr}`;
1194
+ assert(result.status !== 0, `${args[0]} must reject legacy values that conflict with an existing overlay`);
1195
+ assert(output.includes("overlay conflicts with legacy project configuration"), `${args[0]} must explain the conflicting ownership boundary: ${output}`);
1196
+ for (const file of protectedPaths) {
1197
+ assert(fs.readFileSync(file).equals(before.get(file)), `${args[0]} must perform zero writes before rejecting ${path.relative(repo, file)}`);
1198
+ }
1199
+ }
1200
+ }
1201
+
1202
+ function testExistingOverlayLegacyDeletionRejectsInitAndSyncWithoutWrites() {
1203
+ const repo = tmpdir("project-config-existing-deletion");
1204
+ run("node", [cli, "init"], { cwd: repo });
1205
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
1206
+ const overlay = projectConfigPath(repo);
1207
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1208
+ const current = fs.readFileSync(engineering, "utf8");
1209
+ const deletedDefault = current.replace(/^ api_change_log: "docs\/interfaces\/api-change-log\.md"\r?\n/m, "");
1210
+ assert(deletedDefault !== current, "legacy deletion fixture must remove one managed default key");
1211
+ writeFile(engineering, deletedDefault);
1212
+ writeFile(skill, "legacy-deletion-zero-write-sentinel\n");
1213
+
1214
+ const protectedPaths = [engineering, overlay, skill, path.join(repo, ".agents", "managed-install.json")];
1215
+ for (const args of [["init"], ["sync", "--projects", repo]]) {
1216
+ const before = new Map(protectedPaths.map(file => [file, fs.readFileSync(file)]));
1217
+ const result = run("node", [cli, ...args], { cwd: repo, check: false });
1218
+ const output = `${result.stdout}\n${result.stderr}`;
1219
+ assert(result.status !== 0, `${args[0]} must reject a legacy deletion that additive overrides cannot represent`);
1220
+ assert(output.includes("cannot be represented as additive overrides"), `${args[0]} must explain the deleted-default ambiguity: ${output}`);
1221
+ for (const file of protectedPaths) {
1222
+ assert(fs.readFileSync(file).equals(before.get(file)), `${args[0]} must perform zero writes before rejecting ${path.relative(repo, file)}`);
1223
+ }
1224
+ }
1225
+ }
1226
+
1227
+ function testLiveInstallTransactionRejectsSecondInstallerWithoutWrites() {
1228
+ const repo = tmpdir("live-install-owner");
1229
+ run("node", [cli, "init"], { cwd: repo });
1230
+ const installedAp = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
1231
+ writeFile(installedAp, "live-owner-sentinel\n");
1232
+
1233
+ const first = spawn(
1234
+ process.execPath,
1235
+ [cli, "sync", "--projects", repo],
1236
+ {
1237
+ cwd: repo,
1238
+ env: {
1239
+ ...process.env,
1240
+ AUTOCODING_TEST_HOLD_PHASE: "after-stage-copy",
1241
+ AUTOCODING_TEST_HOLD_MILLISECONDS: "5000",
1242
+ },
1243
+ stdio: "ignore",
1244
+ },
1245
+ );
1246
+ const transaction = path.join(repo, ".agents", ".auto-coding-skill-install-transaction");
1247
+ const statePath = path.join(transaction, "state.json");
1248
+ const sleep = new Int32Array(new SharedArrayBuffer(4));
1249
+ const stagedDeadline = Date.now() + 10000;
1250
+ while (!exists(statePath) && Date.now() < stagedDeadline) Atomics.wait(sleep, 0, 0, 5);
1251
+ assert(exists(statePath), "first installer must publish a durable state before the concurrency check");
1252
+ const owner = JSON.parse(fs.readFileSync(path.join(transaction, "owner.json"), "utf8"));
1253
+ assert(owner.pid === first.pid, "transaction owner lease must bind the live installer pid");
1254
+
1255
+ const protectedPaths = [
1256
+ installedAp,
1257
+ path.join(repo, ".agents", "managed-install.json"),
1258
+ path.join(repo, "docs", "ENGINEERING.md"),
1259
+ projectConfigPath(repo),
1260
+ ];
1261
+ const beforeSecond = new Map(protectedPaths.map(file => [file, fs.readFileSync(file)]));
1262
+ const second = run("node", [cli, "sync", "--projects", repo], { cwd: repo, check: false });
1263
+ const secondOutput = `${second.stdout}\n${second.stderr}`;
1264
+ assert(second.status !== 0, "a second installer must reject a live install transaction");
1265
+ assert(secondOutput.includes("install transaction is active under owner pid"), `live-owner rejection must be explicit: ${secondOutput}`);
1266
+ assert(exists(transaction), "second installer must not remove the live transaction");
1267
+ for (const file of protectedPaths) {
1268
+ assert(fs.readFileSync(file).equals(beforeSecond.get(file)), `second installer must perform zero canonical writes: ${path.relative(repo, file)}`);
1269
+ }
1270
+
1271
+ const waitForCompletion = [
1272
+ "const fs = require('node:fs');",
1273
+ "const target = process.argv[1];",
1274
+ "const sleep = new Int32Array(new SharedArrayBuffer(4));",
1275
+ "const deadline = Date.now() + 15000;",
1276
+ "while (fs.existsSync(target) && Date.now() < deadline) Atomics.wait(sleep, 0, 0, 10);",
1277
+ "process.exit(fs.existsSync(target) ? 2 : 0);",
1278
+ ].join("\n");
1279
+ const completed = run(process.execPath, ["-e", waitForCompletion, transaction], { check: false });
1280
+ first.kill();
1281
+ assert(completed.status === 0, "live owner must finish normally after the rejected second installer");
1282
+ assert(!fs.readFileSync(installedAp, "utf8").includes("live-owner-sentinel"), "the live owner must retain control and finish its own upgrade");
1283
+ }
1284
+
1285
+ function testStagedRuntimeTamperingIsRejectedBeforeExecution() {
1286
+ const repo = tmpdir("staged-runtime-tamper");
1287
+ run("node", [cli, "init"], { cwd: repo });
1288
+
1289
+ // Keep beginInstallTransaction busy after it has hashed new-skill. The
1290
+ // watcher uses old-skill creation as the deterministic signal that this
1291
+ // binding has already happened, then changes the staged runtime.
1292
+ const installedSkill = path.join(repo, ".agents", "skills", "auto-coding-skill");
1293
+ fs.writeFileSync(path.join(installedSkill, "zzzz-staging-delay.bin"), Buffer.alloc(32 * 1024 * 1024, 0x61));
1294
+ const installedAp = path.join(installedSkill, "scripts", "ap.py");
1295
+ const installedBefore = fs.readFileSync(installedAp);
1296
+ const transaction = path.join(repo, ".agents", ".auto-coding-skill-install-transaction");
1297
+ const oldSkill = path.join(transaction, "old-skill");
1298
+ const stagedAp = path.join(transaction, "new-skill", "scripts", "ap.py");
1299
+ const ready = path.join(repo, "attacker-ready");
1300
+ const tampered = path.join(repo, "staged-runtime-tampered");
1301
+ const executed = path.join(repo, "tampered-runtime-executed");
1302
+ const malicious = [
1303
+ "from pathlib import Path",
1304
+ `Path(${JSON.stringify(executed)}).write_text('executed', encoding='utf-8')`,
1305
+ "print('{}')",
1306
+ "",
1307
+ ].join("\n");
1308
+ const watcher = [
1309
+ "const fs = require('node:fs');",
1310
+ "const [oldSkill, stagedAp, ready, tampered, malicious] = process.argv.slice(1);",
1311
+ "fs.writeFileSync(ready, 'ready');",
1312
+ "const deadline = Date.now() + 15000;",
1313
+ "const sleep = new Int32Array(new SharedArrayBuffer(4));",
1314
+ "while (Date.now() < deadline) {",
1315
+ " if (fs.existsSync(oldSkill) && fs.existsSync(stagedAp)) {",
1316
+ " fs.writeFileSync(stagedAp, Buffer.from(malicious, 'base64'));",
1317
+ " fs.writeFileSync(tampered, 'tampered');",
1318
+ " process.exit(0);",
1319
+ " }",
1320
+ " Atomics.wait(sleep, 0, 0, 1);",
1321
+ "}",
1322
+ "process.exit(3);",
1323
+ ].join("\n");
1324
+ const attacker = spawn(
1325
+ process.execPath,
1326
+ ["-e", watcher, oldSkill, stagedAp, ready, tampered, Buffer.from(malicious).toString("base64")],
1327
+ { stdio: "ignore" },
1328
+ );
1329
+ const sleep = new Int32Array(new SharedArrayBuffer(4));
1330
+ const readyDeadline = Date.now() + 5000;
1331
+ while (!exists(ready) && Date.now() < readyDeadline) Atomics.wait(sleep, 0, 0, 5);
1332
+ assert(exists(ready), "staged-runtime tamper watcher must start before sync");
1333
+
1334
+ const result = run("node", [cli, "sync", "--projects", repo], { cwd: repo, check: false });
1335
+ attacker.kill();
1336
+ const output = `${result.stdout}\n${result.stderr}`;
1337
+ assert(exists(tampered), `test watcher must alter the staged runtime: ${output}`);
1338
+ assert(result.status !== 0, "transaction must reject a staged runtime changed after its binding hash");
1339
+ assert(output.includes("staged Skill failed its transaction identity check"), `tamper failure must identify the staged Skill binding: ${output}`);
1340
+ assert(!exists(executed), "tampered staged ap.py must never execute");
1341
+ assert(fs.readFileSync(installedAp).equals(installedBefore), "pre-switch tamper rejection must leave the installed runtime unchanged");
1342
+ assert(exists(path.join(transaction, "state.json")), "tamper rejection must retain the verified rollback transaction");
1343
+ }
1344
+
1345
+ function testInterruptedStagedInstallRecoversForInitAndSync() {
1346
+ const cases = [
1347
+ {
1348
+ name: "init-after-config-finalize",
1349
+ phase: "after-config-finalize",
1350
+ args() { return ["init"]; },
1351
+ },
1352
+ {
1353
+ name: "sync-after-runtime-switch",
1354
+ phase: "after-runtime-switch",
1355
+ args(repo) { return ["sync", "--projects", repo]; },
1356
+ },
1357
+ ];
1358
+
1359
+ for (const interrupted of cases) {
1360
+ const repo = tmpdir(`staged-recovery-${interrupted.name}`);
1361
+ const projectName = `specialized-${interrupted.name}`;
1362
+ const projectStack = `stack-${interrupted.name}`;
1363
+ const secret = `secret-${interrupted.name}`;
1364
+ run("node", [cli, "init"], { cwd: repo });
1365
+
1366
+ // Exercise the migration/finalize boundary: prepare must first extract
1367
+ // these project-owned values from a legacy managed document into a new
1368
+ // overlay, and recovery must never normalize or lose that overlay.
1369
+ fs.unlinkSync(projectConfigPath(repo));
1370
+ fillLegacyEngineeringAccess(repo, secret);
1371
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
1372
+ const specialized = fs.readFileSync(engineering, "utf8")
1373
+ .replace(/^ name:.*$/m, ` name: ${JSON.stringify(projectName)}`)
1374
+ .replace(/^ stack:.*$/m, ` stack: ${JSON.stringify(projectStack)}`)
1375
+ .replace(/^ target_branch:.*$/m, ' target_branch: "dev"')
1376
+ .replace(/^ api_docs_required: false$/m, " api_docs_required: true");
1377
+ writeFile(engineering, specialized);
1378
+
1379
+ const args = interrupted.args(repo);
1380
+ const failed = run("node", [cli, ...args], {
1381
+ cwd: repo,
1382
+ check: false,
1383
+ env: { AUTOCODING_TEST_FAIL_PHASE: interrupted.phase },
1384
+ });
1385
+ const failedOutput = `${failed.stdout}\n${failed.stderr}`;
1386
+ assert(failed.status !== 0, `${interrupted.name}: injected staged install must fail`);
1387
+ assert(failedOutput.includes(`injected auto-coding-skill install fault: ${interrupted.phase}`), `${interrupted.name}: failure must identify the injected phase: ${failedOutput}`);
1388
+
1389
+ const transaction = path.join(repo, ".agents", ".auto-coding-skill-install-transaction");
1390
+ assert(exists(transaction), `${interrupted.name}: interrupted install must retain its recovery transaction`);
1391
+ const overlay = projectConfigPath(repo);
1392
+ assert(exists(overlay), `${interrupted.name}: prepare must durably create the project overlay before runtime switching`);
1393
+ const overlayAfterFailure = fs.readFileSync(overlay);
1394
+ const migrated = readYamlConfig(overlay).overrides;
1395
+ assert(migrated.project?.name === projectName && migrated.project?.stack === projectStack, `${interrupted.name}: interrupted prepare must preserve specialized project values`);
1396
+ assert(migrated.access?.project?.frontend?.password === secret, `${interrupted.name}: interrupted prepare must preserve specialized access values`);
1397
+
1398
+ run("node", [cli, ...args], { cwd: repo });
1399
+ assert(fs.readFileSync(overlay).equals(overlayAfterFailure), `${interrupted.name}: retry recovery must preserve overlay bytes exactly`);
1400
+ const effective = readEffectiveConfig(repo);
1401
+ assert(effective.project?.name === projectName && effective.project?.stack === projectStack, `${interrupted.name}: recovered effective config must retain specialized project identity`);
1402
+ assert(effective.concurrency?.target_branch === "dev", `${interrupted.name}: recovered effective config must retain the specialized target branch`);
1403
+ assert(effective.access?.project?.frontend?.password === secret, `${interrupted.name}: recovered effective config must retain specialized access values`);
1404
+ assert(effective.docs?.api_docs_required === true, `${interrupted.name}: recovered effective config must retain specialized documentation policy`);
1405
+ assert(!exists(transaction), `${interrupted.name}: successful retry must remove the active install transaction`);
1406
+ const transactionArtifacts = fs.readdirSync(path.join(repo, ".agents"))
1407
+ .filter(name => name.startsWith(".auto-coding-skill-install-"));
1408
+ assert(transactionArtifacts.length === 0, `${interrupted.name}: successful retry must clean every install transaction artifact: ${transactionArtifacts.join(", ")}`);
1409
+
1410
+ const status = run("node", [cli, "status", "--projects", repo, "--json"]);
1411
+ assert(JSON.parse(status.stdout).results[0].ok === true, `${interrupted.name}: recovered installation must be complete and healthy: ${status.stdout}`);
1412
+ assert(fs.readFileSync(overlay).equals(overlayAfterFailure), `${interrupted.name}: read-only status must leave overlay bytes stable`);
1413
+ }
1414
+ }
1415
+
1416
+ function testArchiveFallbackCollisionsNeverLosePreviousContent() {
1417
+ const digest12 = payload => crypto.createHash("sha256").update(payload).digest("hex").slice(0, 12);
1418
+ const assertUnchanged = (file, expected, label) => {
1419
+ assert(fs.readFileSync(file).equals(expected), `${label}: occupied archive bytes must not be overwritten`);
1420
+ };
1421
+ const assertPreservedAnywhere = (repo, expected, label) => {
1422
+ assert(
1423
+ listProjectFiles(repo).some(file => fs.readFileSync(file).equals(expected)),
1424
+ `${label}: occupied archive bytes must remain available somewhere in project history`,
1425
+ );
1426
+ };
1427
+ const assertArchived = (directory, expected, label, suffix = false) => {
1428
+ const archived = listProjectFiles(directory).some(file => {
1429
+ const payload = fs.readFileSync(file);
1430
+ if (!suffix) return payload.equals(expected);
1431
+ return payload.length >= expected.length
1432
+ && payload.subarray(payload.length - expected.length).equals(expected);
1433
+ });
1434
+ assert(archived, `${label}: previous content must survive default and digest archive collisions`);
1435
+ };
1436
+
1437
+ {
1438
+ const repo = tmpdir("archive-collision-engineering");
1439
+ run("node", [cli, "init"], { cwd: repo });
1440
+ fs.unlinkSync(projectConfigPath(repo));
1441
+ fillLegacyEngineeringAccess(repo, "archive-collision-secret");
1442
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
1443
+ fs.appendFileSync(engineering, "\n## Archive collision sentinel\n\nPreserve these ENGINEERING bytes.\n");
1444
+ const previous = fs.readFileSync(engineering);
1445
+ const archiveDir = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs");
1446
+ const preferred = path.join(archiveDir, "ENGINEERING.md");
1447
+ const legacyDigest = path.join(archiveDir, `ENGINEERING-${digest12(previous)}.md`);
1448
+ const occupiedPreferred = Buffer.from("occupied-engineering-default\n");
1449
+ const occupiedDigest = Buffer.from("occupied-engineering-digest\n");
1450
+ writeFile(preferred, occupiedPreferred);
1451
+ writeFile(legacyDigest, occupiedDigest);
1452
+
1453
+ run("node", [cli, "init"], { cwd: repo });
1454
+
1455
+ assertUnchanged(preferred, occupiedPreferred, "ENGINEERING default collision");
1456
+ assertUnchanged(legacyDigest, occupiedDigest, "ENGINEERING digest collision");
1457
+ assertArchived(archiveDir, previous, "ENGINEERING migration", true);
1458
+ assert(
1459
+ readEffectiveConfig(repo).access?.project?.frontend?.password === "archive-collision-secret",
1460
+ "ENGINEERING archive fallback must not disrupt project configuration migration",
1461
+ );
1462
+ }
1463
+
1464
+ {
1465
+ const repo = tmpdir("archive-collision-managed-template");
1466
+ run("node", [cli, "init"], { cwd: repo });
1467
+ const managed = path.join(repo, "docs", "design", "_TEMPLATE-DD.md");
1468
+ const previous = Buffer.from("# Project-specific design template\n\nPreserve these exact bytes.\n");
1469
+ fs.writeFileSync(managed, previous);
1470
+ const archiveDir = path.join(
1471
+ repo,
1472
+ ".agents",
1473
+ "archive",
1474
+ "auto-coding-skill",
1475
+ "4.3.0",
1476
+ "docs",
1477
+ "design",
1478
+ );
1479
+ const preferred = path.join(archiveDir, "_TEMPLATE-DD.md");
1480
+ const legacyDigest = path.join(archiveDir, `_TEMPLATE-DD-${digest12(previous)}.md`);
1481
+ const occupiedPreferred = Buffer.from("occupied-template-default\n");
1482
+ const occupiedDigest = Buffer.from("occupied-template-digest\n");
1483
+ writeFile(preferred, occupiedPreferred);
1484
+ writeFile(legacyDigest, occupiedDigest);
1485
+
1486
+ run("node", [cli, "init"], { cwd: repo });
1487
+
1488
+ assertUnchanged(preferred, occupiedPreferred, "managed template default collision");
1489
+ assertUnchanged(legacyDigest, occupiedDigest, "managed template digest collision");
1490
+ assertArchived(archiveDir, previous, "managed template migration");
1491
+ assert(!fs.readFileSync(managed).equals(previous), "managed template must still converge after safe archival");
1492
+ }
1493
+
1494
+ {
1495
+ const repo = tmpdir("archive-collision-agents-sync");
1496
+ run("node", [cli, "init"], { cwd: repo });
1497
+ const agents = path.join(repo, "AGENTS.md");
1498
+ const previous = Buffer.from("# Project AGENTS before sync\n\nPreserve this sync history.\n");
1499
+ fs.writeFileSync(agents, previous);
1500
+ const archiveDir = path.join(repo, "docs", "archive", "workflow");
1501
+ const preferred = path.join(archiveDir, "AGENTS.pre-4.3.0.md");
1502
+ const legacyDigest = path.join(archiveDir, `AGENTS.pre-4.3.0-${digest12(previous)}.md`);
1503
+ const occupiedPreferred = Buffer.from("occupied-sync-default\n");
1504
+ const occupiedDigest = Buffer.from("occupied-sync-digest\n");
1505
+ writeFile(preferred, occupiedPreferred);
1506
+ writeFile(legacyDigest, occupiedDigest);
1507
+
1508
+ run("node", [cli, "sync", "--projects", repo]);
1509
+
1510
+ assertPreservedAnywhere(repo, occupiedPreferred, "sync AGENTS default collision");
1511
+ assertPreservedAnywhere(repo, occupiedDigest, "sync AGENTS digest collision");
1512
+ assertArchived(archiveDir, previous, "sync AGENTS migration", true);
1513
+ assert(!fs.readFileSync(agents).equals(previous), "sync AGENTS must still converge after safe archival");
1514
+ }
1515
+
1516
+ {
1517
+ const repo = tmpdir("archive-collision-agents-init");
1518
+ run("node", [cli, "init"], { cwd: repo });
1519
+ const agents = path.join(repo, "AGENTS.md");
1520
+ const previous = Buffer.from("# Project AGENTS before init\n\nPreserve this init history.\n");
1521
+ fs.writeFileSync(agents, previous);
1522
+ const archiveDir = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0");
1523
+ const preferred = path.join(archiveDir, "AGENTS.md");
1524
+ const legacyDigest = path.join(archiveDir, `AGENTS-${digest12(previous)}.md`);
1525
+ const occupiedPreferred = Buffer.from("occupied-init-default\n");
1526
+ const occupiedDigest = Buffer.from("occupied-init-digest\n");
1527
+ writeFile(preferred, occupiedPreferred);
1528
+ writeFile(legacyDigest, occupiedDigest);
1529
+
1530
+ run("node", [cli, "init"], { cwd: repo });
1531
+
1532
+ assertUnchanged(preferred, occupiedPreferred, "init AGENTS default collision");
1533
+ assertUnchanged(legacyDigest, occupiedDigest, "init AGENTS digest collision");
1534
+ assertArchived(archiveDir, previous, "init AGENTS migration");
1535
+ assert(!fs.readFileSync(agents).equals(previous), "init AGENTS must still converge after safe archival");
1536
+ }
1537
+ }
1538
+
1539
+ function testProjectMutationAndInstallSwitchRejectParentSwap() {
1540
+ if (process.platform === "win32") return;
1541
+
1542
+ const assertExternalUntouched = (external, sentinel, label) => {
1543
+ const files = listProjectFiles(external);
1544
+ assert(files.length === 1 && files[0] === sentinel, `${label}: project mutation must not create external files`);
1545
+ assert(fs.readFileSync(sentinel, "utf8") === "external-sentinel\n", `${label}: external sentinel must remain unchanged`);
1546
+ };
1547
+ const restoreParent = (target, backup) => {
1548
+ assert(fs.lstatSync(target).isSymbolicLink(), `swap fixture must leave a symlink at ${target}`);
1549
+ fs.unlinkSync(target);
1550
+ fs.renameSync(backup, target);
1551
+ };
1552
+
1553
+ {
1554
+ const repo = tmpdir("project-file-parent-swap");
1555
+ run("node", [cli, "init"], { cwd: repo });
1556
+ const external = tmpdir("project-file-parent-swap-external");
1557
+ const sentinel = path.join(external, "sentinel.txt");
1558
+ writeFile(sentinel, "external-sentinel\n");
1559
+ const parent = path.join(repo, ".agents", "agents");
1560
+ const backup = path.join(repo, ".agents", "agents.autocoding-test-backup");
1561
+ const failed = run("node", [cli, "init"], {
1562
+ cwd: repo,
1563
+ check: false,
1564
+ env: {
1565
+ AUTOCODING_TEST_MODE: "1",
1566
+ AUTOCODING_TEST_PROJECT_FILE_SWAP_PATH: ".agents/agents/browser-debugger.toml",
1567
+ AUTOCODING_TEST_PROJECT_FILE_SWAP_EXTERNAL: external,
1568
+ AUTOCODING_TEST_PROJECT_FILE_SWAP_BACKUP: backup,
1569
+ },
1570
+ });
1571
+ const output = `${failed.stdout}\n${failed.stderr}`;
1572
+ assert(failed.status !== 0 && output.includes("Project path parent changed"), `project file parent swap must fail closed: ${output}`);
1573
+ assertExternalUntouched(external, sentinel, "project file parent swap");
1574
+ restoreParent(parent, backup);
1575
+ run("node", [cli, "init"], { cwd: repo });
1576
+ assertExternalUntouched(external, sentinel, "project file parent swap recovery");
1577
+ }
1578
+
1579
+ {
1580
+ const repo = tmpdir("install-switch-parent-swap");
1581
+ run("node", [cli, "init"], { cwd: repo });
1582
+ const external = tmpdir("install-switch-parent-swap-external");
1583
+ const sentinel = path.join(external, "sentinel.txt");
1584
+ writeFile(sentinel, "external-sentinel\n");
1585
+ const parent = path.join(repo, ".agents", "skills");
1586
+ const backup = path.join(repo, ".agents", "skills.autocoding-test-backup");
1587
+ const failed = run("node", [cli, "init"], {
1588
+ cwd: repo,
1589
+ check: false,
1590
+ env: {
1591
+ AUTOCODING_TEST_MODE: "1",
1592
+ AUTOCODING_TEST_INSTALL_IO_SWAP_PHASE: "switch",
1593
+ AUTOCODING_TEST_INSTALL_IO_SWAP_PARENT: ".agents/skills",
1594
+ AUTOCODING_TEST_INSTALL_IO_SWAP_EXTERNAL: external,
1595
+ AUTOCODING_TEST_INSTALL_IO_SWAP_BACKUP: backup,
1596
+ },
1597
+ });
1598
+ const output = `${failed.stdout}\n${failed.stderr}`;
1599
+ assert(failed.status !== 0 && output.includes("Install I/O project parent changed"), `install switch parent swap must fail closed: ${output}`);
1600
+ assertExternalUntouched(external, sentinel, "install switch parent swap");
1601
+ restoreParent(parent, backup);
1602
+ run("node", [cli, "init"], { cwd: repo });
1603
+ assertExternalUntouched(external, sentinel, "install switch parent swap recovery");
1604
+ }
1605
+ }
1606
+
1607
+ function testNoChangeLightGateRejectsInvalidEffectiveContracts() {
1608
+ const cases = [
1609
+ {
1610
+ name: "risk-rules",
1611
+ mutate(overrides) {
1612
+ overrides.risk = { rules: { invalid: true } };
1613
+ },
1614
+ hints: ["risk.rules", "must be a list"],
1615
+ },
1616
+ {
1617
+ name: "validation-route",
1618
+ mutate(overrides) {
1619
+ overrides.validation = {
1620
+ ...(overrides.validation ?? {}),
1621
+ routes: [{ name: "invalid-empty-command-route", paths: ["**"], commands: [] }],
1622
+ };
1623
+ },
1624
+ hints: ["validation.routes[0].commands", "must not be empty"],
1625
+ },
1626
+ {
1627
+ name: "validation-budget",
1628
+ mutate(overrides) {
1629
+ overrides.validation = {
1630
+ ...(overrides.validation ?? {}),
1631
+ max_command_seconds: 181,
1632
+ max_total_seconds: 180,
1633
+ };
1634
+ },
1635
+ hints: ["max_command_seconds", "max_total_seconds"],
1636
+ },
1637
+ ];
1638
+
1639
+ for (const invalid of cases) {
1640
+ const repo = tmpdir(`no-change-light-gate-${invalid.name}`);
1641
+ run("node", [cli, "init"], { cwd: repo });
1642
+ fillRequiredAccess(repo);
1643
+ const overrides = readYamlConfig(projectConfigPath(repo)).overrides;
1644
+ invalid.mutate(overrides);
1645
+ writeProjectConfig(repo, overrides);
1646
+ run("git", ["init", "-q"], { cwd: repo });
1647
+ run("git", ["config", "user.email", "test@example.com"], { cwd: repo });
1648
+ run("git", ["config", "user.name", "Auto Coding Test"], { cwd: repo });
1649
+ run("git", ["add", "-A"], { cwd: repo });
1650
+ run("git", ["commit", "-qm", "invalid contract baseline"], { cwd: repo });
1651
+ assert(run("git", ["status", "--porcelain"], { cwd: repo }).stdout === "", `${invalid.name}: fixture must have no changed files`);
1652
+
1653
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
1654
+ if (invalid.name === "risk-rules") {
1655
+ const classify = run("python3", [
1656
+ launcher,
1657
+ "--repo", repo,
1658
+ "classify",
1659
+ "--planned-path", "sensitive/example.txt",
1660
+ "--json",
1661
+ ], { cwd: repo, check: false });
1662
+ const classifyOutput = `${classify.stdout}\n${classify.stderr}`;
1663
+ assert(classify.status !== 0, "malformed risk.rules must fail classify instead of downgrading a sensitive path");
1664
+ assert(classifyOutput.includes("risk.rules must be a list"), `classify must identify malformed risk.rules: ${classifyOutput}`);
1665
+
1666
+ const taskStart = run("python3", [
1667
+ launcher,
1668
+ "--repo", repo,
1669
+ "task-start", "INVALID-RISK-CONTRACT",
1670
+ "--owned-path", "sensitive/example.txt",
1671
+ "--force-lifecycle",
1672
+ ], { cwd: repo, check: false });
1673
+ const taskOutput = `${taskStart.stdout}\n${taskStart.stderr}`;
1674
+ assert(taskStart.status !== 0, "malformed risk.rules must fail task-start before isolation/review decisions");
1675
+ assert(taskOutput.includes("risk.rules must be a list"), `task-start must identify malformed risk.rules: ${taskOutput}`);
1676
+ }
1677
+ const gate = run("python3", [launcher, "--repo", repo, "light-gate", "--scope", "changed"], { cwd: repo, check: false });
1678
+ const output = `${gate.stdout}\n${gate.stderr}`;
1679
+ assert(gate.status !== 0, `${invalid.name}: an invalid effective contract must fail light-gate even with no changed files`);
1680
+ for (const hint of invalid.hints) {
1681
+ assert(output.includes(hint), `${invalid.name}: light-gate must report ${hint}: ${output}`);
1682
+ }
1683
+ }
1684
+ }
1685
+
1686
+ function testStatusRejectsInvalidStructureEnforcementFromDoctorContract() {
1687
+ const repo = tmpdir("invalid-structure-enforcement-status");
1688
+ run("node", [cli, "init"], { cwd: repo });
1689
+ fillRequiredAccess(repo);
1690
+ const overrides = readYamlConfig(projectConfigPath(repo)).overrides;
1691
+ writeProjectConfig(repo, {
1692
+ ...overrides,
1693
+ structure: { ...(overrides.structure ?? {}), enforcement: "strict-but-unknown" },
1694
+ });
1695
+
1696
+ const status = run("node", [cli, "status", "--projects", repo, "--json"], { check: false });
1697
+ assert(status.status !== 0, "status must reject an invalid structure enforcement value");
1698
+ const parsed = JSON.parse(status.stdout).results[0];
1699
+ assert(
1700
+ parsed.invalidConfigTokens.includes("structure.enforcement must be advisory or blocking"),
1701
+ `status must expose the structure issue from the complete doctor contract: ${status.stdout}`,
1702
+ );
1703
+ }
1704
+
1705
+ function testProjectConfigOverlayIsHighRiskAndReviewRequired() {
1706
+ const repo = tmpdir("project-config-classification");
1707
+ run("git", ["init", "-q"], { cwd: repo });
1708
+ run("node", [cli, "init"], { cwd: repo });
1709
+ run("git", ["config", "user.email", "test@example.com"], { cwd: repo });
1710
+ run("git", ["config", "user.name", "Auto Coding Test"], { cwd: repo });
1711
+ run("git", ["add", "-A"], { cwd: repo });
1712
+ run("git", ["commit", "-qm", "baseline"], { cwd: repo });
1713
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
1714
+ for (const plannedPath of ["docs/ENGINEERING.md", "docs/project/auto-coding-skill.yaml"]) {
1715
+ const result = run("python3", [
1716
+ launcher,
1717
+ "--repo", repo,
1718
+ "classify",
1719
+ "--planned-path", plannedPath,
1720
+ "--intent", `change Skill configuration at ${plannedPath}`,
1721
+ "--json",
1722
+ ]);
1723
+ const parsed = JSON.parse(result.stdout);
1724
+ assert(parsed.profile === "high-risk", `${plannedPath} changes must be high-risk: ${result.stdout}`);
1725
+ assert(parsed.review_required === true, `${plannedPath} changes must require independent review: ${result.stdout}`);
1726
+ }
1727
+ }
1728
+
1729
+ function testStatusAndFeedbackUseEffectiveProjectConfigWithoutLeakingAccess() {
1730
+ const repo = tmpdir("project-config-consumers");
1731
+ const projectName = "effective-overlay-project";
1732
+ const secret = "overlay-access-must-not-leak-c819";
1733
+ run("node", [cli, "init"], { cwd: repo });
1734
+ writeProjectConfig(repo, requiredProjectOverrides(projectName, secret));
1735
+ const engineering = readEngineeringConfig(path.join(repo, "docs", "ENGINEERING.md"));
1736
+ assert(engineering.project?.name === "", "managed ENGINEERING must not provide the effective project identity");
1737
+ assert(engineering.access?.project?.frontend?.password === "", "managed ENGINEERING must not provide effective access values");
1738
+
1739
+ const status = run("node", [cli, "status", "--projects", repo, "--json"]);
1740
+ assert(JSON.parse(status.stdout).results[0].ok === true, `status must validate the effective overlay configuration: ${status.stdout}`);
1741
+ assert(!status.stdout.includes(secret), "status must never print access values loaded from the project overlay");
1742
+
1743
+ const signature = `sha256:${"c".repeat(64)}`;
1744
+ const report = path.join(repo, "docs", "skill-feedback", "reports", "2026-07-18-effective-config-c819a2e4.md");
1745
+ writeFile(report, [
1746
+ "---",
1747
+ "schema: auto-coding-skill-feedback/v1",
1748
+ "report_id: ACSF-effective-20260718-c819a2e4",
1749
+ "status: open",
1750
+ 'created_at: "2026-07-18T10:00:00+08:00"',
1751
+ `project: ${projectName}`,
1752
+ `observed_skill_version: ${engineering.workflow.skill_version}`,
1753
+ "component: config-overlay",
1754
+ "kind: defect",
1755
+ "impact: minor",
1756
+ "origin_surface: managed-script",
1757
+ "suspected_scope: shared",
1758
+ `signature: ${signature}`,
1759
+ "export: metadata-only",
1760
+ "---",
1761
+ "# Effective config consumer",
1762
+ "",
1763
+ "## Symptom",
1764
+ "A consumer ignored the project overlay.",
1765
+ "",
1766
+ "## Expected",
1767
+ "Every consumer uses the effective project configuration.",
1768
+ "",
1769
+ "## Minimal reproduction",
1770
+ "Read this report using the configured project identity.",
1771
+ "",
1772
+ "## Evidence",
1773
+ "The metadata is intentionally non-sensitive.",
1774
+ "",
1775
+ "## Workaround",
1776
+ "None.",
1777
+ "",
1778
+ "## Why shared",
1779
+ "The project-independent consumer is managed by the Skill.",
1780
+ "",
1781
+ ].join("\n"));
1782
+ const feedback = run("node", [cli, "feedback", "--projects", repo, "--json"]);
1783
+ const collected = JSON.parse(feedback.stdout);
1784
+ assert(collected.projects[0]?.project === projectName, `feedback collection must use effective project.name: ${feedback.stdout}`);
1785
+ assert(collected.report_count === 1 && collected.metadata[0]?.project === projectName, "feedback metadata must retain the effective project identity");
1786
+ assert(!feedback.stdout.includes(secret), "feedback collection must never print access values loaded from the project overlay");
649
1787
  }
650
1788
 
651
1789
  function testManagedAgentModelsInheritAndOverridesSurvive() {
@@ -771,14 +1909,14 @@ function testBridgeIsGeneric() {
771
1909
  }
772
1910
  }
773
1911
 
774
- function testUpgradeCleansAllManagedSkillExtras() {
775
- const repo = tmpdir("upgrade-extra");
1912
+ function testSyncCleansAllManagedSkillExtras() {
1913
+ const repo = tmpdir("sync-extra");
776
1914
  run("git", ["init", "-q"], { cwd: repo });
777
1915
  run("node", [cli, "init", "--force"], { cwd: repo });
778
1916
  run("node", [cli, "sync", "--projects", repo]);
779
1917
  writeFile(path.join(repo, ".agents", "skills", "auto-coding-skill", "data", "templates", "bridges", "OLD.md"), "old\n");
780
1918
  writeFile(path.join(repo, ".agents", "skills", "auto-coding-skill", "custom.txt"), "custom\n");
781
- run("python3", [assetAp, "--repo", repo, "upgrade", "--write"]);
1919
+ run("node", [cli, "sync", "--projects", repo]);
782
1920
  assert(!exists(path.join(repo, ".agents", "skills", "auto-coding-skill", "data", "templates", "bridges", "OLD.md")), "managed bridge extra should be removed");
783
1921
  assert(!exists(path.join(repo, ".agents", "skills", "auto-coding-skill", "custom.txt")), "fully managed Skill extras should be removed");
784
1922
  }
@@ -858,9 +1996,43 @@ function testReviewScaffoldLeavesBaselineGenerationToBaselineCommand() {
858
1996
  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");
859
1997
  }
860
1998
 
861
- function testUpgradePrefersModernProjectAssetsAndIgnoresRetiredTemplates() {
862
- const repo = tmpdir("upgrade-modern-source");
863
- const fakeHome = tmpdir("upgrade-stale-home");
1999
+ function testBaselineUpdateConfigWritesOnlyProjectOverlay() {
2000
+ const repo = tmpdir("baseline-project-overlay-only");
2001
+ run("git", ["init", "-q"], { cwd: repo });
2002
+ run("node", [cli, "init"], { cwd: repo });
2003
+ run("git", ["config", "user.email", "test@example.com"], { cwd: repo });
2004
+ run("git", ["config", "user.name", "Auto Coding Test"], { cwd: repo });
2005
+ writeFile(path.join(repo, "src", "large-module.js"), "export const line = 1;\n".repeat(801));
2006
+ run("git", ["add", "-A"], { cwd: repo });
2007
+ run("git", ["commit", "-qm", "baseline source"], { cwd: repo });
2008
+
2009
+ const engineering = path.join(repo, "docs", "ENGINEERING.md");
2010
+ const overlay = projectConfigPath(repo);
2011
+ const engineeringBefore = fs.readFileSync(engineering);
2012
+ const overlayBefore = fs.readFileSync(overlay);
2013
+ const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
2014
+ const baseline = run("python3", [
2015
+ launcher,
2016
+ "--repo", repo,
2017
+ "baseline", "init",
2018
+ "--write",
2019
+ "--update-config",
2020
+ "--json",
2021
+ ]);
2022
+ const parsed = JSON.parse(baseline.stdout);
2023
+
2024
+ assert(parsed.updated_accepted_debt_paths.includes("src/large-module.js"), `baseline must discover the tracked large file: ${baseline.stdout}`);
2025
+ assert(fs.readFileSync(engineering).equals(engineeringBefore), "baseline --update-config must never modify managed ENGINEERING defaults");
2026
+ assert(!fs.readFileSync(overlay).equals(overlayBefore), "baseline --update-config must persist accepted debt in the project overlay");
2027
+ assert(readEffectiveConfig(repo).structure?.accepted_debt_paths?.includes("src/large-module.js"), "the overlay update must affect effective accepted_debt_paths");
2028
+ const changed = run("git", ["status", "--porcelain"], { cwd: repo }).stdout;
2029
+ assert(changed.includes("docs/project/auto-coding-skill.yaml"), `baseline must report the overlay as the changed configuration file: ${changed}`);
2030
+ assert(!changed.includes("docs/ENGINEERING.md"), `baseline must not report managed ENGINEERING as changed: ${changed}`);
2031
+ }
2032
+
2033
+ function testSyncUsesPackagedAssetsAndIgnoresRetiredTemplates() {
2034
+ const repo = tmpdir("sync-packaged-source");
2035
+ const fakeHome = tmpdir("sync-stale-home");
864
2036
  run("git", ["init", "-q"], { cwd: repo });
865
2037
  run("node", [cli, "init"], { cwd: repo });
866
2038
  run("node", [cli, "sync", "--projects", repo]);
@@ -873,44 +2045,37 @@ function testUpgradePrefersModernProjectAssetsAndIgnoresRetiredTemplates() {
873
2045
  writeFile(path.join(staleGlobal, "data", "templates", "ENGINEERING.md"), "---\n---\n");
874
2046
  writeFile(path.join(staleGlobal, "data", "templates", "docs", "interfaces", "api.md"), "# Retired global template\n");
875
2047
 
876
- const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
877
- const result = run(
878
- "python3",
879
- [launcher, "--repo", repo, "upgrade", "--write", "--json"],
880
- { env: pythonEnvWithHome(fakeHome) },
881
- );
882
- const parsed = JSON.parse(result.stdout);
883
- assert(fs.realpathSync(parsed.source_root) === fs.realpathSync(projectSkill), `upgrade should prefer the modern project asset root: ${result.stdout}`);
884
- assert(fs.readFileSync(path.join(repo, "docs", "interfaces", "api.md"), "utf8").startsWith("# API Contract"), "compatibility upgrade must not replace the canonical API doc with a retired physical template");
2048
+ run("node", [cli, "sync", "--projects", repo], { env: pythonEnvWithHome(fakeHome) });
2049
+ assert(!exists(path.join(projectSkill, "data", "templates", "docs", "interfaces", "api.md")), "transactional sync must replace retired files in the managed Skill namespace");
2050
+ assert(fs.readFileSync(path.join(repo, "docs", "interfaces", "api.md"), "utf8").startsWith("# API Contract"), "transactional sync must not replace the canonical API doc with a retired physical template");
885
2051
  }
886
2052
 
887
- function testUpgradeInitializesNewEngineeringDefaults() {
888
- const repo = tmpdir("upgrade-engineering-defaults");
889
- const fakeHome = tmpdir("upgrade-engineering-home");
2053
+ function testInitInitializesNewEngineeringDefaults() {
2054
+ const repo = tmpdir("init-engineering-defaults");
890
2055
  run("git", ["init", "-q"], { cwd: repo });
891
2056
  writeFile(path.join(repo, "package.json"), JSON.stringify({ scripts: { test: "node --test", "test:changed": "node --test" } }, null, 2) + "\n");
892
2057
  run("node", [cli, "init"], { cwd: repo });
893
2058
 
894
- const projectAp = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
895
- run("python3", [projectAp, "--repo", repo, "upgrade", "--write"], { env: pythonEnvWithHome(fakeHome) });
896
-
897
- const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
898
- assert(engineering.includes(`name: ${path.basename(repo)}`), "upgrade should initialize a newly created project name");
899
- assert(engineering.includes("project_fast: npm run test:changed"), "upgrade should infer only a dedicated changed-scope test");
900
- assert(!engineering.includes("gate_standard:"), "upgrade must not infer an automatic standard gate");
901
- assert(!engineering.includes("gate_full:"), "upgrade must not infer an automatic full gate");
2059
+ const effective = readEffectiveConfig(repo);
2060
+ assert(effective.project?.name === path.basename(repo), "init should initialize a newly created project name in the overlay");
2061
+ assert(effective.commands?.project_fast === "npm run test:changed", "init should infer only a dedicated changed-scope test in the overlay");
2062
+ assert(effective.commands?.gate_standard === undefined, "init must not infer an automatic standard gate");
2063
+ assert(effective.commands?.gate_full === undefined, "init must not infer an automatic full gate");
902
2064
  }
903
2065
 
904
- function testUpgradeMigratesLegacyAutomaticGateToFastDefault() {
905
- const repo = tmpdir("upgrade-legacy-fast-gate");
2066
+ function testInitMigratesLegacyAutomaticGateToFastDefault() {
2067
+ const repo = tmpdir("init-legacy-fast-gate");
906
2068
  run("git", ["init", "-q"], { cwd: repo });
907
2069
  writeFile(path.join(repo, "package.json"), JSON.stringify({ scripts: { test: "node --test" } }, null, 2) + "\n");
908
2070
  run("node", [cli, "init"], { cwd: repo });
909
- writeFile(path.join(repo, "docs", "ENGINEERING.md"), [
2071
+ fs.unlinkSync(projectConfigPath(repo));
2072
+ const legacyEngineering = [
910
2073
  "---",
911
2074
  "workflow:",
912
- " mode: verify",
2075
+ ' skill_version: "4.2.8"',
2076
+ " mode: dev",
913
2077
  " profile: auto",
2078
+ " completion: push",
914
2079
  "project:",
915
2080
  ' name: "legacy"',
916
2081
  "concurrency:",
@@ -930,16 +2095,25 @@ function testUpgradeMigratesLegacyAutomaticGateToFastDefault() {
930
2095
  "---",
931
2096
  "# Legacy engineering",
932
2097
  "",
933
- ].join("\n"));
2098
+ ].join("\n");
2099
+ writeFile(path.join(repo, "docs", "ENGINEERING.md"), legacyEngineering);
2100
+ const legacyInstalledDefault = legacyEngineering
2101
+ .replace(' name: "legacy"', ' name: ""')
2102
+ .replace(" base_ref: origin/dev", ' base_ref: ""')
2103
+ .replace(" target_branch: dev", ' target_branch: ""');
2104
+ installTrustedEngineeringDefault(repo, legacyInstalledDefault, "4.2.8");
934
2105
 
935
- run("python3", [assetAp, "--repo", repo, "upgrade", "--write"]);
936
- const engineering = fs.readFileSync(path.join(repo, "docs", "ENGINEERING.md"), "utf8");
937
- assert(/project_fast:\s*(?:''|"")/.test(engineering), "upgrade should not promote an ordinary npm test to the project-fast gate");
938
- assert(engineering.includes("mode: dev"), "upgrade should migrate verify mode to fast development mode");
939
- assert(engineering.includes("completion: push"), "upgrade should add push completion");
940
- assert(engineering.includes("isolation: adaptive"), "upgrade should migrate legacy isolation to adaptive");
941
- assert(engineering.includes("on_unmapped: error"), "upgrade should fail closed when changed code has no validation route");
942
- assert(engineering.includes("rules: []"), "upgrade should remove legacy automatic gate escalation rules");
2106
+ run("node", [cli, "init"], { cwd: repo });
2107
+ const managed = readEngineeringConfig(path.join(repo, "docs", "ENGINEERING.md"));
2108
+ const effective = readEffectiveConfig(repo);
2109
+ assert(effective.commands?.project_fast === "", "init should not promote an ordinary npm test to the project-fast gate");
2110
+ assert(managed.workflow?.mode === "dev", "init should retain the managed fast development mode");
2111
+ assert(managed.workflow?.completion === "push", "init should retain managed push completion");
2112
+ assert(managed.concurrency?.isolation === "adaptive", "init should retain managed adaptive isolation");
2113
+ assert(managed.validation?.on_unmapped === "error", "init should retain the fail-closed unmapped default");
2114
+ assert(managed.risk?.rules?.length === 0, "init should retain empty managed project-risk defaults");
2115
+ assert(effective.project?.name === "legacy" && effective.concurrency?.target_branch === "dev", "init must migrate supported legacy project values into the overlay");
2116
+ assert(effective.gate === undefined && effective.commands?.gate_full === undefined, "init must drop removed automatic gate escalation fields");
943
2117
  }
944
2118
 
945
2119
  function testRemovedVerificationFlagsFailFast() {
@@ -948,15 +2122,67 @@ function testRemovedVerificationFlagsFailFast() {
948
2122
  assert(result.status !== 0 && result.stderr.includes("unrecognized arguments"), "removed post-push verification flags must fail instead of being ignored");
949
2123
  }
950
2124
 
951
- function testUpgradeInstallsRuntimeRequiredByLauncher() {
952
- const repo = tmpdir("upgrade-missing-runtime");
2125
+ function testInstallBootstrapsRuntimeRequiredByLauncher() {
2126
+ const repo = tmpdir("install-missing-runtime");
2127
+ const fakeHome = tmpdir("install-global-runtime-home");
2128
+ const env = pythonEnvWithHome(fakeHome);
953
2129
  run("git", ["init", "-q"], { cwd: repo });
954
- run("python3", [assetAp, "--repo", repo, "upgrade", "--write"]);
2130
+ run("node", [cli, "init", "--mode", "global", "--dest", fakeHome, "--force"]);
2131
+ const globalAp = path.join(fakeHome, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
2132
+ run("python3", [globalAp, "--repo", repo, "install"], { env });
955
2133
  const projectRuntime = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
956
2134
  const launcher = path.join(repo, "docs", "tools", "autopipeline", "ap.py");
957
- assert(exists(projectRuntime), "upgrade should install the runtime required by the new launcher");
958
- const help = run("python3", [launcher, "--help"]);
959
- assert(help.stdout.includes("autopipeline"), "upgraded launcher should remain executable");
2135
+ assert(!exists(projectRuntime), "runtime bootstrap install must continue to rely on the invoking global Skill copy");
2136
+ assert(readYamlConfig(projectConfigPath(repo)).overrides?.project?.name === path.basename(repo), "bootstrap install must initialize the project overlay");
2137
+ const help = run("python3", [launcher, "--help"], { env });
2138
+ assert(help.stdout.includes("autopipeline"), "bootstrapped launcher should remain executable through the invoking runtime");
2139
+ }
2140
+
2141
+ function testCliInstallArchivesFeedbackTemplatesAndPreservesReports() {
2142
+ const repo = tmpdir("cli-feedback-ownership");
2143
+ run("git", ["init", "-q"], { cwd: repo });
2144
+ const feedbackReadme = path.join(repo, "docs", "skill-feedback", "README.md");
2145
+ const report = path.join(repo, "docs", "skill-feedback", "reports", "2026-07-18-upgrade-gap-a13f82c1.md");
2146
+ const previousReadme = "project content that occupied the future managed feedback README\n";
2147
+ const reportContent = "project-owned feedback report bytes\n";
2148
+ writeFile(feedbackReadme, previousReadme);
2149
+ writeFile(report, reportContent);
2150
+
2151
+ run("node", [cli, "init"], { cwd: repo });
2152
+ const archive = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs", "skill-feedback", "README.md");
2153
+ assert(fs.readFileSync(feedbackReadme, "utf8").includes("Auto Coding Skill Feedback"), "transactional init must install the managed feedback README");
2154
+ assert(fs.readFileSync(archive, "utf8") === previousReadme, "transactional init must archive a pre-existing feedback README before replacement");
2155
+ assert(fs.readFileSync(report, "utf8") === reportContent, "transactional init must preserve project feedback reports byte-for-byte");
2156
+
2157
+ const archiveBefore = fs.readFileSync(archive);
2158
+ run("node", [cli, "sync", "--projects", repo]);
2159
+ assert(fs.readFileSync(archive).equals(archiveBefore), "repeated transactional sync must keep the original feedback archive stable");
2160
+ assert(fs.readFileSync(report, "utf8") === reportContent, "repeated transactional sync must keep project feedback reports stable");
2161
+ }
2162
+
2163
+ function testLegacyUpgradeWriteFailsWithoutAnyWrites() {
2164
+ const repo = tmpdir("legacy-upgrade-write-rejected");
2165
+ run("git", ["init", "-q"], { cwd: repo });
2166
+ run("node", [cli, "init"], { cwd: repo });
2167
+ const skill = path.join(repo, ".agents", "skills", "auto-coding-skill", "SKILL.md");
2168
+ writeFile(skill, "legacy-upgrade-zero-write-sentinel\n");
2169
+ const beforeFiles = listProjectFiles(repo)
2170
+ .map(file => [path.relative(repo, file), fs.readFileSync(file)])
2171
+ .sort(([left], [right]) => left.localeCompare(right));
2172
+ const projectAp = path.join(repo, ".agents", "skills", "auto-coding-skill", "scripts", "ap.py");
2173
+
2174
+ const rejected = run("python3", [projectAp, "--repo", repo, "upgrade", "--write"], { check: false });
2175
+ const output = `${rejected.stdout}\n${rejected.stderr}`;
2176
+ assert(rejected.status !== 0, "legacy ap.py upgrade --write must be rejected");
2177
+ assert(output.includes("retired") && output.includes("autocoding init") && output.includes("autocoding sync"), `legacy write rejection must direct callers to the transactional CLI: ${output}`);
2178
+ const afterFiles = listProjectFiles(repo)
2179
+ .map(file => [path.relative(repo, file), fs.readFileSync(file)])
2180
+ .sort(([left], [right]) => left.localeCompare(right));
2181
+ assert(afterFiles.length === beforeFiles.length, "rejected legacy write must not create or delete project files");
2182
+ for (let index = 0; index < beforeFiles.length; index += 1) {
2183
+ assert(afterFiles[index][0] === beforeFiles[index][0], `rejected legacy write must preserve the file set: ${beforeFiles[index][0]}`);
2184
+ assert(afterFiles[index][1].equals(beforeFiles[index][1]), `rejected legacy write must preserve bytes: ${beforeFiles[index][0]}`);
2185
+ }
960
2186
  }
961
2187
 
962
2188
  function testLedgerArchiveRecognizesSettledStatuses() {
@@ -1018,7 +2244,7 @@ function testManagedEngineeringInitIsAuthoritativeAndIdempotent() {
1018
2244
 
1019
2245
  const engineering = path.join(repo, "docs", "ENGINEERING.md");
1020
2246
  const initial = fs.readFileSync(engineering, "utf8");
1021
- const startPattern = /<!-- auto-coding-skill:managed-workflow:start version=4\.2\.8 -->/;
2247
+ const startPattern = /<!-- auto-coding-skill:managed-workflow:start version=4\.3\.0 -->/;
1022
2248
  const endMarker = "<!-- auto-coding-skill:managed-workflow:end -->";
1023
2249
  assert(startPattern.test(initial), "new projects should include a versioned managed workflow marker");
1024
2250
  assert(initial.includes(endMarker), "new projects should include the managed workflow end marker");
@@ -1032,21 +2258,21 @@ function testManagedEngineeringInitIsAuthoritativeAndIdempotent() {
1032
2258
  const dryRun = run("node", [cli, "sync", "--projects", repo, "--dry-run", "--json"]);
1033
2259
  const dryResult = JSON.parse(dryRun.stdout).results[0];
1034
2260
  assert(dryResult.managedWorkflow.state === "stale", `dry-run should expose stale workflow state: ${dryRun.stdout}`);
1035
- assert(dryResult.managedWorkflow.version === "4.2.8", "dry-run should expose the target workflow version");
1036
- assert(dryResult.actions.some(item => item.action === "would-update" && item.path === "docs/ENGINEERING.md"), "dry-run should plan the managed body update");
2261
+ assert(dryResult.managedWorkflow.version === "4.3.0", "dry-run should expose the target workflow version");
2262
+ assert(dryResult.actions.some(item => item.action === "would-replace" && item.path === "docs/ENGINEERING.md"), "dry-run should plan exact replacement of the managed default document");
1037
2263
  assert(fs.readFileSync(engineering, "utf8") === customized, "dry-run must not write ENGINEERING.md");
1038
2264
 
1039
2265
  run("node", [cli, "init"], { cwd: repo });
1040
2266
  const updated = fs.readFileSync(engineering, "utf8");
1041
2267
  assert(!updated.includes("project note before") && !updated.includes("project note after"), "init must remove text outside the canonical ENGINEERING body");
1042
- assert(updated.includes("version=4.2.8"), "init should install the current managed workflow version");
2268
+ assert(updated.includes("version=4.3.0"), "init should install the current managed workflow version");
1043
2269
  assert(updated.includes("The frontmatter contract is:"), "init should refresh stale managed workflow content");
1044
2270
 
1045
2271
  fillRequiredAccess(repo);
1046
2272
  const status = run("node", [cli, "status", "--projects", repo, "--json"]);
1047
2273
  const statusResult = JSON.parse(status.stdout).results[0];
1048
2274
  assert(statusResult.managedWorkflow.state === "current", `status should expose current managed workflow state: ${status.stdout}`);
1049
- assert(statusResult.managedWorkflow.version === "4.2.8", "status should expose the installed managed workflow version");
2275
+ assert(statusResult.managedWorkflow.version === "4.3.0", "status should expose the installed managed workflow version");
1050
2276
 
1051
2277
  const beforeSecondInit = fs.readFileSync(engineering, "utf8");
1052
2278
  run("node", [cli, "init"], { cwd: repo });
@@ -1070,11 +2296,14 @@ function testLegacyEngineeringMigrationPreservesExistingBody() {
1070
2296
  const dryResult = JSON.parse(dryRun.stdout).results[0];
1071
2297
  assert(dryResult.managedWorkflow.state === "legacy-custom", "unknown unmarked documents should be reported as a custom legacy migration");
1072
2298
  assert(dryResult.managedWorkflow.preservedCustom === true, "custom legacy migration should expose its preservation policy");
1073
- assert(dryResult.actions.find(item => item.path === "docs/ENGINEERING.md")?.detail.includes("preserved-custom"), "custom legacy action should be labeled preserved-custom");
2299
+ assert(dryResult.actions.some(item => item.action === "would-replace" && item.path === "docs/ENGINEERING.md"), "custom legacy migration must plan exact managed replacement");
2300
+ assert(dryResult.actions.some(item => item.action === "would-archive" && item.path.endsWith("/docs/ENGINEERING.md")), "custom legacy migration must plan archival before replacement");
1074
2301
  run("node", [cli, "sync", "--projects", repo]);
1075
2302
  const migrated = fs.readFileSync(engineering, "utf8");
1076
- assert(migrated.includes("version=4.2.8"), "legacy migration should insert the current managed workflow");
1077
- assert(migrated.includes(legacyNote), "legacy migration must preserve the complete existing body");
2303
+ assert(migrated.includes("version=4.3.0"), "legacy migration should insert the current managed workflow");
2304
+ assert(!migrated.includes(legacyNote), "legacy project text must not remain in the exact managed default document");
2305
+ const archive = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs", "ENGINEERING.md");
2306
+ assert(fs.readFileSync(archive, "utf8").includes(legacyNote), "legacy migration must preserve the complete previous body in history");
1078
2307
  const stable = fs.readFileSync(engineering, "utf8");
1079
2308
  run("node", [cli, "sync", "--projects", repo]);
1080
2309
  assert(fs.readFileSync(engineering, "utf8") === stable, "legacy migration should converge after one sync");
@@ -1094,12 +2323,15 @@ function testOfficialLegacyEngineeringBodyIsReplacedWithoutDuplication() {
1094
2323
  const dryRun = run("node", [cli, "sync", "--projects", repo, "--dry-run", "--json"]);
1095
2324
  const dryResult = JSON.parse(dryRun.stdout).results[0];
1096
2325
  assert(dryResult.managedWorkflow.state === "legacy-official", `official body hash should select replacement migration: ${dryRun.stdout}`);
1097
- assert(dryResult.actions.find(item => item.path === "docs/ENGINEERING.md")?.detail.includes("official-legacy"), "official legacy action should identify replacement migration");
2326
+ assert(dryResult.actions.some(item => item.action === "would-replace" && item.path === "docs/ENGINEERING.md"), "official legacy migration must plan exact managed replacement");
1098
2327
  run("node", [cli, "sync", "--projects", repo]);
1099
2328
  const migrated = fs.readFileSync(engineering, "utf8");
1100
- assert(migrated.startsWith(customizedFrontmatter), "official legacy migration must preserve YAML frontmatter byte-for-byte");
2329
+ const canonicalEngineering = fs.readFileSync(path.join(repoRoot, "cli", "assets", "skill", "data", "templates", "ENGINEERING.md"), "utf8");
2330
+ assert(migrated === canonicalEngineering, "official legacy migration must install the exact managed default document");
1101
2331
  assert((migrated.match(/auto-coding-skill:managed-workflow:start/g) || []).length === 1, "official legacy migration should install exactly one managed workflow");
1102
- assert((migrated.match(/^## Delivery levels$/gm) || []).length === 0, "official legacy migration must remove the old duplicated workflow body");
2332
+ assert((migrated.match(/^## Execution profiles$/gm) || []).length === 0, "official legacy migration must remove the old duplicated workflow body");
2333
+ const archive = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs", "ENGINEERING.md");
2334
+ assert(fs.readFileSync(archive, "utf8").includes("## Execution profiles"), "official legacy body must remain available in the historical archive");
1103
2335
 
1104
2336
  const stable = fs.readFileSync(engineering, "utf8");
1105
2337
  run("node", [cli, "sync", "--projects", repo]);
@@ -1173,7 +2405,7 @@ function testManagedAgentsMigrationReplacesWholeFileAndArchivesPreviousRules() {
1173
2405
  run("node", [cli, "sync", "--projects", repo]);
1174
2406
  const agents = path.join(repo, "AGENTS.md");
1175
2407
  const initial = fs.readFileSync(agents, "utf8");
1176
- assert(initial.includes("managed-agents:start version=4.2.8"), "new projects should receive the versioned root AGENTS block");
2408
+ assert(initial.includes("managed-agents:start version=4.3.0"), "new projects should receive the versioned root AGENTS block");
1177
2409
 
1178
2410
  const custom = [
1179
2411
  "# Project rules",
@@ -1192,12 +2424,12 @@ function testManagedAgentsMigrationReplacesWholeFileAndArchivesPreviousRules() {
1192
2424
 
1193
2425
  run("node", [cli, "sync", "--projects", repo]);
1194
2426
  const migrated = fs.readFileSync(agents, "utf8");
1195
- assert(migrated.includes("managed-agents:start version=4.2.8"), "AGENTS migration should install the current managed block");
2427
+ assert(migrated.includes("managed-agents:start version=4.3.0"), "AGENTS migration should install the current managed block");
1196
2428
  assert(!migrated.includes("Preserve this repository-specific rule exactly."), "root AGENTS must contain no project-specific tail");
1197
2429
  assert(!migrated.includes("must execute `commands.gate_full`"), "known official conflicting rule should be removed");
1198
2430
  const canonical = fs.readFileSync(path.join(repoRoot, "cli", "assets", "skill", "data", "templates", "bridges", "AGENTS.md"), "utf8");
1199
2431
  assert(migrated === canonical, "root AGENTS must be byte-identical to the packaged canonical file");
1200
- const archive = path.join(repo, "docs", "archive", "workflow", "AGENTS.pre-4.2.8.md");
2432
+ const archive = path.join(repo, "docs", "archive", "workflow", "AGENTS.pre-4.3.0.md");
1201
2433
  assert(fs.readFileSync(archive, "utf8").includes("Preserve this repository-specific rule exactly."), "previous AGENTS content must be archived once");
1202
2434
  const stable = fs.readFileSync(agents);
1203
2435
  run("node", [cli, "sync", "--projects", repo]);
@@ -1215,16 +2447,25 @@ function testUnknownWorkflowConflictFailsWholeBatchBeforeWrites() {
1215
2447
  const firstSkill = path.join(first, ".agents", "skills", "auto-coding-skill", "SKILL.md");
1216
2448
  writeFile(firstSkill, "batch-sentinel\n");
1217
2449
  const secondEngineering = path.join(second, "docs", "ENGINEERING.md");
1218
- fs.appendFileSync(secondEngineering, "\nHigh-risk changes must run the real full gate before push.\n");
2450
+ const secret = "UNIQUE_POLICY_BEARER_SECRET_4d920f7a";
2451
+ fs.appendFileSync(secondEngineering, `\nHigh-risk changes must run the real full gate before push. Authorization: Bearer ${secret}\n`);
1219
2452
 
1220
2453
  const status = run("node", [cli, "status", "--projects", second, "--json"], { check: false });
1221
2454
  assert(status.status !== 0, "status must be non-ok for an unknown conflicting workflow rule");
2455
+ assert(!`${status.stdout}\n${status.stderr}`.includes(secret), `status must redact Bearer values from policy-conflict excerpts: ${status.stdout}\n${status.stderr}`);
1222
2456
  const statusPlan = JSON.parse(status.stdout).results[0].managedWorkflow;
1223
2457
  assert(statusPlan.state === "conflict", `status should expose the document conflict: ${status.stdout}`);
1224
2458
  assert(statusPlan.conflicts[0].file === "docs/ENGINEERING.md" && statusPlan.conflicts[0].line > 0, "status conflict should include file and line");
1225
2459
 
2460
+ const launcher = path.join(second, "docs", "tools", "autopipeline", "ap.py");
2461
+ const effective = run("python3", [launcher, "--repo", second, "config-effective", "--json"]);
2462
+ assert(!`${effective.stdout}\n${effective.stderr}`.includes(secret), `config-effective must redact Bearer values from policy conflicts: ${effective.stdout}\n${effective.stderr}`);
2463
+ const effectiveStatus = JSON.parse(effective.stdout);
2464
+ assert(effectiveStatus.contract_valid === false && effectiveStatus.policy_issues.length > 0, `config-effective must retain redacted conflict diagnostics: ${effective.stdout}`);
2465
+
1226
2466
  const sync = run("node", [cli, "sync", "--projects", `${first},${second}`], { check: false });
1227
2467
  assert(sync.status !== 0 && sync.stderr.includes("entire sync batch before writes"), "one unknown conflict must reject the complete batch");
2468
+ assert(!`${sync.stdout}\n${sync.stderr}`.includes(secret), `sync preflight must redact Bearer values from conflict diagnostics: ${sync.stdout}\n${sync.stderr}`);
1228
2469
  assert(fs.readFileSync(firstSkill, "utf8") === "batch-sentinel\n", "batch conflict preflight must run before an earlier project's skill write");
1229
2470
  }
1230
2471
 
@@ -1238,7 +2479,10 @@ function testEngineeringMarkerBoundaryIsNormalized() {
1238
2479
  writeFile(engineering, current.replace(`${marker}\n`, `${marker}# Project-specific workflow\n`));
1239
2480
  run("node", [cli, "sync", "--projects", repo]);
1240
2481
  const normalized = fs.readFileSync(engineering, "utf8");
1241
- assert(normalized.includes(`${marker}\n# Project-specific workflow\n`), "sync should normalize a heading glued to the managed end marker");
2482
+ assert(normalized === current, "sync should restore the exact managed document when text is glued to its end marker");
2483
+ assert(!normalized.includes("# Project-specific workflow"), "project workflow text must not remain in the managed default document");
2484
+ const archive = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs", "ENGINEERING.md");
2485
+ assert(fs.readFileSync(archive, "utf8").includes(`${marker}# Project-specific workflow`), "the malformed previous document must remain available in history");
1242
2486
  }
1243
2487
 
1244
2488
  function testEngineeringFrameworkRejectsAnyNonCanonicalWorkflowText() {
@@ -1254,7 +2498,7 @@ function testEngineeringFrameworkRejectsAnyNonCanonicalWorkflowText() {
1254
2498
 
1255
2499
  run("node", [cli, "init"], { cwd: repo });
1256
2500
  assert(!fs.readFileSync(engineering, "utf8").includes("backend owns APIs"), "init must restore the canonical ENGINEERING body");
1257
- const archived = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.2.8", "docs", "ENGINEERING.md");
2501
+ const archived = path.join(repo, ".agents", "archive", "auto-coding-skill", "4.3.0", "docs", "ENGINEERING.md");
1258
2502
  assert(fs.readFileSync(archived, "utf8").includes("backend owns APIs"), "removed project text should remain in non-authoritative history");
1259
2503
  }
1260
2504
 
@@ -1266,12 +2510,12 @@ function testManagedInstallIntegrityIsBoundedAndRepairable() {
1266
2510
 
1267
2511
  const manifestPath = path.join(repo, ".agents", "managed-install.json");
1268
2512
  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
1269
- assert(manifest.schema_version === 1 && manifest.skill_version === "4.2.8", "installed manifest must identify the release");
2513
+ assert(manifest.schema_version === 1 && manifest.skill_version === "4.3.0", "installed manifest must identify the release");
1270
2514
  assert(manifest.entries.length > 0, "installed manifest must list managed files");
1271
2515
  for (const entry of manifest.entries) {
1272
2516
  assert(typeof entry.path === "string" && !path.isAbsolute(entry.path) && !entry.path.includes(".."), "manifest paths must be safe relative paths");
1273
2517
  assert(/^[0-9a-f]{64}$/.test(entry.sha256), `${entry.path}: manifest hash must be sha256`);
1274
- assert(entry.version === "4.2.8" && typeof entry.executable === "boolean", `${entry.path}: version/executable metadata missing`);
2518
+ assert(entry.version === "4.3.0" && typeof entry.executable === "boolean", `${entry.path}: version/executable metadata missing`);
1275
2519
  }
1276
2520
  assert(!manifest.managed_namespaces.some(item => item.path === ".agents" || item.path === "docs"), "manifest must not mirror entire project-owned trees");
1277
2521
 
@@ -1340,22 +2584,149 @@ function testManagedInstallIntegrityIsBoundedAndRepairable() {
1340
2584
  assertStatusOk(repo);
1341
2585
  }
1342
2586
 
2587
+ function testSkillFeedbackCollectionIsBoundedReadOnlyAndMetadataOnly() {
2588
+ const first = tmpdir("feedback-collect-first");
2589
+ const second = tmpdir("feedback-collect-second");
2590
+ const third = tmpdir("feedback-collect-empty");
2591
+ run("node", [cli, "init"], { cwd: first });
2592
+ run("node", [cli, "init"], { cwd: second });
2593
+ run("node", [cli, "init"], { cwd: third });
2594
+ const signature = `sha256:${"a".repeat(64)}`;
2595
+ const marker = path.join(os.tmpdir(), `autocoding-feedback-must-not-execute-${crypto.randomUUID()}`);
2596
+ const render = (project, reportId, privateMarker) => [
2597
+ "---",
2598
+ "schema: auto-coding-skill-feedback/v1",
2599
+ `report_id: ${reportId}`,
2600
+ "status: open",
2601
+ 'created_at: "2026-07-18T10:00:00+08:00"',
2602
+ `project: ${project}`,
2603
+ "observed_skill_version: 4.2.8",
2604
+ "component: reviewer-runtime",
2605
+ "kind: defect",
2606
+ "impact: blocking",
2607
+ "origin_surface: managed-script",
2608
+ "suspected_scope: shared",
2609
+ `signature: ${signature}`,
2610
+ "export: metadata-only",
2611
+ "---",
2612
+ "# Reviewer runtime stalls",
2613
+ "",
2614
+ "## Symptom",
2615
+ `${privateMarker}; $(touch ${marker})`,
2616
+ "",
2617
+ "## Expected",
2618
+ "The managed runtime must return before its deadline.",
2619
+ "",
2620
+ "## Minimal reproduction",
2621
+ "Use a synthetic read-only assignment.",
2622
+ "",
2623
+ "## Evidence",
2624
+ "The bounded local fixture reproduced the timeout.",
2625
+ "",
2626
+ "## Workaround",
2627
+ "Use the explicit runtime override only with user authorization.",
2628
+ "",
2629
+ "## Why shared",
2630
+ "Managed runtime behavior reproduces outside project configuration.",
2631
+ "",
2632
+ ].join("\n");
2633
+ const firstReport = path.join(first, "docs", "skill-feedback", "reports", "2026-07-18-review-timeout-a13f82c1.md");
2634
+ const firstOtherReport = path.join(first, "docs", "skill-feedback", "reports", "2026-07-18-installer-gap-c35fa4e3.md");
2635
+ const secondReport = path.join(second, "docs", "skill-feedback", "reports", "2026-07-18-review-timeout-b24f93d2.md");
2636
+ const firstContent = render(path.basename(first), "ACSF-geesight-20260718-a13f82c1", "PRIVATE-BODY-FIRST");
2637
+ const firstOtherContent = render(path.basename(first), "ACSF-geesight-20260718-c35fa4e3", "PRIVATE-BODY-OTHER")
2638
+ .replaceAll(signature, `sha256:${"b".repeat(64)}`);
2639
+ const secondContent = render(path.basename(second), "ACSF-xjmate-20260718-b24f93d2", "PRIVATE-BODY-SECOND");
2640
+ writeFile(firstReport, firstContent);
2641
+ writeFile(firstOtherReport, firstOtherContent);
2642
+ writeFile(secondReport, secondContent);
2643
+
2644
+ const collected = run("node", [cli, "feedback", "--projects", `${first},${second},${third}`, "--json"]);
2645
+ const result = JSON.parse(collected.stdout);
2646
+ assert(result.schema === "auto-coding-skill-feedback-collection/v1", "feedback collection must identify its schema");
2647
+ assert(result.report_count === 3 && result.groups.length === 2, "feedback collection must preserve multiple exact-signature groups");
2648
+ assert(result.projects.length === 3 && result.projects.every(item => item.source_project && item.project), "feedback collection must retain every explicit initialized project, including one with no reports");
2649
+ const sharedGroup = result.groups.find(item => item.signature === signature);
2650
+ assert(sharedGroup?.cross_project === true && sharedGroup.project_count === 2, "same signature from two explicit roots must be cross-project");
2651
+ const localGroup = result.groups.find(item => item.signature === `sha256:${"b".repeat(64)}`);
2652
+ assert(localGroup?.cross_project === false && localGroup.project_count === 1, "a separate one-project signature must remain a local candidate group");
2653
+ const rawReportDigests = [firstContent, firstOtherContent, secondContent]
2654
+ .map(content => crypto.createHash("sha256").update(content).digest("hex"));
2655
+ assert(result.metadata.every(item => !("content_sha256" in item) && item.size_bytes > 0), "feedback metadata must not export a hash oracle over private report bodies");
2656
+ assert(rawReportDigests.every(digest => !collected.stdout.includes(digest)), "collector output must not expose raw report body digests");
2657
+ assert(!collected.stdout.includes("PRIVATE-BODY") && !collected.stdout.includes("touch"), "collector output must never include report bodies");
2658
+ assert(!collected.stdout.includes(first) && !collected.stdout.includes(second) && !collected.stdout.includes(third), "collector output must not expose absolute project roots");
2659
+ assert(!exists(marker), "collector must never execute report content");
2660
+ assert(fs.readFileSync(firstReport, "utf8") === firstContent && fs.readFileSync(firstOtherReport, "utf8") === firstOtherContent && fs.readFileSync(secondReport, "utf8") === secondContent, "collection must not modify reports");
2661
+
2662
+ writeFile(secondReport, render("spoofed-project", "ACSF-xjmate-20260718-b24f93d2", "PRIVATE-BODY-SECOND"));
2663
+ const spoofed = run("node", [cli, "feedback", "--projects", second, "--json"], { check: false });
2664
+ assert(spoofed.status !== 0 && spoofed.stderr.includes("project must equal") && spoofed.stderr.includes("project.name"), "collector must bind report project identity to effective project configuration");
2665
+ writeFile(secondReport, secondContent);
2666
+
2667
+ const secondOverlay = projectConfigPath(second);
2668
+ const secondOverlayContent = fs.readFileSync(secondOverlay);
2669
+ const secondOverrides = readYamlConfig(secondOverlay).overrides;
2670
+ writeProjectConfig(second, {
2671
+ ...secondOverrides,
2672
+ project: { ...(secondOverrides.project ?? {}), name: path.basename(first) },
2673
+ });
2674
+ writeFile(secondReport, render(path.basename(first), "ACSF-xjmate-20260718-b24f93d2", "PRIVATE-BODY-SECOND"));
2675
+ const duplicateIdentity = run("node", [cli, "feedback", "--projects", `${first},${second}`, "--json"], { check: false });
2676
+ assert(duplicateIdentity.status !== 0 && duplicateIdentity.stderr.includes("distinct") && duplicateIdentity.stderr.includes("project.name"), "collector must not count two roots declaring one effective project identity as cross-project evidence");
2677
+ fs.writeFileSync(secondOverlay, secondOverlayContent);
2678
+ writeFile(secondReport, secondContent);
2679
+
2680
+ const firstOverlay = projectConfigPath(first);
2681
+ const firstOverlayContent = fs.readFileSync(firstOverlay);
2682
+ fs.writeFileSync(firstOverlay, Buffer.alloc(128 * 1024 + 1, "a"));
2683
+ const oversizedConfig = run("node", [cli, "feedback", "--projects", first, "--json"], { check: false });
2684
+ assert(oversizedConfig.status !== 0 && oversizedConfig.stderr.includes("size limit"), "collector must bound project overlay reads");
2685
+ fs.writeFileSync(firstOverlay, firstOverlayContent);
2686
+
2687
+ const implicit = run("node", [cli, "feedback", first, "--json"], { check: false });
2688
+ assert(implicit.status !== 0 && implicit.stderr.includes("requires explicit --projects"), "feedback collection must reject implicit or positional project scope");
2689
+
2690
+ if (process.platform !== "win32") {
2691
+ const linked = path.join(first, "docs", "skill-feedback", "reports", "2026-07-18-linked-report-deadbeef.md");
2692
+ fs.symlinkSync(secondReport, linked);
2693
+ const unsafe = run("node", [cli, "feedback", "--projects", first, "--json"], { check: false });
2694
+ assert(unsafe.status !== 0 && unsafe.stderr.includes("regular non-symlink file"), "collector must reject feedback symlinks without following them");
2695
+
2696
+ fs.rmSync(path.join(first, "docs", "skill-feedback"), { recursive: true, force: true });
2697
+ const externalFeedback = tmpdir("feedback-collector-parent-external");
2698
+ fs.mkdirSync(path.join(externalFeedback, "reports"), { recursive: true });
2699
+ writeFile(path.join(externalFeedback, "reports", path.basename(firstReport)), firstContent);
2700
+ fs.symlinkSync(externalFeedback, path.join(first, "docs", "skill-feedback"));
2701
+ const unsafeParent = run("node", [cli, "feedback", "--projects", first, "--json"], { check: false });
2702
+ assert(unsafeParent.status !== 0 && unsafeParent.stderr.includes("real directory"), "collector must reject a symlink in the feedback parent chain");
2703
+ }
2704
+ }
2705
+
1343
2706
  function testReleaseVersionMarkersStayInSync() {
1344
- const expected = "4.2.8";
2707
+ const expected = "4.3.0";
1345
2708
  const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
1346
2709
  const lock = JSON.parse(fs.readFileSync(path.join(repoRoot, "package-lock.json"), "utf8"));
1347
2710
  const policy = JSON.parse(fs.readFileSync(
1348
2711
  path.join(repoRoot, "src", "auto-coding-skill", "data", "policies", "workflow-migrations-v1.json"),
1349
2712
  "utf8",
1350
2713
  ));
1351
- assert(pkg.version === expected, "package version must match the 4.2.8 release");
2714
+ assert(pkg.version === expected, "package version must match the 4.3.0 release");
1352
2715
  assert(lock.version === expected && lock.packages[""].version === expected, "package-lock versions must match");
1353
2716
  assert(policy.managed_versions.engineering === expected && policy.managed_versions.agents === expected, "managed workflow versions must match");
1354
2717
  const manifest = JSON.parse(fs.readFileSync(path.join(repoRoot, "cli", "assets", "managed-install.json"), "utf8"));
1355
2718
  assert(manifest.skill_version === expected && manifest.schema_version === 1, "managed install manifest version/schema must match");
1356
2719
  assert(manifest.entries.every(entry => entry.version === expected && /^[0-9a-f]{64}$/.test(entry.sha256)), "managed install entries must carry release hashes and versions");
2720
+ assert(manifest.entries.find(entry => entry.path === "docs/ENGINEERING.md")?.ownership === "exact", "managed ENGINEERING must be installed as an exact default layer");
1357
2721
  assert(!manifest.entries.some(entry => entry.path === "docs/architecture/structure-standard.md"), "project structure standard must not be exact-managed");
1358
2722
  assert(manifest.preserved.includes("docs/architecture/structure-standard.md"), "manifest must declare the project structure standard preserved");
2723
+ assert(manifest.entries.some(entry => entry.path === "docs/skill-feedback/README.md"), "feedback README must be exact-managed");
2724
+ assert(manifest.entries.some(entry => entry.path === "docs/skill-feedback/_TEMPLATE-SKILL-FEEDBACK.md"), "feedback template must be exact-managed");
2725
+ assert(manifest.preserved.includes("docs/skill-feedback/reports/*.md"), "manifest must declare project feedback reports preserved");
2726
+ assert(!manifest.managed_namespaces.some(item => item.path === "docs/skill-feedback"), "project feedback reports must stay outside managed namespaces");
2727
+ assert(manifest.preserved.includes("docs/project/auto-coding-skill.yaml"), "manifest must declare the project configuration overlay preserved");
2728
+ assert(!manifest.entries.some(entry => entry.path === "docs/project/auto-coding-skill.yaml"), "project configuration overlay must never be exact-managed");
2729
+ assert(!manifest.managed_namespaces.some(item => item.path === "docs/project"), "project configuration overlay must stay outside managed namespaces");
1359
2730
  const publishWorkflow = fs.readFileSync(path.join(repoRoot, ".github", "workflows", "npm-publish.yml"), "utf8");
1360
2731
  const runtimeRequirements = fs.readFileSync(path.join(repoRoot, "src", "auto-coding-skill", "requirements.txt"), "utf8");
1361
2732
  assert(publishWorkflow.includes("tags:\n - \"v*\""), "npm publish must run from version tag pushes");
@@ -1380,11 +2751,14 @@ function testProtocolResponsibilitiesStaySeparated() {
1380
2751
  const agents = fs.readFileSync(path.join(repoRoot, "src", "auto-coding-skill", "data", "templates", "bridges", "AGENTS.md"), "utf8");
1381
2752
  const engineering = fs.readFileSync(path.join(repoRoot, "src", "auto-coding-skill", "data", "templates", "ENGINEERING.md"), "utf8");
1382
2753
  const totalLines = [skill, agents, engineering].reduce((sum, text) => sum + text.split(/\r?\n/).length, 0);
1383
- assert(totalLines <= 360, `shared protocol context budget exceeded: ${totalLines} lines`);
2754
+ // The project-overlay ownership boundary adds a small, measured protocol
2755
+ // contract without adding another workflow document.
2756
+ assert(totalLines <= 370, `shared protocol context budget exceeded: ${totalLines} lines`);
1384
2757
  assert(agents.includes("## Minimum mechanism budget") && agents.includes("## Bounded real validation"), "AGENTS must remain the behavioral protocol");
1385
2758
  assert(skill.includes("## Select the minimum mechanism set") && !skill.includes("## Authority"), "SKILL must remain invocation guidance");
1386
2759
  assert(engineering.includes("The frontmatter contract is:") && !engineering.includes("## Git and parallel work"), "ENGINEERING must remain project configuration/facts");
1387
- assert(engineering.includes("frontmatter values are authoritative"), "ENGINEERING policy summary must defer to project frontmatter");
2760
+ assert(engineering.includes("docs/project/auto-coding-skill.yaml") && engineering.includes("project overlay"), "ENGINEERING must direct project specialization to the preserved overlay");
2761
+ assert(engineering.includes("owns this document byte-for-byte"), "ENGINEERING must identify itself as the managed default layer");
1388
2762
  assert(!engineering.includes("advisory architecture and no-new-debt policy"), "ENGINEERING policy summary must not hard-code template defaults");
1389
2763
  }
1390
2764
 
@@ -1395,27 +2769,49 @@ testInitRejectsMissingPythonRuntimeBeforeWrites();
1395
2769
  testDestVariants();
1396
2770
  testLauncherFallsBackToGlobalRuntime();
1397
2771
  testMinimalInitConvergesWithinBudget();
2772
+ testSkillFeedbackTemplatesAndReportsSurviveSync();
1398
2773
  testStatusRejectsLegacyIsolation();
1399
2774
  testStatusRejectsLegacyGateEscalation();
1400
2775
  testStatusAcceptsValidIndentlessYamlRoutes();
1401
2776
  testOrdinaryNodeTestIsNotPromotedToAutomaticGate();
1402
2777
  testAccessPasswordsAreRequiredButNeverPrintedByStatus();
2778
+ testProjectConfigOverlayMigratesLegacyEngineeringAndStaysByteStable();
2779
+ testProjectConfigOverlayMergeKeepsExplicitFalseZeroEmptyAndList();
2780
+ testOversizedLegacyMigrationFailsBeforeCreatingAnInvalidOverlay();
2781
+ testInvalidProjectConfigOverlayFailsBeforeAnyWrites();
2782
+ testStatusRejectsManagedAgentSymlinksWithoutLeakingExternalContent();
2783
+ testMultiProjectSyncRejectsManagedTargetSymlinksBeforeAnyProjectWrite();
2784
+ testTamperedInstalledDefaultRejectsInitAndSyncWithoutWrites();
2785
+ testExistingOverlayConflictRejectsInitAndSyncWithoutWrites();
2786
+ testExistingOverlayLegacyDeletionRejectsInitAndSyncWithoutWrites();
2787
+ testLiveInstallTransactionRejectsSecondInstallerWithoutWrites();
2788
+ testStagedRuntimeTamperingIsRejectedBeforeExecution();
2789
+ testInterruptedStagedInstallRecoversForInitAndSync();
2790
+ testArchiveFallbackCollisionsNeverLosePreviousContent();
2791
+ testProjectMutationAndInstallSwitchRejectParentSwap();
2792
+ testNoChangeLightGateRejectsInvalidEffectiveContracts();
2793
+ testStatusRejectsInvalidStructureEnforcementFromDoctorContract();
2794
+ testProjectConfigOverlayIsHighRiskAndReviewRequired();
2795
+ testStatusAndFeedbackUseEffectiveProjectConfigWithoutLeakingAccess();
1403
2796
  testManagedAgentModelsInheritAndOverridesSurvive();
1404
2797
  testForcePreservesCustomAgentsAndModelOverrides();
1405
2798
  testInvalidManagedAgentModelsFailStatusAndAreDroppedOnSync();
1406
2799
  testModelTextInsideInstructionsIsNotPromotedToOverride();
1407
2800
  testCommandSpecificArgumentsAreRejectedBeforeWrites();
1408
2801
  testBridgeIsGeneric();
1409
- testUpgradeCleansAllManagedSkillExtras();
2802
+ testSyncCleansAllManagedSkillExtras();
1410
2803
  testOptionalDocsAndLegacyToolsDoNotCauseDrift();
1411
2804
  testOptionalScaffoldIsOnDemandAndIdempotent();
1412
2805
  testTestingScaffoldMatchesCheckMatrixSchema();
1413
2806
  testReviewScaffoldLeavesBaselineGenerationToBaselineCommand();
1414
- testUpgradePrefersModernProjectAssetsAndIgnoresRetiredTemplates();
1415
- testUpgradeInitializesNewEngineeringDefaults();
1416
- testUpgradeMigratesLegacyAutomaticGateToFastDefault();
2807
+ testBaselineUpdateConfigWritesOnlyProjectOverlay();
2808
+ testSyncUsesPackagedAssetsAndIgnoresRetiredTemplates();
2809
+ testInitInitializesNewEngineeringDefaults();
2810
+ testInitMigratesLegacyAutomaticGateToFastDefault();
1417
2811
  testRemovedVerificationFlagsFailFast();
1418
- testUpgradeInstallsRuntimeRequiredByLauncher();
2812
+ testInstallBootstrapsRuntimeRequiredByLauncher();
2813
+ testCliInstallArchivesFeedbackTemplatesAndPreservesReports();
2814
+ testLegacyUpgradeWriteFailsWithoutAnyWrites();
1419
2815
  testLedgerArchiveRecognizesSettledStatuses();
1420
2816
  testLedgerArchiveUpdatesExistingPeriodIndex();
1421
2817
  testManagedEngineeringInitIsAuthoritativeAndIdempotent();
@@ -1429,6 +2825,7 @@ testUnknownWorkflowConflictFailsWholeBatchBeforeWrites();
1429
2825
  testEngineeringMarkerBoundaryIsNormalized();
1430
2826
  testEngineeringFrameworkRejectsAnyNonCanonicalWorkflowText();
1431
2827
  testManagedInstallIntegrityIsBoundedAndRepairable();
2828
+ testSkillFeedbackCollectionIsBoundedReadOnlyAndMetadataOnly();
1432
2829
  testReleaseVersionMarkersStayInSync();
1433
2830
  testProtocolResponsibilitiesStaySeparated();
1434
2831