@elvis1513/auto-coding-skill 3.0.1 → 3.0.3

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.
@@ -46,6 +46,39 @@ _GENERATED_NOISE_PATTERNS = [
46
46
  ]
47
47
  _AGENT_CONTRACT_VERSION = 1
48
48
  _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
49
+ _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
50
+ _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
51
+ "schema_version": 1,
52
+ "managed_versions": {"agents": "3.0.3", "engineering": "3.0.3"},
53
+ "known_official_engineering_body_sha256": [
54
+ "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
55
+ "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
56
+ "198d675361337bc272880154266b3eb1f50e3f82f3c6ab04b2e559cd18d8c7b4",
57
+ ],
58
+ "known_official_fragments": [],
59
+ "conflict_rules": [
60
+ {
61
+ "id": "mandatory-high-risk-full",
62
+ "paths": ["AGENTS.md", "docs/ENGINEERING.md"],
63
+ "pattern": r"^(?:.*(?:high[- ]risk|高风险).*(?:must|required|requires|必须|需).*(?:full(?:[ -]gate)?|gate_full|verify|验证).*)$",
64
+ "flags": "im",
65
+ "message": "normal development must not require a full/verify gate",
66
+ },
67
+ {
68
+ "id": "mandatory-change-full",
69
+ "paths": ["AGENTS.md", "docs/ENGINEERING.md"],
70
+ "pattern": r"^(?:.*(?:changes?|变更).*(?:require|required|requires|必须).*(?:full(?:[ -]gate)?|gate_full).*)$",
71
+ "flags": "im",
72
+ "message": "changed files must not automatically require a full gate",
73
+ },
74
+ ],
75
+ "dependency_recovery": {
76
+ "allowed_gate": "gate_changed",
77
+ "requires_locked_dependency": True,
78
+ "retry_same_gate_only": True,
79
+ "forbid_full_gate_recovery": True,
80
+ },
81
+ }
49
82
  _DEFAULT_DISPOSABLE_IGNORED_PATTERNS = [
50
83
  ".local/auto-coding-skill",
51
84
  ".local/auto-coding-skill/**",
@@ -625,13 +658,32 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
625
658
  if _bool_config(gate_cfg.get("full_on_unknown"), False):
626
659
  gate_cfg["full_on_unknown"] = False
627
660
  changed.append("gate.full_on_unknown")
661
+ if "full_on" in gate_cfg:
662
+ del gate_cfg["full_on"]
663
+ changed.append("gate.full_on")
664
+ raw_rules = gate_cfg.get("rules")
665
+ if isinstance(raw_rules, list):
666
+ migrated_rules: list = []
667
+ for index, rule in enumerate(raw_rules):
668
+ if not isinstance(rule, dict):
669
+ migrated_rules.append(rule)
670
+ continue
671
+ migrated_rule = dict(rule)
672
+ for legacy_key in ["scope", "commands"]:
673
+ if legacy_key in migrated_rule:
674
+ del migrated_rule[legacy_key]
675
+ changed.append(f"gate.rules[{index}].{legacy_key}")
676
+ if migrated_rule:
677
+ migrated_rules.append(migrated_rule)
678
+ if migrated_rules != raw_rules:
679
+ gate_cfg["rules"] = migrated_rules
628
680
 
629
681
  concurrency_cfg = cfg.setdefault("concurrency", {})
630
682
  if not isinstance(concurrency_cfg, dict):
631
683
  concurrency_cfg = {}
632
684
  cfg["concurrency"] = concurrency_cfg
633
- if _text(concurrency_cfg.get("isolation")).lower() != "worktree":
634
- concurrency_cfg["isolation"] = "worktree"
685
+ if _text(concurrency_cfg.get("isolation")).lower() != "adaptive":
686
+ concurrency_cfg["isolation"] = "adaptive"
635
687
  changed.append("concurrency.isolation")
636
688
 
637
689
  return changed
@@ -720,6 +772,7 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
720
772
  write = bool(args.write) and not bool(args.dry_run)
721
773
  source_root = _find_skill_asset_root(repo)
722
774
  templates = source_root / "data" / "templates"
775
+ template_engineering = templates / "ENGINEERING.md"
723
776
  actions: list[dict] = []
724
777
 
725
778
  def add_action(kind: str, path: Path, action: str, detail: str = "") -> None:
@@ -730,6 +783,25 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
730
783
  "detail": detail,
731
784
  })
