@elvis1513/auto-coding-skill 4.2.0 → 4.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -42,6 +42,17 @@ _GENERATED_NOISE_PATTERNS = [
42
42
  ]
43
43
  _AGENT_CONTRACT_VERSION = 1
44
44
  _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
45
+ _FOCUSED_REVIEW_TIMEOUT_SECONDS = 90
46
+ _DEEP_REVIEW_TIMEOUT_SECONDS = 300
47
+ _DEEP_REVIEW_CATEGORIES = {
48
+ "api",
49
+ "auth",
50
+ "db",
51
+ "file_transfer",
52
+ "gateway",
53
+ "payment",
54
+ "prod_config",
55
+ }
45
56
  _RECOMMENDED_FINAL_COMMAND_SECONDS = 120.0
46
57
  _RECOMMENDED_FINAL_TOTAL_SECONDS = 180.0
47
58
  _FINAL_GATE_CACHE_SCHEMA = 1
@@ -49,7 +60,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
49
60
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
50
61
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
51
62
  "schema_version": 1,
52
- "managed_versions": {"agents": "4.2.0", "engineering": "4.2.0"},
63
+ "managed_versions": {"agents": "4.2.1", "engineering": "4.2.1"},
53
64
  "known_official_engineering_body_sha256": [
54
65
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
55
66
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -962,8 +973,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
962
973
  if _text(workflow_cfg.get("completion")).lower() != "push":
963
974
  workflow_cfg["completion"] = "push"
964
975
  changed.append("workflow.completion")
965
- if _text(workflow_cfg.get("skill_version")) != "4.2.0":
966
- workflow_cfg["skill_version"] = "4.2.0"
976
+ if _text(workflow_cfg.get("skill_version")) != "4.2.1":
977
+ workflow_cfg["skill_version"] = "4.2.1"
967
978
  changed.append("workflow.skill_version")
968
979
 
969
980
  commands_cfg = cfg.setdefault("commands", {})
@@ -1276,16 +1287,16 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1276
1287
  if current_agents:
1277
1288
  archive_dir = repo / "docs" / "archive" / "workflow"
1278
1289
  archive_header = (
1279
- "# Archived AGENTS.md before auto-coding-skill 4.2.0\n\n"
1290
+ "# Archived AGENTS.md before auto-coding-skill 4.2.1\n\n"
1280
1291
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
1281
1292
  "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
1282
1293
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
1283
1294
  )
1284
1295
  archive_content = archive_header + current_agents
1285
- archive = archive_dir / "AGENTS.pre-4.2.0.md"
1296
+ archive = archive_dir / "AGENTS.pre-4.2.1.md"
1286
1297
  if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
1287
1298
  digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
1288
- archive = archive_dir / f"AGENTS.pre-4.2.0-{digest}.md"
1299
+ archive = archive_dir / f"AGENTS.pre-4.2.1-{digest}.md"
1289
1300
  if not archive.exists():
1290
1301
  add_action("policy", archive, "archive", "historical and non-authoritative")
1291
1302
  if write:
@@ -2066,9 +2077,38 @@ def _active_direct_claims(repo: Path) -> list[dict]:
2066
2077
  return []
2067
2078
  active: list[dict] = []
2068
2079
  for path in sorted(root.glob("*.json")):
2069
- payload = _read_json_object(path) or {}
2070
- worktree = Path(_text(payload.get("worktree_path"))).resolve()
2071
- valid_checkout = worktree.exists() and _text(payload.get("worktree_path"))
2080
+ payload = _read_json_object(path)
2081
+ if payload is None:
2082
+ raise APError(
2083
+ f"Direct claim registry is unreadable or invalid JSON: {path}. "
2084
+ "Refusing to assume the checkout has no active writer."
2085
+ )
2086
+ try:
2087
+ schema = int(payload.get("schema") or 0)
2088
+ except (TypeError, ValueError) as exc:
2089
+ raise APError(f"Direct claim registry has an invalid schema: {path}") from exc
2090
+ claim_id = _text(payload.get("claim_id"))
2091
+ worktree_value = _text(payload.get("worktree_path"))
2092
+ owned_paths = payload.get("owned_paths")
2093
+ if (
2094
+ schema != 1
2095
+ or _text(payload.get("state")) != "active"
2096
+ or claim_id != path.stem
2097
+ or not _DIRECT_CLAIM_ID_RE.fullmatch(claim_id)
2098
+ or not _text(payload.get("owner"))
2099
+ or not _text(payload.get("base_sha"))
2100
+ or not _text(payload.get("branch"))
2101
+ or not worktree_value
2102
+ or not isinstance(owned_paths, list)
2103
+ or not owned_paths
2104
+ or not all(isinstance(item, str) and _text(item) for item in owned_paths)
2105
+ ):
2106
+ raise APError(
2107
+ f"Direct claim registry is malformed: {path}. "
2108
+ "Refusing to assume the checkout has no active writer."
2109
+ )
2110
+ worktree = Path(worktree_value).resolve()
2111
+ valid_checkout = worktree.exists()
2072
2112
  if valid_checkout:
2073
2113
  try:
2074
2114
  valid_checkout = bool(
@@ -2077,11 +2117,7 @@ def _active_direct_claims(repo: Path) -> list[dict]:
2077
2117
  )
2078
2118
  except APError:
2079
2119
  valid_checkout = False
2080
- if (
2081
- int(payload.get("schema") or 0) != 1
2082
- or _text(payload.get("state")) != "active"
2083
- or not valid_checkout
2084
- ):
2120
+ if not valid_checkout:
2085
2121
  path.unlink(missing_ok=True)
2086
2122
  continue
2087
2123
  active.append(payload)
@@ -2114,23 +2150,25 @@ def _create_direct_claim(repo: Path, cfg: dict, owned_paths: list[str], owner: s
2114
2150
  if _has_registered_active_task(repo):
2115
2151
  raise APError("A registered active task acquired repository writes.")
2116
2152
  existing = _active_direct_claims(repo)
2117
- other = [item for item in existing if _text(item.get("owner")) != _text(owner)]
2118
- if other:
2153
+ base_sha = _resolve_commit(repo, "HEAD")
2154
+ worktree_path = str(repo.resolve())
2155
+ if existing:
2119
2156
  raise APError(
2120
2157
  "Another direct writer already owns this checkout: "
2121
- + ", ".join(_text(item.get("owner")) for item in other)
2158
+ + ", ".join(
2159
+ f"{_text(item.get('owner'))}:{_text(item.get('claim_id'))}"
2160
+ for item in existing
2161
+ )
2122
2162
  )
2123
- for item in existing:
2124
- _direct_claim_path(repo, _text(item.get("claim_id"))).unlink(missing_ok=True)
2125
2163
  claim_id = uuid.uuid4().hex
2126
2164
  payload = {
2127
2165
  "schema": 1,
2128
2166
  "claim_id": claim_id,
2129
2167
  "state": "active",
2130
2168
  "owner": _text(owner),
2131
- "base_sha": _resolve_commit(repo, "HEAD"),
2169
+ "base_sha": base_sha,
2132
2170
  "branch": branch,
2133
- "worktree_path": str(repo.resolve()),
2171
+ "worktree_path": worktree_path,
2134
2172
  "owned_paths": normalized,
2135
2173
  "created_at": _now_iso(),
2136
2174
  }
@@ -2175,8 +2213,19 @@ def _has_registered_active_task(repo: Path) -> bool:
2175
2213
  if not registry.exists():
2176
2214
  return False
2177
2215
  for path in sorted(registry.glob("*.json")):
2178
- payload = _read_json_object(path) or {}
2179
- if _text(payload.get("state")) not in {"", "integrated", "cleanup-pending"}:
2216
+ payload = _read_json_object(path)
2217
+ if payload is None:
2218
+ raise APError(
2219
+ f"Task registry is unreadable or invalid JSON: {path}. "
2220
+ "Refusing to assume the checkout has no active writer."
2221
+ )
2222
+ state = _text(payload.get("state"))
2223
+ if not state:
2224
+ raise APError(
2225
+ f"Task registry has no state: {path}. "
2226
+ "Refusing to assume the checkout has no active writer."
2227
+ )
2228
+ if state not in {"integrated", "cleanup-pending"}:
2180
2229
  return True
2181
2230
  return False
2182
2231
 
@@ -2388,22 +2437,57 @@ def _checked_git_z_paths(repo: Path, command: list[str], context: str) -> list[s
2388
2437
 
2389
2438
 
2390
2439
  def _working_tree_paths(repo: Path) -> list[str]:
2391
- paths: set[str] = set()
2392
- paths.update(
2393
- _git_z_paths(
2394
- repo,
2395
- ["git", "diff", "--no-renames", "--name-only", "-z", "--diff-filter=ACDMRTUXB"],
2396
- )
2440
+ """Return one fail-closed Git status snapshot, including both rename endpoints."""
2441
+ result = run(
2442
+ [
2443
+ "git",
2444
+ "status",
2445
+ "--porcelain=v2",
2446
+ "-z",
2447
+ "--untracked-files=all",
2448
+ "--no-renames",
2449
+ ],
2450
+ cwd=repo,
2451
+ check=False,
2397
2452
  )
2398
- paths.update(
2399
- _git_z_paths(
2400
- repo,
2401
- ["git", "diff", "--cached", "--no-renames", "--name-only", "-z", "--diff-filter=ACDMRTUXB"],
2453
+ if result.returncode != 0:
2454
+ raise APError(
2455
+ "Cannot inspect working tree status; refusing a direct execution plan: "
2456
+ + (result.stderr.strip() or result.stdout.strip() or "git status failed")
2402
2457
  )
2403
- )
2404
- paths.update(
2405
- _git_z_paths(repo, ["git", "ls-files", "--others", "--exclude-standard", "-z"])
2406
- )
2458
+ paths: set[str] = set()
2459
+ entries = result.stdout.split("\0")
2460
+ index = 0
2461
+ while index < len(entries):
2462
+ entry = entries[index]
2463
+ index += 1
2464
+ if not entry:
2465
+ continue
2466
+ record_type = entry[:1]
2467
+ if record_type == "1":
2468
+ fields = entry.split(" ", 8)
2469
+ path = fields[8] if len(fields) == 9 else ""
2470
+ elif record_type == "2":
2471
+ fields = entry.split(" ", 9)
2472
+ path = fields[9] if len(fields) == 10 else ""
2473
+ if index >= len(entries) or not entries[index]:
2474
+ raise APError(
2475
+ "Cannot parse renamed Git path; refusing a direct execution plan."
2476
+ )
2477
+ paths.add(entries[index])
2478
+ index += 1
2479
+ elif record_type == "u":
2480
+ fields = entry.split(" ", 10)
2481
+ path = fields[10] if len(fields) == 11 else ""
2482
+ elif entry.startswith("? "):
2483
+ path = entry[2:]
2484
+ else:
2485
+ path = ""
2486
+ if not path:
2487
+ raise APError(
2488
+ "Cannot parse Git working tree status; refusing a direct execution plan."
2489
+ )
2490
+ paths.add(path)
2407
2491
  return sorted(path.replace("\\", "/") for path in paths if path)
2408
2492
 
2409
2493
 
@@ -3358,10 +3442,14 @@ def _default_base_ref(repo: Path) -> str:
3358
3442
  return upstream[0] if upstream else ""
3359
3443
 
3360
3444
 
3445
+ def _effective_change_base(repo: Path, base_ref: str = "") -> str:
3446
+ manifest = _active_task_manifest(repo)
3447
+ return base_ref or (_text(manifest.get("base_sha")) if manifest else "") or _default_base_ref(repo)
3448
+
3449
+
3361
3450
  def _changed_files(repo: Path, base_ref: str = "") -> list[str]:
3362
3451
  paths: list[str] = []
3363
- manifest = _active_task_manifest(repo)
3364
- effective_base = base_ref or (_text(manifest.get("base_sha")) if manifest else "") or _default_base_ref(repo)
3452
+ effective_base = _effective_change_base(repo, base_ref)
3365
3453
  if effective_base:
3366
3454
  paths.extend(_git_lines(repo, ["git", "diff", "--no-renames", "--name-only", "--diff-filter=ACDMRTUXB", f"{effective_base}...HEAD"]))
3367
3455
  paths.extend(_git_lines(repo, ["git", "diff", "--no-renames", "--name-only", "--diff-filter=ACDMRTUXB"]))
@@ -3756,6 +3844,9 @@ def _run_git_diff_check(repo: Path, cfg: dict) -> None:
3756
3844
 
3757
3845
  _DEFAULT_STRUCTURE_ALLOW_PATTERNS = [
3758
3846
  ".git/**",
3847
+ ".agents/archive/**",
3848
+ ".agents/agents/**",
3849
+ ".agents/managed-install.json",
3759
3850
  ".agents/skills/**",
3760
3851
  ".next/**",
3761
3852
  ".nuxt/**",
@@ -5132,7 +5223,7 @@ def _classify_paths(paths: list[str]) -> dict:
5132
5223
  categories.add("gateway")
5133
5224
  if "production" in words or "prod" in words and "config" in words or ".env.prod" in lower:
5134
5225
  categories.add("prod_config")
5135
- if any(token in lower for token in ["page", "component", "view", "frontend", "miniapp", ".tsx", ".jsx", ".vue", ".scss", ".css"]):
5226
+ if _is_ui_path(path):
5136
5227
  categories.add("ui")
5137
5228
  if any(token in lower for token in ["test", "spec", "__tests__"]):
5138
5229
  categories.add("test")
@@ -5143,6 +5234,17 @@ def _classify_paths(paths: list[str]) -> dict:
5143
5234
  return _classification_for_categories(categories, len(paths))
5144
5235
 
5145
5236
 
5237
+ _UI_PATH_SEGMENTS = {"frontend", "miniapp", "page", "pages", "component", "components", "view", "views"}
5238
+ _UI_FILE_SUFFIXES = {".css", ".jsx", ".scss", ".tsx", ".vue"}
5239
+
5240
+
5241
+ def _is_ui_path(path: str) -> bool:
5242
+ """Classify UI paths by exact directory semantics or UI-only extensions."""
5243
+ normalized = path.replace("\\", "/").strip("/").lower()
5244
+ directories = [part for part in normalized.split("/")[:-1] if part]
5245
+ return Path(normalized).suffix.lower() in _UI_FILE_SUFFIXES or any(part in _UI_PATH_SEGMENTS for part in directories)
5246
+
5247
+
5146
5248
  def _classification_for_categories(categories: set[str], file_count: int) -> dict:
5147
5249
  return {
5148
5250
  "categories": sorted(categories),
@@ -5223,6 +5325,79 @@ def _high_confidence_intent_categories(intent: str) -> set[str]:
5223
5325
  }
5224
5326
 
5225
5327
 
5328
+ _MECHANICAL_CHANGE_SIGNALS = (
5329
+ "mechanical", "rename only", "move only", "pure rename", "pure move", "no behavior change",
5330
+ "without behavior change", "behavior unchanged", "source of truth unchanged", "contract unchanged",
5331
+ "仅改名", "只改名", "仅移动", "只移动", "不改变行为", "行为不变", "机械同步", "机械变更", "契约不变", "事实源不变",
5332
+ )
5333
+ _SEMANTIC_CHANGE_SIGNALS = (
5334
+ "semantic change", "change behavior", "behavior change", "new behavior", "architecture change", "contract change", "schema change",
5335
+ "语义变更", "行为变更", "改变行为", "新增行为", "架构变更", "契约变更", "模式变更",
5336
+ )
5337
+
5338
+
5339
+ def _intent_change_nature(intent: str) -> str:
5340
+ value = _text(intent).lower()
5341
+ if not value:
5342
+ return "unknown"
5343
+ semantic_value = re.sub(r"\b(?:not\s+(?:a\s+)?|non[- ]?|isn't\s+)mechanical\b|(?:不是|并非|非)机械(?:变更|同步)?", " ", value)
5344
+ mechanical = [] if semantic_value != value else [signal for signal in _MECHANICAL_CHANGE_SIGNALS if signal in value]
5345
+ for signal in mechanical:
5346
+ semantic_value = semantic_value.replace(signal, " ")
5347
+ for pattern in [r"\bno\s+.{0,16}\bbehavior\s+change\b", r"不改变.{0,16}行为"]:
5348
+ if re.search(pattern, semantic_value):
5349
+ mechanical.append(pattern)
5350
+ semantic_value = re.sub(pattern, " ", semantic_value)
5351
+ if any(signal in semantic_value for signal in _SEMANTIC_CHANGE_SIGNALS) or re.search(
5352
+ r"\b(?:change|changes|changed|changing|modify|modifies|modified|modifying|alter|alters|altered|altering|update|updates|updated|updating)\b.{0,40}\b(?:behaviors?|semantics?|architecture|contracts?|schemas?)\b"
5353
+ r"|\b(?:behaviors?|semantics?|architecture|contracts?|schemas?)\b.{0,24}\b(?:change|changes|changed|changing)\b|(?:修改|调整|改变|新增|更新).{0,32}(?:行为|语义|架构|契约|模式)|(?:行为|语义|架构|契约|模式).{0,16}(?:变化|变更|调整)", semantic_value
5354
+ ):
5355
+ return "semantic"
5356
+ if mechanical:
5357
+ return "mechanical"
5358
+ return "unknown"
5359
+
5360
+
5361
+ def _pure_exact_git_rename(repo: Path, base_ref: str, changed_paths: list[str]) -> bool:
5362
+ common = ["--name-status", "-z", "-M100%", "--diff-filter=ACDMRTUXB"]
5363
+ commands = [["git", "diff", *common], ["git", "diff", "--cached", *common]]
5364
+ effective_base = _effective_change_base(repo, base_ref)
5365
+ if effective_base:
5366
+ commands.insert(0, ["git", "diff", *common, f"{effective_base}...HEAD"])
5367
+ entries: list[tuple[str, tuple[str, ...]]] = []
5368
+ for command in commands:
5369
+ result = run(command, cwd=repo, check=False)
5370
+ if result.returncode != 0:
5371
+ return False
5372
+ tokens = [token for token in result.stdout.split("\0") if token]
5373
+ index = 0
5374
+ while index < len(tokens):
5375
+ status = tokens[index]
5376
+ width = 2 if status[:1] in {"R", "C"} else 1
5377
+ paths = tokens[index + 1 : index + 1 + width]
5378
+ if len(paths) != width:
5379
+ return False
5380
+ entries.append((status, tuple(path.replace("\\", "/") for path in paths)))
5381
+ index += width + 1
5382
+ renamed = {path for status, paths in entries if status == "R100" for path in paths}
5383
+ changed = {path.replace("\\", "/") for path in changed_paths if _text(path)}
5384
+ return bool(entries) and all(status == "R100" for status, _ in entries) and renamed == changed
5385
+
5386
+
5387
+ def _classify_change_nature(
5388
+ repo: Path,
5389
+ *,
5390
+ base_ref: str,
5391
+ changed_paths: list[str],
5392
+ intent: str,
5393
+ inspect_git: bool,
5394
+ ) -> str:
5395
+ intent_nature = _intent_change_nature(intent)
5396
+ if intent_nature != "semantic" and inspect_git and changed_paths and _pure_exact_git_rename(repo, base_ref, changed_paths):
5397
+ return "mechanical"
5398
+ return intent_nature
5399
+
5400
+
5226
5401
  def _resolve_task_kind(
5227
5402
  requested: str,
5228
5403
  paths: list[str],
@@ -5323,6 +5498,7 @@ def _recommended_agents(
5323
5498
  *,
5324
5499
  parallel_writers: int = 1,
5325
5500
  review_required: bool = False,
5501
+ review_policy: Optional[dict] = None,
5326
5502
  ) -> list[str]:
5327
5503
  roles: list[str] = []
5328
5504
  for stage in _agent_execution_plan(
@@ -5331,6 +5507,7 @@ def _recommended_agents(
5331
5507
  classification,
5332
5508
  parallel_writers=parallel_writers,
5333
5509
  review_required=review_required,
5510
+ review_policy=review_policy,
5334
5511
  )["stages"]:
5335
5512
  for role in stage["roles"]:
5336
5513
  if role != "main" and role not in roles:
@@ -5430,9 +5607,19 @@ def _contract_equal(left: object, right: object) -> bool:
5430
5607
  return left == right
5431
5608
 
5432
5609
 
5433
- def _validate_contract_fragment(fragment: dict, value: object, root: dict, path: str) -> None:
5610
+ def _contract_validation_errors(
5611
+ fragment: dict,
5612
+ value: object,
5613
+ root: dict,
5614
+ path: str,
5615
+ ) -> list[str]:
5616
+ errors: list[str] = []
5434
5617
  if "$ref" in fragment:
5435
- _validate_contract_fragment(_contract_ref(root, _text(fragment["$ref"])), value, root, path)
5618
+ errors.extend(
5619
+ _contract_validation_errors(
5620
+ _contract_ref(root, _text(fragment["$ref"])), value, root, path
5621
+ )
5622
+ )
5436
5623
 
5437
5624
  expected_types = fragment.get("type")
5438
5625
  if expected_types is not None:
@@ -5440,60 +5627,61 @@ def _validate_contract_fragment(fragment: dict, value: object, root: dict, path:
5440
5627
  if not all(isinstance(item, str) for item in choices) or not any(
5441
5628
  _contract_type_matches(value, item) for item in choices
5442
5629
  ):
5443
- raise APError(f"Contract validation failed at {path}: expected type {choices}.")
5630
+ errors.append(f"{path}: expected type {choices}")
5631
+ return errors
5444
5632
 
5445
5633
  if "const" in fragment and not _contract_equal(value, fragment["const"]):
5446
- raise APError(f"Contract validation failed at {path}: expected constant {fragment['const']!r}.")
5447
- if "enum" in fragment and not any(_contract_equal(value, item) for item in fragment["enum"]):
5448
- raise APError(f"Contract validation failed at {path}: value is outside the allowed enum.")
5634
+ errors.append(f"{path}: expected constant {fragment['const']!r}")
5635
+ if "enum" in fragment and not any(
5636
+ _contract_equal(value, item) for item in fragment["enum"]
5637
+ ):
5638
+ errors.append(f"{path}: value is outside the allowed enum")
5449
5639
 
5450
5640
  if isinstance(value, str):
5451
5641
  if len(value) < int(fragment.get("minLength") or 0):
5452
- raise APError(f"Contract validation failed at {path}: string is too short.")
5642
+ errors.append(f"{path}: string is too short")
5453
5643
  pattern = fragment.get("pattern")
5454
5644
  if pattern and not re.search(str(pattern), value):
5455
- raise APError(f"Contract validation failed at {path}: string does not match {pattern!r}.")
5645
+ errors.append(f"{path}: string does not match {pattern!r}")
5456
5646
 
5457
5647
  if isinstance(value, list):
5458
5648
  if "maxItems" in fragment and len(value) > int(fragment["maxItems"]):
5459
- raise APError(f"Contract validation failed at {path}: too many array items.")
5649
+ errors.append(f"{path}: too many array items")
5460
5650
  item_schema = fragment.get("items")
5461
5651
  if isinstance(item_schema, dict):
5462
5652
  for index, item in enumerate(value):
5463
- _validate_contract_fragment(item_schema, item, root, f"{path}[{index}]")
5653
+ errors.extend(
5654
+ _contract_validation_errors(item_schema, item, root, f"{path}[{index}]")
5655
+ )
5464
5656
 
5465
5657
  if isinstance(value, dict):
5466
5658
  required = fragment.get("required") or []
5467
- missing = [item for item in required if item not in value]
5659
+ missing = sorted(item for item in required if item not in value)
5468
5660
  if missing:
5469
- raise APError(
5470
- f"Contract validation failed at {path}: missing " + ", ".join(sorted(missing)) + "."
5471
- )
5661
+ errors.append(f"{path}: missing " + ", ".join(missing))
5472
5662
  properties = fragment.get("properties") or {}
5473
5663
  if fragment.get("additionalProperties") is False:
5474
5664
  unexpected = sorted(set(value) - set(properties))
5475
5665
  if unexpected:
5476
- raise APError(
5477
- f"Contract validation failed at {path}: unexpected " + ", ".join(unexpected) + "."
5478
- )
5666
+ errors.append(f"{path}: unexpected " + ", ".join(unexpected))
5479
5667
  for key, child in properties.items():
5480
5668
  if key in value and isinstance(child, dict):
5481
- _validate_contract_fragment(child, value[key], root, f"{path}.{key}")
5669
+ errors.extend(
5670
+ _contract_validation_errors(child, value[key], root, f"{path}.{key}")
5671
+ )
5482
5672
 
5483
5673
  condition = fragment.get("if")
5484
- if isinstance(condition, dict):
5485
- try:
5486
- _validate_contract_fragment(condition, value, root, path)
5487
- except APError:
5488
- pass
5489
- else:
5490
- then = fragment.get("then")
5491
- if isinstance(then, dict):
5492
- _validate_contract_fragment(then, value, root, path)
5674
+ if isinstance(condition, dict) and not _contract_validation_errors(
5675
+ condition, value, root, path
5676
+ ):
5677
+ then = fragment.get("then")
5678
+ if isinstance(then, dict):
5679
+ errors.extend(_contract_validation_errors(then, value, root, path))
5493
5680
 
5494
5681
  for child in fragment.get("allOf") or []:
5495
5682
  if isinstance(child, dict):
5496
- _validate_contract_fragment(child, value, root, path)
5683
+ errors.extend(_contract_validation_errors(child, value, root, path))
5684
+ return errors
5497
5685
 
5498
5686
 
5499
5687
  def _validate_orchestration_contract(kind: str, payload: dict) -> dict:
@@ -5507,28 +5695,85 @@ def _validate_orchestration_contract(kind: str, payload: dict) -> dict:
5507
5695
  if not definition:
5508
5696
  raise APError(f"Unknown orchestration contract kind: {kind}")
5509
5697
  root = _orchestration_schema()
5510
- _validate_contract_fragment(root["$defs"][definition], payload, root, "$")
5698
+ errors = _contract_validation_errors(root["$defs"][definition], payload, root, "$")
5511
5699
 
5512
5700
  role = _text(payload.get("role"))
5513
5701
  if kind == "assignment" and role == "reviewer":
5514
5702
  if _text(payload.get("node_id")) == _text(payload.get("owning_fixer")):
5515
- raise APError("Reviewer assignment node_id must differ from owning_fixer.")
5703
+ errors.append("$.node_id: reviewer must differ from owning_fixer")
5516
5704
  if kind == "result":
5517
- if role == "fixer":
5705
+ owned_paths = payload.get("owned_paths")
5706
+ changed_paths = payload.get("changed_paths")
5707
+ if role == "fixer" and isinstance(owned_paths, list) and isinstance(changed_paths, list):
5518
5708
  owned = [_normalize_owned_path(item) for item in payload.get("owned_paths") or []]
5519
5709
  outside = [
5520
5710
  path
5521
5711
  for path in payload.get("changed_paths") or []
5712
+ if isinstance(path, str)
5522
5713
  if not _path_is_owned(path, owned)
5523
5714
  ]
5524
5715
  if outside:
5525
- raise APError("Fixer result changed_paths exceed owned_paths: " + ", ".join(outside))
5716
+ errors.append(
5717
+ "$.changed_paths: fixer paths exceed owned_paths: " + ", ".join(outside)
5718
+ )
5526
5719
  if role == "reviewer" and _text(payload.get("verdict")) in {"approved", "changes-requested"}:
5527
5720
  if not re.fullmatch(r"[0-9a-f]{64}", _text(payload.get("diff_fingerprint"))):
5528
- raise APError("Reviewer result must bind its verdict to a non-empty diff fingerprint.")
5721
+ errors.append(
5722
+ "$.diff_fingerprint: reviewer verdict must bind to a 64-character fingerprint"
5723
+ )
5724
+ errors = list(dict.fromkeys(errors))
5725
+ if errors:
5726
+ raise APError("Contract validation failed:\n- " + "\n- ".join(errors))
5529
5727
  return payload
5530
5728
 
5531
5729
 
5730
+ def _reviewer_result_template(assignment: dict, verdict: str) -> dict:
5731
+ """Build a complete Reviewer result without guessing review evidence or findings."""
5732
+ _validate_orchestration_contract("assignment", assignment)
5733
+ if _text(assignment.get("role")) != "reviewer":
5734
+ raise APError("Reviewer result templates require a reviewer assignment.")
5735
+ normalized_verdict = _text(verdict).lower()
5736
+ if normalized_verdict not in {"approved", "changes-requested", "blocked"}:
5737
+ raise APError(
5738
+ "Reviewer result verdict must be approved, changes-requested, or blocked."
5739
+ )
5740
+ fingerprint = _text(assignment.get("diff_fingerprint"))
5741
+ if not re.fullmatch(r"[0-9a-f]{64}", fingerprint):
5742
+ raise APError(
5743
+ "Reviewer result templates require a non-empty 64-character diff fingerprint."
5744
+ )
5745
+ status = "blocked" if normalized_verdict == "blocked" else "completed"
5746
+ next_owner = (
5747
+ _text(assignment.get("owning_fixer"))
5748
+ if normalized_verdict == "changes-requested"
5749
+ else "main"
5750
+ )
5751
+ summaries = {
5752
+ "approved": "Review completed with no blocking findings.",
5753
+ "changes-requested": "Review completed with changes requested.",
5754
+ "blocked": "Review could not be completed.",
5755
+ }
5756
+ result = {
5757
+ "contract_version": _AGENT_CONTRACT_VERSION,
5758
+ "node_id": _text(assignment.get("node_id")),
5759
+ "role": "reviewer",
5760
+ "task_id": _text(assignment.get("task_id")),
5761
+ "base_sha": _text(assignment.get("base_sha")),
5762
+ "status": status,
5763
+ "summary": summaries[normalized_verdict],
5764
+ "depends_on": list(assignment.get("depends_on") or []),
5765
+ "owned_paths": [],
5766
+ "changed_paths": [],
5767
+ "diff_fingerprint": fingerprint,
5768
+ "evidence": [],
5769
+ "findings": [],
5770
+ "verdict": normalized_verdict,
5771
+ "risks": [],
5772
+ "next_owner": next_owner,
5773
+ }
5774
+ return _validate_orchestration_contract("result", result)
5775
+
5776
+
5532
5777
  def _validate_agent_plan(plan: dict) -> dict:
5533
5778
  required = {
5534
5779
  "contract_version",
@@ -5548,6 +5793,35 @@ def _validate_agent_plan(plan: dict) -> dict:
5548
5793
  return plan
5549
5794
 
5550
5795
 
5796
+ def _review_execution_policy(
5797
+ *,
5798
+ review_required: bool,
5799
+ categories: set[str],
5800
+ cross_module: bool,
5801
+ parallel_writers: int,
5802
+ ) -> dict:
5803
+ if not review_required:
5804
+ return {
5805
+ "depth": "none",
5806
+ "agent": "",
5807
+ "timeout_seconds": 0,
5808
+ "analysis_attempt_limit": 0,
5809
+ }
5810
+ deep = bool(
5811
+ cross_module
5812
+ or parallel_writers > 1
5813
+ or categories & _DEEP_REVIEW_CATEGORIES
5814
+ )
5815
+ return {
5816
+ "depth": "deep" if deep else "focused",
5817
+ "agent": "reviewer",
5818
+ "timeout_seconds": (
5819
+ _DEEP_REVIEW_TIMEOUT_SECONDS if deep else _FOCUSED_REVIEW_TIMEOUT_SECONDS
5820
+ ),
5821
+ "analysis_attempt_limit": 1,
5822
+ }
5823
+
5824
+
5551
5825
  def _agent_execution_plan(
5552
5826
  profile: str,
5553
5827
  categories: set[str],
@@ -5555,10 +5829,12 @@ def _agent_execution_plan(
5555
5829
  *,
5556
5830
  parallel_writers: int = 1,
5557
5831
  review_required: bool = False,
5832
+ review_policy: Optional[dict] = None,
5558
5833
  optional_roles: Optional[list[str]] = None,
5559
5834
  ) -> dict:
5560
5835
  assignment_contract, result_contract = _agent_contract_shape()
5561
5836
  optional_roles = list(dict.fromkeys(optional_roles or []))
5837
+ review_policy = dict(review_policy or {})
5562
5838
  # Optional roles are candidates, never automatic stages. The model selects
5563
5839
  # them only when expected benefit exceeds coordination cost.
5564
5840
  discovery_roles: list[str] = []
@@ -5570,6 +5846,12 @@ def _agent_execution_plan(
5570
5846
  "dependency_policy": "integrate-before-dependent-start",
5571
5847
  "review_feedback_owner": "owning-fixer" if review_required else "main",
5572
5848
  "review_binding": "diff-fingerprint-when-required",
5849
+ "review_depth": _text(review_policy.get("depth")) or "none",
5850
+ "review_agent": _text(review_policy.get("agent")),
5851
+ "review_timeout_seconds": int(review_policy.get("timeout_seconds") or 0),
5852
+ "review_analysis_attempt_limit": int(
5853
+ review_policy.get("analysis_attempt_limit") or 0
5854
+ ),
5573
5855
  "lifecycle_owner": "main",
5574
5856
  "gate_owner": "main",
5575
5857
  }
@@ -5579,6 +5861,11 @@ def _agent_execution_plan(
5579
5861
  "Never run two writers in one worktree.",
5580
5862
  "The main agent runs one final changed-scope gate, pushes, and cleans only temporary branches actually created.",
5581
5863
  ]
5864
+ if review_required:
5865
+ constraints.append(
5866
+ "Run one bounded review analysis over the supplied diff and relevant evidence; "
5867
+ "a timeout is blocked, never approved, and JSON formatting repair must reuse the same analysis."
5868
+ )
5582
5869
 
5583
5870
  if parallel_writers <= 1 and not discovery_roles and not review_required:
5584
5871
  stages = [{"id": "delivery", "mode": "serial", "roles": ["main"], "depends_on": []}]
@@ -5604,7 +5891,7 @@ def _agent_execution_plan(
5604
5891
  delivery_roles = ["fixer", "main"]
5605
5892
  delivery_mode = "parallel-isolated"
5606
5893
  if review_required:
5607
- delivery_roles.append("reviewer")
5894
+ delivery_roles.append(_text(review_policy.get("agent")) or "reviewer")
5608
5895
  stages.append(
5609
5896
  {
5610
5897
  "id": "delivery",
@@ -5687,7 +5974,8 @@ def _mechanism_plan(
5687
5974
  "rule": (
5688
5975
  "run required mechanisms; select optional mechanisms only when expected value exceeds "
5689
5976
  "coordination cost; reclassify before changing writer count; do not run forbidden "
5690
- "mechanisms unless the user explicitly overrides"
5977
+ "mechanisms unless the user explicitly overrides; direct/worktree decisions apply only "
5978
+ "to the reported workspace snapshot and require reclassification if it changes"
5691
5979
  ),
5692
5980
  }
5693
5981
 
@@ -5721,6 +6009,13 @@ def _resolve_execution_plan(
5721
6009
  )
5722
6010
  classification_inputs = [*paths, *normalized_planned_paths]
5723
6011
  task_kind = _resolve_task_kind(requested_task_kind, classification_inputs, intent)
6012
+ change_nature = _classify_change_nature(
6013
+ repo,
6014
+ base_ref=base_ref,
6015
+ changed_paths=paths,
6016
+ intent=intent,
6017
+ inspect_git=changed_paths is None,
6018
+ )
5724
6019
  path_classification = _classify_paths(classification_inputs)
5725
6020
  path_categories = set(path_classification["categories"])
5726
6021
  intent_categories = _classify_intent(intent)
@@ -5861,7 +6156,14 @@ def _resolve_execution_plan(
5861
6156
  )
5862
6157
  design_required = bool(
5863
6158
  task_kind == "change"
5864
- and (rule_design or (effective_profile == "high-risk" and cross_module))
6159
+ and (
6160
+ rule_design
6161
+ or (
6162
+ effective_profile == "high-risk"
6163
+ and cross_module
6164
+ and change_nature != "mechanical"
6165
+ )
6166
+ )
5865
6167
  )
5866
6168
  dirty_paths = _working_tree_paths(repo)
5867
6169
  workspace_dirty = bool(dirty_paths)
@@ -5879,12 +6181,10 @@ def _resolve_execution_plan(
5879
6181
  if continue_direct
5880
6182
  else {}
5881
6183
  )
5882
- runtime_actor = _text(os.environ.get("CODEX_THREAD_ID"))
5883
6184
  other_direct_claims = [
5884
6185
  item
5885
6186
  for item in _active_direct_claims(repo)
5886
6187
  if _text(item.get("claim_id")) != _text(direct_claim_id)
5887
- and (not runtime_actor or _text(item.get("owner")) != runtime_actor)
5888
6188
  ]
5889
6189
  active_writer = bool(registered_active_writer or other_direct_claims)
5890
6190
  continued_direct = bool(
@@ -5922,12 +6222,19 @@ def _resolve_execution_plan(
5922
6222
  cross_module=cross_module,
5923
6223
  profile=effective_profile,
5924
6224
  )
6225
+ review_policy = _review_execution_policy(
6226
+ review_required=review_required,
6227
+ categories=categories,
6228
+ cross_module=cross_module,
6229
+ parallel_writers=writer_count,
6230
+ )
5925
6231
  agent_plan = _agent_execution_plan(
5926
6232
  effective_profile,
5927
6233
  categories,
5928
6234
  classification,
5929
6235
  parallel_writers=writer_count,
5930
6236
  review_required=review_required,
6237
+ review_policy=review_policy,
5931
6238
  optional_roles=optional_agents,
5932
6239
  )
5933
6240
  mechanism_plan = _mechanism_plan(
@@ -5944,6 +6251,7 @@ def _resolve_execution_plan(
5944
6251
  "planned_files": normalized_planned_paths,
5945
6252
  "classification_files": classification_inputs,
5946
6253
  "intent_provided": bool(_text(intent)),
6254
+ "change_nature": change_nature,
5947
6255
  "task_kind": task_kind,
5948
6256
  "intent_categories": intent_categories,
5949
6257
  "intent_risk_candidates": intent_risk_candidates,
@@ -5958,6 +6266,7 @@ def _resolve_execution_plan(
5958
6266
  "effective_mode": effective_mode,
5959
6267
  "execution_mode": execution_mode,
5960
6268
  "terminal_maintenance": terminal_maintenance,
6269
+ "repo": str(repo),
5961
6270
  "workspace_dirty": workspace_dirty,
5962
6271
  "dirty_paths": dirty_paths,
5963
6272
  "dirty_outside_plan": dirty_outside_plan,
@@ -5966,6 +6275,10 @@ def _resolve_execution_plan(
5966
6275
  "parallel_writers": writer_count,
5967
6276
  "cross_module": cross_module,
5968
6277
  "review_required": review_required,
6278
+ "review_depth": review_policy["depth"],
6279
+ "review_agent": review_policy["agent"],
6280
+ "review_timeout_seconds": review_policy["timeout_seconds"],
6281
+ "review_analysis_attempt_limit": review_policy["analysis_attempt_limit"],
5969
6282
  "design_required": design_required,
5970
6283
  "selected_scope": selected_scope,
5971
6284
  "categories": sorted(categories),
@@ -5980,6 +6293,7 @@ def _resolve_execution_plan(
5980
6293
  classification,
5981
6294
  parallel_writers=writer_count,
5982
6295
  review_required=review_required,
6296
+ review_policy=review_policy,
5983
6297
  ),
5984
6298
  "optional_agents": optional_agents,
5985
6299
  "agent_plan": agent_plan,
@@ -6056,9 +6370,24 @@ def cmd_classify(args: argparse.Namespace) -> None:
6056
6370
  print(f"[classify] task_kind={result['task_kind']}")
6057
6371
  print(f"[classify] profile={result['profile']}")
6058
6372
  print(f"[classify] effective_mode={result['effective_mode']}")
6373
+ print(f"[classify] repo={result['repo']}")
6374
+ print(f"[classify] workspace_dirty={str(result['workspace_dirty']).lower()}")
6375
+ print(
6376
+ "[classify] dirty_paths="
6377
+ + json.dumps(result["dirty_paths"], ensure_ascii=False, separators=(",", ":"))
6378
+ )
6379
+ print(f"[classify] active_writer={str(result['active_writer']).lower()}")
6059
6380
  print(f"[classify] execution_mode={result['execution_mode']}")
6060
6381
  print(f"[classify] review_required={str(result['review_required']).lower()}")
6382
+ print(f"[classify] review_depth={result['review_depth']}")
6383
+ print(f"[classify] review_agent={result['review_agent'] or '(none)'}")
6384
+ print(f"[classify] review_timeout_seconds={result['review_timeout_seconds']}")
6385
+ print(
6386
+ "[classify] review_analysis_attempt_limit="
6387
+ f"{result['review_analysis_attempt_limit']}"
6388
+ )
6061
6389
  print(f"[classify] design_required={str(result['design_required']).lower()}")
6390
+ print(f"[classify] change_nature={result['change_nature']}")
6062
6391
  print(f"[classify] selected_scope={result['selected_scope']}")
6063
6392
  print("[classify] categories=" + (", ".join(result["categories"]) or "(none)"))
6064
6393
  print("[classify] agents=" + (", ".join(result["recommended_agents"]) or "(main agent only)"))
@@ -6094,8 +6423,7 @@ def cmd_classify(args: argparse.Namespace) -> None:
6094
6423
  _record_evidence(repo, cfg, "classify", "pass", result)
6095
6424
 
6096
6425
 
6097
- def cmd_agent_contract_check(args: argparse.Namespace) -> None:
6098
- repo = Path(args.repo).resolve()
6426
+ def _agent_contract_payload(repo: Path, args: argparse.Namespace) -> dict:
6099
6427
  raw = _text(getattr(args, "payload", ""))
6100
6428
  source = _text(getattr(args, "file", ""))
6101
6429
  if source:
@@ -6119,6 +6447,12 @@ def cmd_agent_contract_check(args: argparse.Namespace) -> None:
6119
6447
  raise APError(f"Agent contract payload is not valid JSON: {exc}") from exc
6120
6448
  if not isinstance(payload, dict):
6121
6449
  raise APError("Agent contract payload must be a JSON object.")
6450
+ return payload
6451
+
6452
+
6453
+ def cmd_agent_contract_check(args: argparse.Namespace) -> None:
6454
+ repo = Path(args.repo).resolve()
6455
+ payload = _agent_contract_payload(repo, args)
6122
6456
  _validate_orchestration_contract(args.kind, payload)
6123
6457
  result = {"valid": True, "kind": args.kind}
6124
6458
  if args.json:
@@ -6127,6 +6461,13 @@ def cmd_agent_contract_check(args: argparse.Namespace) -> None:
6127
6461
  print(f"[agent-contract-check] OK kind={args.kind}")
6128
6462
 
6129
6463
 
6464
+ def cmd_agent_result_template(args: argparse.Namespace) -> None:
6465
+ repo = Path(args.repo).resolve()
6466
+ assignment = _agent_contract_payload(repo, args)
6467
+ result = _reviewer_result_template(assignment, args.verdict)
6468
+ print(json.dumps(result, ensure_ascii=False, indent=2))
6469
+
6470
+
6130
6471
  def cmd_run(args: argparse.Namespace) -> None:
6131
6472
  """
6132
6473
  Run any configured gate command by name.
@@ -9458,6 +9799,20 @@ def main(argv: Optional[List[str]] = None) -> int:
9458
9799
  s.add_argument("--json", action="store_true")
9459
9800
  s.set_defaults(func=cmd_agent_contract_check)
9460
9801
 
9802
+ s = sp.add_parser(
9803
+ "agent-result-template",
9804
+ help="Generate a complete reviewer result from a validated assignment",
9805
+ )
9806
+ source = s.add_mutually_exclusive_group(required=True)
9807
+ source.add_argument("--file")
9808
+ source.add_argument("--payload")
9809
+ s.add_argument(
9810
+ "--verdict",
9811
+ choices=["approved", "changes-requested", "blocked"],
9812
+ required=True,
9813
+ )
9814
+ s.set_defaults(func=cmd_agent_result_template)
9815
+
9461
9816
  s = sp.add_parser("validation-map-check")
9462
9817
  s.add_argument("--base")
9463
9818
  s.add_argument("--path", action="append")