732
785
 
786
+ # Complete policy discovery before the first write. Known official fragments
787
+ # are safe migration inputs; every remaining match is project-owned and must
788
+ # be handled explicitly instead of being overwritten by a partial upgrade.
789
+ workflow_plans = _workflow_policy_plans(repo)
790
+ workflow_issues = [issue for plan in workflow_plans for issue in plan["issues"]]
791
+ if workflow_issues:
792
+ raise APError(
793
+ "Upgrade preflight found unknown workflow policy conflicts; no files were written:\n- "
794
+ + "\n- ".join(workflow_issues)
795
+ )
796
+ workflow_plan_by_path = {plan["path"]: plan for plan in workflow_plans}
797
+ engineering_plan = workflow_plan_by_path["docs/ENGINEERING.md"]
798
+ if engineering_plan.get("official_body_hash") and template_engineering.exists():
799
+ current = engineering_plan["original"]
800
+ frontmatter = _frontmatter_span(current, "docs/ENGINEERING.md")
801
+ _, template_body = _read_frontmatter_markdown(template_engineering)
802
+ body_start = frontmatter[1] if frontmatter else 0
803
+ engineering_plan["output"] = current[:body_start] + template_body
804
+
733
805
  tool_files = [
734
806
  (
735
807
  source_root / "data" / "templates" / "tools" / "ap.py",
@@ -781,6 +853,14 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
781
853
  if write:
782
854
  copy_tree(source_root, project_skill)
783
855
 
856
+ agents_plan = workflow_plan_by_path["AGENTS.md"]
857
+ agents_path = repo / "AGENTS.md"
858
+ if agents_plan["output"] != agents_plan["original"]:
859
+ migrated = ", ".join(item["id"] for item in agents_plan["migrations"])
860
+ add_action("policy", agents_path, "migrate", migrated)
861
+ if write:
862
+ agents_path.write_text(agents_plan["output"], encoding="utf-8")
863
+
784
864
  docs_template = templates / "docs"
785
865
  for rel in _CORE_DOC_TEMPLATES:
786
866
  src = docs_template / rel
@@ -797,19 +877,25 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
797
877
  add_action("doc", dst, "ok")
798
878
 
799
879
  engineering = repo / "docs" / "ENGINEERING.md"
800
- template_engineering = templates / "ENGINEERING.md"
801
880
  if engineering.exists() and template_engineering.exists():
802
- current_cfg, body = _read_frontmatter_markdown(engineering)
881
+ planned_engineering = engineering_plan["output"] or engineering.read_text(encoding="utf-8")
882
+ current_cfg, body = _parse_frontmatter_markdown_text(planned_engineering, engineering)
803
883
  template_cfg, _ = _read_frontmatter_markdown(template_engineering)
804
884
  merged_cfg = json.loads(json.dumps(current_cfg))
805
885
  added_keys = _deep_merge_missing(merged_cfg, template_cfg)
806
886
  migrated_keys = _migrate_fast_development_defaults(merged_cfg, repo)
807
- if added_keys or migrated_keys:
887
+ body_migrated = planned_engineering != engineering_plan["original"]
888
+ if added_keys or migrated_keys or body_migrated:
808
889
  detail_parts = []
809
890
  if added_keys:
810
891
  detail_parts.append("add " + ", ".join(added_keys))
811
892
  if migrated_keys:
812
893
  detail_parts.append("migrate " + ", ".join(migrated_keys))
894
+ if body_migrated:
895
+ detail_parts.append(
896
+ "remove known legacy workflow "
897
+ + ", ".join(item["id"] for item in engineering_plan["migrations"])
898
+ )
813
899
  add_action("config", engineering, "merge", "; ".join(detail_parts))
814
900
  if write:
815
901
  _write_frontmatter_markdown(engineering, merged_cfg, body)
@@ -1063,10 +1149,290 @@ def _files_differ(a: Path, b: Path) -> bool:
1063
1149
  return _file_sha256(a) != _file_sha256(b)
1064
1150
 
1065
1151
 
1066
- def _read_frontmatter_markdown(path: Path) -> tuple[dict, str]:
1152
+ def _load_workflow_migration_policy(repo: Path) -> dict:
1153
+ policy_path = _find_skill_asset_root(repo) / _WORKFLOW_MIGRATION_POLICY
1154
+ if policy_path.exists():
1155
+ try:
1156
+ policy = json.loads(policy_path.read_text(encoding="utf-8"))
1157
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
1158
+ raise APError(f"Invalid workflow migration policy: {policy_path}: {exc}") from exc
1159
+ else:
1160
+ # Keep installed runtimes fail-closed during a rolling package update. The
1161
+ # packaged policy is authoritative once present; this fallback intentionally
1162
+ # knows no removable fragments, so only an explicit policy can auto-migrate.
1163
+ policy = json.loads(json.dumps(_FALLBACK_WORKFLOW_MIGRATION_POLICY))
1164
+
1165
+ if not isinstance(policy, dict) or policy.get("schema_version") != 1:
1166
+ raise APError(f"Unsupported workflow migration policy schema: {policy_path}")
1167
+ for field in [
1168
+ "known_official_engineering_body_sha256",
1169
+ "known_official_fragments",
1170
+ "conflict_rules",
1171
+ ]:
1172
+ if not isinstance(policy.get(field), list):
1173
+ raise APError(f"Workflow migration policy field must be a list: {field}")
1174
+ for index, fragment in enumerate(policy["known_official_fragments"]):
1175
+ if not isinstance(fragment, dict):
1176
+ raise APError(f"Workflow migration policy fragment[{index}] must be an object")
1177
+ if fragment.get("match") not in {"exact-line", "exact-block"}:
1178
+ raise APError(f"Workflow migration policy fragment[{index}] has invalid match mode")
1179
+ if not _text(fragment.get("id")) or not isinstance(fragment.get("paths"), list):
1180
+ raise APError(f"Workflow migration policy fragment[{index}] is incomplete")
1181
+ if not isinstance(fragment.get("text"), str) or not fragment["text"].strip():
1182
+ raise APError(f"Workflow migration policy fragment[{index}] has empty text")
1183
+ if "replacement" in fragment and not isinstance(fragment.get("replacement"), str):
1184
+ raise APError(f"Workflow migration policy fragment[{index}] replacement must be text")
1185
+ for index, rule in enumerate(policy["conflict_rules"]):
1186
+ if not isinstance(rule, dict):
1187
+ raise APError(f"Workflow migration policy conflict_rules[{index}] must be an object")
1188
+ flags = _text(rule.get("flags"))
1189
+ if set(flags) - {"i", "m"}:
1190
+ raise APError(f"Workflow migration policy conflict_rules[{index}] has invalid flags")
1191
+ if not _text(rule.get("id")) or not isinstance(rule.get("paths"), list):
1192
+ raise APError(f"Workflow migration policy conflict_rules[{index}] is incomplete")
1193
+ try:
1194
+ re.compile(_text(rule.get("pattern")), _workflow_regex_flags(flags))
1195
+ except re.error as exc:
1196
+ raise APError(
1197
+ f"Workflow migration policy conflict_rules[{index}] has invalid regex: {exc}"
1198
+ ) from exc
1199
+ return policy
1200
+
1201
+
1202
+ def _workflow_regex_flags(raw: str) -> int:
1203
+ flags = 0
1204
+ if "i" in raw:
1205
+ flags |= re.IGNORECASE
1206
+ if "m" in raw:
1207
+ flags |= re.MULTILINE
1208
+ return flags
1209
+
1210
+
1211
+ def _blank_text_span(text: str, start: int, end: int) -> str:
1212
+ return text[:start] + "".join("\n" if char == "\n" else " " for char in text[start:end]) + text[end:]
1213
+
1214
+
1215
+ def _merge_text_spans(spans: list[tuple[int, int]]) -> list[tuple[int, int]]:
1216
+ merged: list[tuple[int, int]] = []
1217
+ for start, end in sorted(spans):
1218
+ if start >= end:
1219
+ continue
1220
+ if merged and start <= merged[-1][1]:
1221
+ merged[-1] = (merged[-1][0], max(merged[-1][1], end))
1222
+ else:
1223
+ merged.append((start, end))
1224
+ return merged
1225
+
1226
+
1227
+ def _managed_document_span(text: str, kind: str, rel: str) -> Optional[tuple[int, int]]:
1228
+ token = f"auto-coding-skill:managed-{kind}"
1229
+ raw_starts = text.count(f"{token}:start")
1230
+ raw_ends = text.count(f"{token}:end")
1231
+ if raw_starts == 0 and raw_ends == 0:
1232
+ return None
1233
+ start_re = re.compile(
1234
+ rf"<!--\s*{re.escape(token)}:start(?:\s+version=[0-9]+\.[0-9]+\.[0-9]+)?\s*-->"
1235
+ )
1236
+ end_re = re.compile(rf"<!--\s*{re.escape(token)}:end\s*-->")
1237
+ starts = list(start_re.finditer(text))
1238
+ ends = list(end_re.finditer(text))
1239
+ if raw_starts != 1 or raw_ends != 1 or len(starts) != 1 or len(ends) != 1:
1240
+ raise APError(f"Malformed managed {kind} markers in {rel}")
1241
+ if starts[0].start() >= ends[0].start():
1242
+ raise APError(f"Out-of-order managed {kind} markers in {rel}")
1243
+ return starts[0].start(), ends[0].end()
1244
+
1245
+
1246
+ def _frontmatter_span(text: str, rel: str) -> Optional[tuple[int, int]]:
1247
+ if not text.startswith("---\n"):
1248
+ return None
1249
+ match = re.match(r"^---\n[\s\S]*?\n---(?:\n|$)", text)
1250
+ if not match:
1251
+ raise APError(f"Malformed Markdown frontmatter in {rel}")
1252
+ return 0, match.end()
1253
+
1254
+
1255
+ def _known_fragment_spans(
1256
+ visible: str,
1257
+ rel: str,
1258
+ policy: dict,
1259
+ ) -> list[tuple[int, int, str, int, str, str]]:
1260
+ found: list[tuple[int, int, str, int, str, str]] = []
1261
+ for fragment in policy.get("known_official_fragments") or []:
1262
+ if rel not in fragment.get("paths", []):
1263
+ continue
1264
+ fragment_id = _text(fragment.get("id"))
1265
+ replacement = str(fragment.get("replacement") or "")
1266
+ match_mode = _text(fragment.get("match"))
1267
+ expected = str(fragment.get("text") or "").replace("\r\n", "\n")
1268
+ if fragment.get("match") == "exact-line":
1269
+ cursor = 0
1270
+ for line in visible.splitlines(keepends=True):
1271
+ content = line.rstrip("\n")
1272
+ if content.strip() == expected.strip():
1273
+ found.append((cursor, cursor + len(line), fragment_id, visible.count("\n", 0, cursor) + 1, replacement, match_mode))
1274
+ cursor += len(line)
1275
+ continue
1276
+ cursor = 0
1277
+ while True:
1278
+ start = visible.find(expected, cursor)
1279
+ if start < 0:
1280
+ break
1281
+ end = start + len(expected)
1282
+ found.append((start, end, fragment_id, visible.count("\n", 0, start) + 1, replacement, match_mode))
1283
+ cursor = end
1284
+ return found
1285
+
1286
+
1287
+ def _workflow_document_plan(repo: Path, rel: str, policy: dict) -> dict:
1288
+ path = repo / rel
1067
1289
  if not path.exists():
1068
- return {}, ""
1069
- text = path.read_text(encoding="utf-8")
1290
+ return {"path": rel, "original": "", "output": "", "migrations": [], "issues": []}
1291
+ original = path.read_text(encoding="utf-8").replace("\r\n", "\n")
1292
+ protected: list[tuple[int, int]] = []
1293
+ if rel == "docs/ENGINEERING.md":
1294
+ frontmatter = _frontmatter_span(original, rel)
1295
+ if frontmatter:
1296
+ protected.append(frontmatter)
1297
+ managed = _managed_document_span(original, "workflow", rel)
1298
+ else:
1299
+ managed = _managed_document_span(original, "agents", rel)
1300
+ if managed:
1301
+ protected.append(managed)
1302
+
1303
+ visible = original
1304
+ for start, end in protected:
1305
+ visible = _blank_text_span(visible, start, end)
1306
+
1307
+ official_body_hash = ""
1308
+ if rel == "docs/ENGINEERING.md" and managed is None:
1309
+ body_start = protected[0][1] if protected else 0
1310
+ body = original[body_start:]
1311
+ digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
1312
+ if digest in set(policy.get("known_official_engineering_body_sha256") or []):
1313
+ official_body_hash = digest
1314
+ visible = _blank_text_span(visible, body_start, len(visible))
1315
+
1316
+ known = _known_fragment_spans(visible, rel, policy)
1317
+ known_spans = _merge_text_spans([(start, end) for start, end, _, _, _, _ in known])
1318
+ scan_text = visible
1319
+ for start, end in known_spans:
1320
+ scan_text = _blank_text_span(scan_text, start, end)
1321
+
1322
+ issues: list[str] = []
1323
+ candidates = _workflow_scan_candidates(scan_text)
1324
+ seen_issues: set[tuple[str, int]] = set()
1325
+ for rule in policy.get("conflict_rules") or []:
1326
+ if rel not in rule.get("paths", []):
1327
+ continue
1328
+ regex = re.compile(_text(rule.get("pattern")), _workflow_regex_flags(_text(rule.get("flags"))))
1329
+ for candidate, line in candidates:
1330
+ match = regex.search(candidate)
1331
+ if not match or (_text(rule.get("id")), line) in seen_issues:
1332
+ continue
1333
+ seen_issues.add((_text(rule.get("id")), line))
1334
+ snippet = " ".join(match.group(0).strip().split())[:180]
1335
+ message = _text(rule.get("message")) or "conflicts with the fast development workflow"
1336
+ issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}: {snippet}")
1337
+
1338
+ output = original
1339
+ for start, end, _, _, replacement, match_mode in sorted(known, reverse=True):
1340
+ if replacement and match_mode == "exact-line" and output[start:end].endswith("\n"):
1341
+ replacement = replacement + "\n"
1342
+ output = output[:start] + replacement + output[end:]
1343
+ migrations = [
1344
+ {"id": fragment_id, "line": line}
1345
+ for _, _, fragment_id, line, _, _ in known
1346
+ ]
1347
+ if official_body_hash:
1348
+ migrations.append({"id": f"official-body:{official_body_hash}", "line": 1})
1349
+ return {
1350
+ "path": rel,
1351
+ "original": original,
1352
+ "output": output,
1353
+ "migrations": migrations,
1354
+ "issues": issues,
1355
+ "official_body_hash": official_body_hash,
1356
+ }
1357
+
1358
+
1359
+ def _workflow_policy_plans(repo: Path, policy: Optional[dict] = None) -> list[dict]:
1360
+ effective = policy or _load_workflow_migration_policy(repo)
1361
+ return [
1362
+ _workflow_document_plan(repo, "AGENTS.md", effective),
1363
+ _workflow_document_plan(repo, "docs/ENGINEERING.md", effective),
1364
+ ]
1365
+
1366
+
1367
+ def _workflow_scan_candidates(text: str) -> list[tuple[str, int]]:
1368
+ lines = text.split("\n")
1369
+ candidates: list[tuple[str, int]] = [(line, index + 1) for index, line in enumerate(lines)]
1370
+ for index, line in enumerate(lines):
1371
+ if not line.strip():
1372
+ continue
1373
+ if re.match(r"^\s*(?:[-+*]|\d+\.)\s+", line):
1374
+ end = index + 1
1375
+ while end < len(lines) and re.match(r"^\s{2,}\S", lines[end]) and not re.match(
1376
+ r"^\s*(?:[-+*]|\d+\.)\s+", lines[end]
1377
+ ):
1378
+ end += 1
1379
+ if end > index + 1:
1380
+ candidates.append((" ".join(lines[index:end]), index + 1))
1381
+ continue
1382
+ if re.match(r"^\s*(?:#|\||```|~~~)", line):
1383
+ continue
1384
+ end = index + 1
1385
+ while end < len(lines) and lines[end].strip() and not re.match(
1386
+ r"^\s*(?:#|\||```|~~~|[-+*]|\d+\.)\s*", lines[end]
1387
+ ):
1388
+ end += 1
1389
+ if end > index + 1:
1390
+ candidates.append((" ".join(lines[index:end]), index + 1))
1391
+ return candidates
1392
+
1393
+
1394
+ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
1395
+ issues: list[str] = []
1396
+ gate_cfg = cfg.get("gate") or {}
1397
+ if not isinstance(gate_cfg, dict):
1398
+ return ["docs/ENGINEERING.md frontmatter gate must be a mapping"]
1399
+ if "full_on" in gate_cfg:
1400
+ issues.append("docs/ENGINEERING.md frontmatter gate.full_on is legacy automatic full escalation; run ap.py upgrade")
1401
+ if _bool_config(gate_cfg.get("full_on_unknown"), False):
1402
+ issues.append("docs/ENGINEERING.md frontmatter gate.full_on_unknown=true is legacy automatic full escalation; run ap.py upgrade")
1403
+ rules = gate_cfg.get("rules") or []
1404
+ if isinstance(rules, list):
1405
+ for index, rule in enumerate(rules):
1406
+ if not isinstance(rule, dict):
1407
+ continue
1408
+ for key in ["scope", "commands"]:
1409
+ if key in rule:
1410
+ issues.append(
1411
+ f"docs/ENGINEERING.md frontmatter gate.rules[{index}].{key} is legacy automatic gate escalation; run ap.py upgrade"
1412
+ )
1413
+ return issues
1414
+
1415
+
1416
+ def _workflow_policy_issues(repo: Path, cfg: Optional[dict] = None) -> list[str]:
1417
+ issues: list[str] = []
1418
+ for plan in _workflow_policy_plans(repo):
1419
+ issues.extend(plan["issues"])
1420
+ for migration in plan["migrations"]:
1421
+ issues.append(
1422
+ f"{plan['path']}:{migration['line']} [{migration['id']}] known legacy workflow rule; "
1423
+ "run `ap.py upgrade --dry-run` then `ap.py upgrade --write`"
1424
+ )
1425
+ issues.extend(_legacy_gate_config_issues(cfg if cfg is not None else _load_cfg(repo)))
1426
+ return issues
1427
+
1428
+
1429
+ def _require_workflow_policy_clean(repo: Path, cfg: Optional[dict] = None) -> None:
1430
+ issues = _workflow_policy_issues(repo, cfg)
1431
+ if issues:
1432
+ raise APError("Workflow policy conflicts block normal development:\n- " + "\n- ".join(issues))
1433
+
1434
+
1435
+ def _parse_frontmatter_markdown_text(text: str, path: Path) -> tuple[dict, str]:
1070
1436
  m = re.match(r"^---\s*\n(.*?)\n---\s*(\n|$)(.*)$", text, flags=re.DOTALL)
1071
1437
  if not m:
1072
1438
  raise APError(f"Markdown frontmatter not found: {path}")
@@ -1076,6 +1442,12 @@ def _read_frontmatter_markdown(path: Path) -> tuple[dict, str]:
1076
1442
  return data, m.group(3)
1077
1443
 
1078
1444
 
1445
+ def _read_frontmatter_markdown(path: Path) -> tuple[dict, str]:
1446
+ if not path.exists():
1447
+ return {}, ""
1448
+ return _parse_frontmatter_markdown_text(path.read_text(encoding="utf-8"), path)
1449
+
1450
+
1079
1451
  def _write_frontmatter_markdown(path: Path, data: dict, body: str) -> None:
1080
1452
  if yaml is None:
1081
1453
  raise APError("PyYAML not installed. Install dependencies with: pip install pyyaml requests")
@@ -1128,10 +1500,10 @@ def _concurrency_cfg(cfg: dict) -> dict:
1128
1500
 
1129
1501
 
1130
1502
  def _task_isolation(cfg: dict) -> str:
1131
- isolation = _text(_concurrency_cfg(cfg).get("isolation")).lower() or "worktree"
1132
- if isolation != "worktree":
1503
+ isolation = _text(_concurrency_cfg(cfg).get("isolation")).lower() or "adaptive"
1504
+ if isolation not in {"adaptive", "worktree"}:
1133
1505
  raise APError(
1134
- "concurrency.isolation must be worktree; shared-checkout/legacy writes are no longer supported"
1506
+ "concurrency.isolation must be adaptive or worktree; legacy shared-checkout mode is unsupported"
1135
1507
  )
1136
1508
  return isolation
1137
1509
 
@@ -3700,7 +4072,7 @@ def _agent_contract_shape() -> tuple[dict, list[str]]:
3700
4072
  "depends_on",
3701
4073
  "acceptance",
3702
4074
  ],
3703
- "writer": ["task_branch", "worktree_path", "owned_paths"],
4075
+ "writer": ["execution_mode", "owned_paths", "task_branch/worktree_path when isolated"],
3704
4076
  "reviewer": [
3705
4077
  "task_id",
3706
4078
  "diff_base",
@@ -3764,6 +4136,7 @@ def _agent_execution_plan(profile: str, categories: set[str], classification: di
3764
4136
  "strategy": "main-only",
3765
4137
  "policies": {
3766
4138
  "one_writer_per_worktree": True,
4139
+ "workspace_isolation": "adaptive-clean-current-or-isolated",
3767
4140
  "path_ownership": "explicit-non-overlapping",
3768
4141
  "dependency_policy": "integrate-before-dependent-start",
3769
4142
  "review_feedback_owner": "main",
@@ -3799,6 +4172,7 @@ def _agent_execution_plan(profile: str, categories: set[str], classification: di
3799
4172
  "strategy": "orchestrated-subagents",
3800
4173
  "policies": {
3801
4174
  "one_writer_per_worktree": True,
4175
+ "workspace_isolation": "adaptive-clean-current-or-isolated",
3802
4176
  "path_ownership": "explicit-non-overlapping",
3803
4177
  "dependency_policy": "integrate-before-dependent-start",
3804
4178
  "review_feedback_owner": "owning-fixer",
@@ -3862,12 +4236,12 @@ def _agent_execution_plan(profile: str, categories: set[str], classification: di
3862
4236
  ],
3863
4237
  "constraints": [
3864
4238
  "Delegate only independent bounded work and declare dependencies before dispatch.",
3865
- "Every fixer owns exactly one registered task branch/worktree and an explicit path scope.",
4239
+ "One serial fixer may use a clean current branch; dirty or parallel writers require registered task branches/worktrees.",
3866
4240
  "Never run two writers in one worktree or let the main agent edit a fixer-owned worktree concurrently.",
3867
4241
  "Start a dependent write task only after its prerequisite has been integrated into the target branch.",
3868
4242
  "Subagents do not commit, push, integrate, or clean task branches.",
3869
4243
  "Reviewers inspect a stable diff; changes-requested returns to the owning fixer and any edit requires re-review.",
3870
- "The main agent routes review feedback, runs the single fast gate for each write task, integrates in dependency order, pushes, and cleans branches.",
4244
+ "The main agent routes review feedback, runs one fast gate, pushes, and cleans only temporary branches/worktrees that were actually created.",
3871
4245
  ],
3872
4246
  })
3873
4247
 
@@ -4305,6 +4679,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
4305
4679
 
4306
4680
  missing: List[str] = []
4307
4681
  validation_errors: List[str] = []
4682
+ validation_errors.extend(_workflow_policy_issues(repo, cfg))
4308
4683
 
4309
4684
  mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
4310
4685
  profile = str(workflow_cfg.get("profile") or "auto").strip().lower()
@@ -4315,10 +4690,10 @@ def cmd_doctor(args: argparse.Namespace) -> None:
4315
4690
  missing.append("workflow.profile (must be auto, micro, standard, or high-risk)")
4316
4691
  if completion != "push":
4317
4692
  missing.append("workflow.completion (must be push)")
4318
- isolation = _text(concurrency_cfg.get("isolation")).lower() or "worktree"
4319
- if isolation != "worktree":
4693
+ isolation = _text(concurrency_cfg.get("isolation")).lower() or "adaptive"
4694
+ if isolation not in {"adaptive", "worktree"}:
4320
4695
  validation_errors.append(
4321
- "concurrency.isolation must be worktree; shared-checkout/legacy writes are no longer supported"
4696
+ "concurrency.isolation must be adaptive or worktree; legacy shared-checkout mode is unsupported"
4322
4697
  )
4323
4698
  branch_prefix = _text(concurrency_cfg.get("branch_prefix")) or "codex/"
4324
4699
  if not branch_prefix.endswith("/"):
@@ -4336,6 +4711,8 @@ def cmd_doctor(args: argparse.Namespace) -> None:
4336
4711
  if enforcement and enforcement not in {"advisory", "blocking"}:
4337
4712
  validation_errors.append("structure.enforcement must be advisory or blocking")
4338
4713
  gate_cfg = _gate_cfg(cfg)
4714
+ if "full_on" in gate_cfg:
4715
+ validation_errors.append("gate.full_on is legacy automatic full escalation; run ap.py upgrade")
4339
4716
  raw_rules = gate_cfg.get("rules") or []
4340
4717
  rules_valid = isinstance(raw_rules, list)
4341
4718
  if not rules_valid:
@@ -4353,10 +4730,15 @@ def cmd_doctor(args: argparse.Namespace) -> None:
4353
4730
  f"gate.rules[{index}].profile must be micro, standard, or high-risk"
4354
4731
  )
4355
4732
  rule_scope = _text(rule.get("scope")).lower()
4356
- if rule_scope and rule_scope not in {"changed", "standard", "full"}:
4733
+ if "scope" in rule:
4734
+ rules_valid = False
4735
+ validation_errors.append(
4736
+ f"gate.rules[{index}].scope is legacy automatic gate escalation; run ap.py upgrade"
4737
+ )
4738
+ if "commands" in rule:
4357
4739
  rules_valid = False
4358
4740
  validation_errors.append(
4359
- f"gate.rules[{index}].scope must be changed, standard, or full"
4741
+ f"gate.rules[{index}].commands is legacy automatic gate escalation; run ap.py upgrade"
4360
4742
  )
4361
4743
 
4362
4744
  if not (_configured_command(cfg, "gate_changed") or _configured_command(cfg, "quick_test")):
@@ -5607,6 +5989,7 @@ def cmd_task_start(args: argparse.Namespace) -> None:
5607
5989
  repo = Path(args.repo).resolve()
5608
5990
  ensure_git_repo(repo)
5609
5991
  cfg = _load_cfg(repo)
5992
+ _require_workflow_policy_clean(repo, cfg)
5610
5993
  _task_isolation(cfg)
5611
5994
  access_issues = _access_config_issues(cfg)
5612
5995
  if access_issues:
@@ -6645,6 +7028,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
6645
7028
  repo = Path(args.repo).resolve()
6646
7029
  ensure_git_repo(repo)
6647
7030
  cfg = _load_cfg(repo)
7031
+ _require_workflow_policy_clean(repo, cfg)
6648
7032
  manifest = _require_task_context(repo, cfg, args.task_id)
6649
7033
  _require_current_writer(manifest, args)
6650
7034
  lock_name = f"task-{_validate_task_id(args.task_id)}"