@elvis1513/auto-coding-skill 2.1.3 → 2.2.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.
Files changed (30) hide show
  1. package/README.md +154 -548
  2. package/cli/assets/agents/browser-debugger.toml +0 -1
  3. package/cli/assets/agents/docs-researcher.toml +0 -1
  4. package/cli/assets/agents/explorer.toml +1 -2
  5. package/cli/assets/agents/fixer.toml +2 -3
  6. package/cli/assets/agents/reviewer.toml +1 -2
  7. package/cli/assets/skill/SKILL.md +98 -207
  8. package/cli/assets/skill/data/templates/ENGINEERING.md +113 -468
  9. package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +11 -22
  10. package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +16 -39
  11. package/cli/assets/skill/data/templates/tools/ap.py +16 -0
  12. package/cli/assets/skill/scripts/ap.py +666 -129
  13. package/cli/assets/skill/scripts/scaffold_templates.py +136 -0
  14. package/cli/src/index.js +317 -42
  15. package/cli/tests/ap_profiles_test.py +428 -0
  16. package/cli/tests/index.test.js +373 -62
  17. package/package.json +3 -3
  18. package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +0 -38
  19. package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +0 -92
  20. package/cli/assets/skill/data/templates/docs/bugs/bug-list.md +0 -5
  21. package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +0 -19
  22. package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +0 -11
  23. package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +0 -49
  24. package/cli/assets/skill/data/templates/docs/interfaces/api-change-log.md +0 -11
  25. package/cli/assets/skill/data/templates/docs/interfaces/api.md +0 -36
  26. package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +0 -36
  27. package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +0 -25
  28. package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +0 -66
  29. package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +0 -35
  30. package/cli/assets/skill/data/templates/docs/testing/regression-matrix.md +0 -11
@@ -26,6 +26,7 @@ except Exception:
26
26
  yaml = None
27
27
 
28
28
  from core import APError, ensure_git_repo, copy_tree, run, load_yaml, find_config, run_shell, http_get_status
29
+ from scaffold_templates import scaffold_groups, templates_for
29
30
 
30
31
 
31
32
  _JENKINS_CRUMB_CACHE: dict[str, dict[str, str]] = {}
@@ -489,25 +490,105 @@ _MANAGED_EXTRA_CLEANUP_DIRS = {
489
490
  Path("data/templates/bridges"),
490
491
  }
491
492
 
493
+ _CORE_DOC_TEMPLATES = [
494
+ Path("tasks/taskbook.md"),
495
+ Path("tasks/closure-log.md"),
496
+ ]
497
+
498
+
499
+ def _inferred_gate_commands(repo: Path) -> dict[str, str]:
500
+ package_json = repo / "package.json"
501
+ if not package_json.exists():
502
+ return {}
503
+ try:
504
+ payload = json.loads(package_json.read_text(encoding="utf-8"))
505
+ except Exception:
506
+ return {}
507
+ scripts = payload.get("scripts") or {}
508
+ if not isinstance(scripts, dict):
509
+ return {}
510
+ inferred: dict[str, str] = {}
511
+ if isinstance(scripts.get("test"), str) and scripts["test"].strip():
512
+ inferred["gate_changed"] = (
513
+ "npm run test:changed"
514
+ if isinstance(scripts.get("test:changed"), str) and scripts["test:changed"].strip()
515
+ else "npm test"
516
+ )
517
+ inferred["gate_standard"] = (
518
+ "npm run test:standard"
519
+ if isinstance(scripts.get("test:standard"), str) and scripts["test:standard"].strip()
520
+ else "npm test"
521
+ )
522
+ if isinstance(scripts.get("test:full"), str) and scripts["test:full"].strip():
523
+ inferred["gate_full"] = "npm run test:full"
524
+ return inferred
525
+
526
+
527
+ def _initialize_engineering_defaults(path: Path, repo: Path) -> None:
528
+ if not path.exists():
529
+ return
530
+ text = path.read_text(encoding="utf-8")
531
+ updated = text.replace(
532
+ 'project:\n name: ""',
533
+ f"project:\n name: {json.dumps(repo.name, ensure_ascii=False)}",
534
+ 1,
535
+ )
536
+ for key, gate_command in _inferred_gate_commands(repo).items():
537
+ updated = updated.replace(
538
+ f' {key}: ""',
539
+ f" {key}: {json.dumps(gate_command)}",
540
+ 1,
541
+ )
542
+ if updated != text:
543
+ path.write_text(updated, encoding="utf-8")
544
+
545
+
546
+ def cmd_scaffold(args: argparse.Namespace) -> None:
547
+ repo = Path(args.repo).resolve()
548
+ group = str(args.group or "").strip().lower()
549
+ try:
550
+ selected = templates_for(group)
551
+ except KeyError as exc:
552
+ choices = ", ".join(scaffold_groups() + ["all"])
553
+ raise APError(f"Unknown scaffold group '{group}'. Choose one of: {choices}") from exc
554
+
555
+ write = bool(args.write)
556
+ force = bool(args.force)
557
+ actions: list[dict] = []
558
+ for rel, content in sorted(selected.items()):
559
+ path = repo / rel
560
+ if path.exists() and not force:
561
+ actions.append({"path": rel, "action": "exists"})
562
+ continue
563
+ action = "write" if write else "would-write"
564
+ actions.append({"path": rel, "action": action})
565
+ if write:
566
+ path.parent.mkdir(parents=True, exist_ok=True)
567
+ path.write_text(content, encoding="utf-8")
568
+
569
+ result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
570
+ if args.json:
571
+ print(json.dumps(result, ensure_ascii=False, indent=2))
572
+ return
573
+ for item in actions:
574
+ print(f"[scaffold] {item['action']}: {item['path']}")
575
+ if not write:
576
+ print("[scaffold] plan only; re-run with --write to create missing files")
577
+
492
578
 
493
579
  def cmd_install(args: argparse.Namespace) -> None:
494
580
  repo = Path(args.repo).resolve()
495
581
  templates = _skill_root() / "data" / "templates"
496
582
 
497
- planned_copies = [
498
- (templates / "docs", repo / "docs"),
499
- (templates / "ENGINEERING.md", repo / "docs" / "ENGINEERING.md"),
500
- ]
583
+ planned_copies = [(templates / "ENGINEERING.md", repo / "docs" / "ENGINEERING.md")]
584
+ for rel in _CORE_DOC_TEMPLATES:
585
+ planned_copies.append((templates / "docs" / rel, repo / "docs" / rel))
501
586
 
502
587
  if args.bridges:
503
588
  planned_copies.append((templates / "bridges" / "AGENTS.md", repo / "AGENTS.md"))
504
589
 
505
590
  tools_dir = repo / "docs" / "tools" / "autopipeline"
506
- planned_copies.extend([
507
- (Path(__file__).resolve(), tools_dir / "ap.py"),
508
- (Path(__file__).resolve().parent / "core.py", tools_dir / "core.py"),
509
- (Path(__file__).resolve().parent / "http_checks.py", tools_dir / "http_checks.py"),
510
- ])
591
+ planned_copies.append((templates / "tools" / "ap.py", tools_dir / "ap.py"))
511
592
 
512
593
  conflicts: list[Path] = []
513
594
  for src, dst in planned_copies:
@@ -525,7 +606,14 @@ def cmd_install(args: argparse.Namespace) -> None:
525
606
  for src, dst in planned_copies:
526
607
  copy_tree(src, dst)
527
608
 
528
- print(f"[install] OK: scaffold installed into {repo}")
609
+ _initialize_engineering_defaults(repo / "docs" / "ENGINEERING.md", repo)
610
+ if args.full:
611
+ cmd_scaffold(
612
+ argparse.Namespace(repo=str(repo), group="all", write=True, force=args.force, json=False)
613
+ )
614
+
615
+ layout = "full" if args.full else "minimal"
616
+ print(f"[install] OK: {layout} scaffold installed into {repo}")
529
617
  print(
530
618
  "[install] Next: edit docs/ENGINEERING.md frontmatter, set verification.*_required, "
531
619
  "fill only enabled environment fields, and commit that file into Git."
@@ -549,9 +637,10 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
549
637
  })
550
638
 
551
639
  tool_files = [
552
- (source_root / "scripts" / "ap.py", repo / "docs" / "tools" / "autopipeline" / "ap.py"),
553
- (source_root / "scripts" / "core.py", repo / "docs" / "tools" / "autopipeline" / "core.py"),
554
- (source_root / "scripts" / "http_checks.py", repo / "docs" / "tools" / "autopipeline" / "http_checks.py"),
640
+ (
641
+ source_root / "data" / "templates" / "tools" / "ap.py",
642
+ repo / "docs" / "tools" / "autopipeline" / "ap.py",
643
+ ),
555
644
  ]
556
645
  for src, dst in tool_files:
557
646
  if not src.exists():
@@ -585,6 +674,8 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
585
674
  for dst in _iter_files(project_skill):
586
675
  rel = dst.relative_to(project_skill)
587
676
  if not (source_root / rel).exists():
677
+ if rel.parts[:3] == ("data", "templates", "docs"):
678
+ continue
588
679
  if rel.parent in _MANAGED_EXTRA_CLEANUP_DIRS:
589
680
  add_action("skill", dst, "delete", "stale managed template")
590
681
  if write:
@@ -592,11 +683,15 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
592
683
  else:
593
684
  add_action("skill", dst, "extra", "present only in project copy")
594
685
  else:
595
- add_action("skill", project_skill, "missing", "run autocoding init --mode project --force")
686
+ add_action("skill", project_skill, "create", "install runtime required by the project launcher")
687
+ if write:
688
+ copy_tree(source_root, project_skill)
596
689
 
597
690
  docs_template = templates / "docs"
598
- for src in _iter_files(docs_template):
599
- rel = src.relative_to(docs_template)
691
+ for rel in _CORE_DOC_TEMPLATES:
692
+ src = docs_template / rel
693
+ if not src.exists():
694
+ continue
600
695
  dst = repo / "docs" / rel
601
696
  if not dst.exists():
602
697
  add_action("doc", dst, "create")
@@ -624,6 +719,7 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
624
719
  add_action("config", engineering, "create")
625
720
  if write:
626
721
  copy_tree(template_engineering, engineering)
722
+ _initialize_engineering_defaults(engineering, repo)
627
723
 
628
724
  result = {
629
725
  "source_root": str(source_root),
@@ -746,7 +842,9 @@ def cmd_check_matrix(args: argparse.Namespace) -> None:
746
842
  docs_cfg = (cfg.get("docs") or {})
747
843
  matrix = Path(repo, str(docs_cfg.get("regression_matrix", "docs/testing/regression-matrix.md")))
748
844
  if not matrix.exists():
749
- raise APError(f"Matrix not found: {matrix}")
845
+ raise APError(
846
+ f"Matrix not found: {matrix}. Create it with `ap.py scaffold testing --write`."
847
+ )
750
848
 
751
849
  rows = 0
752
850
  fail = []
@@ -813,15 +911,9 @@ def _candidate_skill_roots(repo: Path) -> list[Path]:
813
911
  project_root = repo / ".agents" / "skills" / "auto-coding-skill"
814
912
  global_root = Path.home() / ".agents" / "skills" / "auto-coding-skill"
815
913
 
816
- # When upgrade is launched from a project-local skill copy, that copy may be
817
- # stale. Prefer an external source or the global installation, and use the
818
- # project-local copy only as a last resort.
819
- candidates = []
820
- if local_root != project_root:
821
- candidates.append(local_root)
822
- candidates.extend([global_root, project_root])
823
- if local_root == project_root:
824
- candidates.append(local_root)
914
+ # The runtime executing this command is authoritative. In particular, a
915
+ # modern project copy must not be overwritten by an older global copy.
916
+ candidates = [local_root, project_root, global_root]
825
917
 
826
918
  unique: list[Path] = []
827
919
  seen: set[Path] = set()
@@ -834,8 +926,23 @@ def _candidate_skill_roots(repo: Path) -> list[Path]:
834
926
 
835
927
 
836
928
  def _find_skill_asset_root(repo: Path) -> Path:
837
- for root in _candidate_skill_roots(repo):
838
- if (root / "data" / "templates").exists() and (root / "scripts" / "ap.py").exists():
929
+ candidates = _candidate_skill_roots(repo)
930
+
931
+ def is_asset_root(root: Path) -> bool:
932
+ return (root / "data" / "templates").exists() and (root / "scripts" / "ap.py").exists()
933
+
934
+ def has_modern_layout(root: Path) -> bool:
935
+ return (
936
+ is_asset_root(root)
937
+ and (root / "data" / "templates" / "tools" / "ap.py").exists()
938
+ and (root / "scripts" / "scaffold_templates.py").exists()
939
+ )
940
+
941
+ for root in candidates:
942
+ if has_modern_layout(root):
943
+ return root
944
+ for root in candidates:
945
+ if is_asset_root(root):
839
946
  return root
840
947
  raise APError(
841
948
  "Cannot find auto-coding-skill asset root. Run `autocoding init --mode global --force` "
@@ -987,6 +1094,10 @@ def _resolve_secret(section_name: str, section_cfg: dict, field: str) -> str:
987
1094
 
988
1095
 
989
1096
  _GATE_SCOPES = {"auto", "changed", "standard", "full"}
1097
+ _WORKFLOW_PROFILES = {"auto", "micro", "standard", "high-risk"}
1098
+ _PROFILE_GATE_SCOPE = {"micro": "changed", "standard": "standard", "high-risk": "full"}
1099
+ _PROFILE_RANK = {"micro": 0, "standard": 1, "high-risk": 2}
1100
+ _SCOPE_RANK = {"changed": 0, "standard": 1, "full": 2}
990
1101
  _DOC_PATH_PATTERNS = ["*.md", "docs/**"]
991
1102
  _DEFAULT_FULL_PATH_PATTERNS = [
992
1103
  ".agents/**",
@@ -1124,6 +1235,27 @@ def _changed_files(repo: Path, base_ref: str = "") -> list[str]:
1124
1235
  return _unique_paths(paths)
1125
1236
 
1126
1237
 
1238
+ def _commit_changed_files(repo: Path, ref: str) -> list[str]:
1239
+ commit_ref = _text(ref) or "HEAD"
1240
+ result = run(
1241
+ [
1242
+ "git",
1243
+ "diff-tree",
1244
+ "--root",
1245
+ "--no-commit-id",
1246
+ "--name-only",
1247
+ "-r",
1248
+ "--diff-filter=ACMRTUXB",
1249
+ commit_ref,
1250
+ ],
1251
+ cwd=repo,
1252
+ check=False,
1253
+ )
1254
+ if result.returncode != 0:
1255
+ return []
1256
+ return _unique_paths([line.strip() for line in result.stdout.splitlines() if line.strip()])
1257
+
1258
+
1127
1259
  def _cleanup_generated_noise(repo: Path) -> None:
1128
1260
  candidates = [
1129
1261
  rel for rel in _git_lines(repo, ["git", "ls-files", "--others", "--exclude-standard"])
@@ -1147,6 +1279,16 @@ def _docs_only(paths: list[str]) -> bool:
1147
1279
  return bool(paths) and all(_path_matches(path, _DOC_PATH_PATTERNS) for path in paths)
1148
1280
 
1149
1281
 
1282
+ def _tests_only(paths: list[str]) -> bool:
1283
+ non_docs = [path for path in paths if not _path_matches(path, _DOC_PATH_PATTERNS)]
1284
+ if not non_docs:
1285
+ return False
1286
+ return all(
1287
+ re.search(r"(^|[/_.-])(test|tests|spec|specs)([/_.-]|$)", path.lower())
1288
+ for path in non_docs
1289
+ )
1290
+
1291
+
1150
1292
  def _gate_rules(gate_cfg: dict) -> list[dict]:
1151
1293
  rules = gate_cfg.get("rules") or []
1152
1294
  return [rule for rule in rules if isinstance(rule, dict)]
@@ -1189,6 +1331,12 @@ def _select_gate_scope(cfg: dict, requested_scope: str, paths: list[str]) -> tup
1189
1331
  matching_rules = _matching_gate_rules(paths, gate_cfg)
1190
1332
  reasons: list[str] = []
1191
1333
 
1334
+ rule_scopes = {_text(rule.get("scope")).lower() for rule in matching_rules if _text(rule.get("scope"))}
1335
+ if "full" in rule_scopes:
1336
+ return "full", ["matched gate rule with scope=full"], matching_rules
1337
+ if any(_path_matches(path, _gate_full_patterns(gate_cfg)) for path in paths):
1338
+ return "full", ["changed files match full-gate patterns"], matching_rules
1339
+
1192
1340
  if scope != "auto":
1193
1341
  return scope, [f"requested scope: {scope}"], matching_rules
1194
1342
 
@@ -1198,15 +1346,9 @@ def _select_gate_scope(cfg: dict, requested_scope: str, paths: list[str]) -> tup
1198
1346
  fallback = "standard"
1199
1347
  return fallback, ["no changed files detected"], matching_rules
1200
1348
 
1201
- rule_scopes = {_text(rule.get("scope")).lower() for rule in matching_rules if _text(rule.get("scope"))}
1202
- if "full" in rule_scopes:
1203
- return "full", ["matched gate rule with scope=full"], matching_rules
1204
1349
  if "standard" in rule_scopes:
1205
1350
  return "standard", ["matched gate rule with scope=standard"], matching_rules
1206
1351
 
1207
- if any(_path_matches(path, _gate_full_patterns(gate_cfg)) for path in paths):
1208
- return "full", ["changed files match full-gate patterns"], matching_rules
1209
-
1210
1352
  if _docs_only(paths):
1211
1353
  return "changed", ["docs-only change"], matching_rules
1212
1354
 
@@ -1222,8 +1364,25 @@ def _select_gate_scope(cfg: dict, requested_scope: str, paths: list[str]) -> tup
1222
1364
  return fallback, reasons, matching_rules
1223
1365
 
1224
1366
 
1225
- def _impact_summary(cfg: dict, repo: Path, requested_scope: str, base_ref: str = "") -> dict:
1226
- paths = _changed_files(repo, base_ref=base_ref)
1367
+ def _impact_summary(
1368
+ cfg: dict,
1369
+ repo: Path,
1370
+ requested_scope: str,
1371
+ base_ref: str = "",
1372
+ changed_paths: Optional[list[str]] = None,
1373
+ ) -> dict:
1374
+ paths = _changed_files(repo, base_ref=base_ref) if changed_paths is None else _unique_paths(changed_paths)
1375
+ docs_cfg = cfg.get("docs") or {}
1376
+ ignored_runtime_paths = {
1377
+ _text(docs_cfg.get("evidence_log")) or "docs/tasks/evidence.jsonl",
1378
+ _text(docs_cfg.get("closure_log")) or "docs/tasks/closure-log.md",
1379
+ _text(_gate_cfg(cfg).get("profile_log")) or ".local/auto-coding-skill/gate-profile.jsonl",
1380
+ }
1381
+ ignored_runtime_paths = {
1382
+ path[2:] if path.startswith("./") else path
1383
+ for path in ignored_runtime_paths
1384
+ }
1385
+ paths = [path for path in paths if path not in ignored_runtime_paths]
1227
1386
  scope, reasons, matching_rules = _select_gate_scope(cfg, requested_scope, paths)
1228
1387
  return {
1229
1388
  "requested_scope": requested_scope or _text(_gate_cfg(cfg).get("default_scope")) or "standard",
@@ -1240,6 +1399,10 @@ def _print_impact(summary: dict, as_json: bool = False) -> None:
1240
1399
  return
1241
1400
  print(f"[impact] requested_scope={summary['requested_scope']}")
1242
1401
  print(f"[impact] selected_scope={summary['selected_scope']}")
1402
+ if summary.get("profile"):
1403
+ print(f"[impact] profile={summary['profile']}")
1404
+ if summary.get("effective_mode"):
1405
+ print(f"[impact] effective_mode={summary['effective_mode']}")
1243
1406
  for reason in summary.get("reasons") or []:
1244
1407
  print(f"[impact] reason: {reason}")
1245
1408
  for rule in summary.get("matched_rules") or []:
@@ -1291,11 +1454,11 @@ def _run_standard_gate(repo: Path, cfg: dict) -> list[str]:
1291
1454
 
1292
1455
 
1293
1456
  def _run_full_gate(repo: Path, cfg: dict) -> list[str]:
1294
- command = _run_first_configured_command(repo, cfg, ["gate_full", "full_gate", "gate_standard", "light_gate", "test", "build"])
1457
+ command = _run_first_configured_command(repo, cfg, ["gate_full", "full_gate"])
1295
1458
  if not command:
1296
1459
  raise APError(
1297
- "Full gate is under-configured. Add commands.gate_full, commands.full_gate, commands.test, "
1298
- "commands.build, or commands.light_gate."
1460
+ "Full gate is under-configured. High-risk and verify work requires "
1461
+ "commands.gate_full or commands.full_gate; light/standard fallbacks do not count."
1299
1462
  )
1300
1463
  return [command]
1301
1464
 
@@ -1782,9 +1945,6 @@ def _docs_ledger_check_result(repo: Path, cfg: dict) -> dict:
1782
1945
  blocking.append(f"docs.taskbook missing or unreadable: {_repo_rel(repo, taskbook)}")
1783
1946
  if closure_lines is None:
1784
1947
  blocking.append(f"docs.closure_log missing or unreadable: {_repo_rel(repo, closure_log)}")
1785
- if not design_dir.exists() or not design_dir.is_dir():
1786
- blocking.append(f"docs.design_dir missing on disk: {_repo_rel(repo, design_dir)}")
1787
-
1788
1948
  if taskbook_lines is not None and taskbook_max > 0 and taskbook_lines > taskbook_max:
1789
1949
  exceeded.append("taskbook")
1790
1950
  _ledger_message(
@@ -2242,6 +2402,9 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
2242
2402
 
2243
2403
  structure_cfg = _structure_cfg(cfg)
2244
2404
  optimization_cfg = _optimization_cfg(cfg)
2405
+ enforcement = _text(structure_cfg.get("enforcement")).lower() or "advisory"
2406
+ if enforcement not in {"advisory", "blocking"}:
2407
+ raise APError("structure.enforcement must be 'advisory' or 'blocking'")
2245
2408
  warn_file_lines = _int_config(structure_cfg.get("max_file_lines_warn"), 800)
2246
2409
  block_file_lines = _int_config(structure_cfg.get("max_file_lines_block"), 1500)
2247
2410
  warn_function_lines = _int_config(structure_cfg.get("max_function_lines_warn"), 120)
@@ -2294,18 +2457,25 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
2294
2457
  else:
2295
2458
  warnings.extend(boundary_issues)
2296
2459
 
2297
- missing_docs: list[str] = []
2298
- for key, rel_path in _configured_structure_docs(cfg).items():
2299
- if rel_path and not Path(repo, rel_path).exists():
2300
- missing_docs.append(f"{key} missing on disk: {rel_path}")
2301
2460
  require_baseline = _bool_config(optimization_cfg.get("require_baseline_for_global_review"), True)
2302
- if missing_docs and selected_scope == "full" and require_baseline:
2303
- blocking.extend(missing_docs)
2304
- else:
2305
- warnings.extend(missing_docs)
2461
+ if require_baseline:
2462
+ missing_docs = [
2463
+ f"{key} missing on disk: {rel_path}"
2464
+ for key, rel_path in _configured_structure_docs(cfg).items()
2465
+ if rel_path and not Path(repo, rel_path).exists()
2466
+ ]
2467
+ if selected_scope == "full":
2468
+ blocking.extend(missing_docs)
2469
+ else:
2470
+ warnings.extend(missing_docs)
2471
+
2472
+ if enforcement == "advisory" and blocking:
2473
+ warnings.extend(f"{message} [advisory]" for message in blocking)
2474
+ blocking = []
2306
2475
 
2307
2476
  result = {
2308
2477
  "scope": selected_scope,
2478
+ "enforcement": enforcement,
2309
2479
  "inspected_files": inspected,
2310
2480
  "blocking": blocking,
2311
2481
  "warnings": warnings,
@@ -2630,14 +2800,23 @@ def _classify_paths(paths: list[str]) -> dict:
2630
2800
  categories: set[str] = set()
2631
2801
  for path in paths:
2632
2802
  lower = path.lower()
2803
+ words = {word for word in re.split(r"[^a-z0-9]+", lower) if word}
2633
2804
  if _path_matches(path, _DEFAULT_FULL_PATH_PATTERNS):
2634
2805
  categories.add("release_or_tooling")
2635
- if any(token in lower for token in ["migration", "schema", "database", "/db/", "/sql/"]) or lower.endswith(".sql"):
2806
+ if words & {"migration", "migrations", "schema", "database", "db", "sql"} or lower.endswith(".sql"):
2636
2807
  categories.add("db")
2637
2808
  if any(token in lower for token in ["api", "controller", "handler", "route", "server"]):
2638
2809
  categories.add("api")
2639
- if any(token in lower for token in ["auth", "permission", "role", "tenant", "security"]):
2810
+ if words & {"auth", "authentication", "authorization", "permission", "permissions", "role", "roles", "tenant", "security"}:
2640
2811
  categories.add("auth")
2812
+ if words & {"payment", "payments", "billing", "invoice", "invoices", "checkout", "order", "orders"}:
2813
+ categories.add("payment")
2814
+ if words & {"upload", "uploads", "download", "downloads", "attachment", "attachments"}:
2815
+ categories.add("file_transfer")
2816
+ if words & {"nginx", "gateway", "ingress"} or {"reverse", "proxy"} <= words:
2817
+ categories.add("gateway")
2818
+ if "production" in words or "prod" in words and "config" in words or ".env.prod" in lower:
2819
+ categories.add("prod_config")
2641
2820
  if any(token in lower for token in ["page", "component", "view", "frontend", "miniapp", ".tsx", ".jsx", ".vue", ".scss", ".css"]):
2642
2821
  categories.add("ui")
2643
2822
  if any(token in lower for token in ["test", "spec", "__tests__"]):
@@ -2648,61 +2827,222 @@ def _classify_paths(paths: list[str]) -> dict:
2648
2827
  categories.add("structure")
2649
2828
  return {
2650
2829
  "categories": sorted(categories),
2651
- "needs_dd": bool(categories & {"api", "db", "auth", "release_or_tooling"}) or len(paths) > 12,
2830
+ "needs_dd": bool(
2831
+ categories
2832
+ & {"api", "db", "auth", "payment", "file_transfer", "gateway", "prod_config", "release_or_tooling"}
2833
+ )
2834
+ or len(paths) > 12,
2652
2835
  "needs_adr": bool(categories & {"structure", "release_or_tooling"}) and not categories <= {"docs"},
2653
2836
  "needs_browser": "ui" in categories,
2654
- "needs_jenkins": bool(categories & {"release_or_tooling", "db", "auth"}),
2655
- "needs_target": bool(categories & {"api", "db", "auth", "ui"}),
2837
+ "needs_jenkins": bool(
2838
+ categories & {"release_or_tooling", "db", "auth", "payment", "gateway", "prod_config"}
2839
+ ),
2840
+ "needs_target": bool(
2841
+ categories & {"api", "db", "auth", "payment", "file_transfer", "gateway", "prod_config", "ui"}
2842
+ ),
2656
2843
  }
2657
2844
 
2658
2845
 
2659
- def cmd_classify(args: argparse.Namespace) -> None:
2660
- repo = Path(args.repo).resolve()
2661
- cfg = _load_cfg(repo)
2662
- scope = str(args.scope or "").strip().lower()
2663
- impact = _impact_summary(cfg, repo, requested_scope=scope, base_ref=str(args.base or ""))
2846
+ def _normalize_workflow_profile(value: object, default: str = "auto") -> str:
2847
+ profile = _text(value).lower() or default
2848
+ if profile not in _WORKFLOW_PROFILES:
2849
+ raise APError("workflow.profile must be one of: " + ", ".join(sorted(_WORKFLOW_PROFILES)))
2850
+ return profile
2851
+
2852
+
2853
+ def _configured_workflow_profile(cfg: dict) -> str:
2854
+ return _normalize_workflow_profile((cfg.get("workflow") or {}).get("profile"))
2855
+
2856
+
2857
+ def _recommended_agents(profile: str, categories: set[str], classification: dict) -> list[str]:
2858
+ if profile == "micro":
2859
+ return []
2860
+ roles = ["explorer"]
2861
+ if categories & {"api", "release_or_tooling"}:
2862
+ roles.append("docs_researcher")
2863
+ roles.append("fixer")
2864
+ if classification.get("needs_browser"):
2865
+ roles.append("browser_debugger")
2866
+ if profile == "high-risk":
2867
+ roles.append("reviewer")
2868
+ return roles
2869
+
2870
+
2871
+ def _resolve_execution_plan(
2872
+ cfg: dict,
2873
+ repo: Path,
2874
+ *,
2875
+ requested_scope: str = "",
2876
+ requested_profile: str = "",
2877
+ requested_mode: str = "",
2878
+ base_ref: str = "",
2879
+ changed_paths: Optional[list[str]] = None,
2880
+ ) -> dict:
2881
+ impact = _impact_summary(
2882
+ cfg,
2883
+ repo,
2884
+ requested_scope=requested_scope,
2885
+ base_ref=base_ref,
2886
+ changed_paths=changed_paths,
2887
+ )
2664
2888
  paths = list(impact.get("changed_files") or [])
2665
- path_classification = _classify_paths(paths)
2889
+ classification = _classify_paths(paths)
2890
+ categories = set(classification["categories"])
2891
+ matching_rules = _matching_gate_rules(paths, _gate_cfg(cfg))
2892
+ configured_profile = _configured_workflow_profile(cfg)
2893
+ requested_profile_value = _normalize_workflow_profile(requested_profile) if requested_profile else ""
2894
+ configured_mode = _workflow_mode(cfg)
2895
+ requested_mode_value = _text(requested_mode).lower()
2896
+ if requested_mode_value and requested_mode_value not in {"dev", "verify"}:
2897
+ raise APError("workflow.mode must be 'dev' or 'verify'.")
2898
+
2899
+ detected_profile = "standard"
2900
+ profile_reasons: list[str] = []
2901
+ docs_only_paths = _docs_only(paths)
2902
+ docs_or_tests_only = bool(paths) and (
2903
+ (docs_only_paths and str(impact["selected_scope"]) != "full") or _tests_only(paths)
2904
+ )
2905
+ if docs_or_tests_only and str(impact["selected_scope"]) != "full":
2906
+ detected_profile = "micro"
2907
+ profile_reasons.append("only docs/test files changed")
2908
+
2909
+ raw_rule_profiles = {_text(rule.get("profile")).lower() for rule in matching_rules if _text(rule.get("profile"))}
2910
+ invalid_rule_profiles = raw_rule_profiles - (_WORKFLOW_PROFILES - {"auto"})
2911
+ if invalid_rule_profiles:
2912
+ raise APError(
2913
+ "matched gate rule has invalid profile: " + ", ".join(sorted(invalid_rule_profiles))
2914
+ )
2915
+ rule_profiles = raw_rule_profiles
2916
+ if "micro" in rule_profiles and detected_profile == "standard":
2917
+ detected_profile = "micro"
2918
+ profile_reasons.append("matched gate rule with profile=micro")
2919
+ if "standard" in rule_profiles and detected_profile == "micro":
2920
+ detected_profile = "standard"
2921
+ profile_reasons.append("matched gate rule with profile=standard")
2922
+
2923
+ high_categories = {
2924
+ "db",
2925
+ "auth",
2926
+ "payment",
2927
+ "file_transfer",
2928
+ "gateway",
2929
+ "prod_config",
2930
+ "release_or_tooling",
2931
+ }
2932
+ high_signals: list[str] = []
2933
+ if categories & high_categories and not docs_or_tests_only:
2934
+ high_signals.append("high-risk category: " + ", ".join(sorted(categories & high_categories)))
2935
+ if str(impact["selected_scope"]) == "full":
2936
+ high_signals.append("impact requires full gate")
2937
+ if "high-risk" in rule_profiles:
2938
+ high_signals.append("matched gate rule with profile=high-risk")
2939
+ if len(paths) > 12 and not docs_or_tests_only:
2940
+ high_signals.append("change spans more than 12 files")
2941
+ if requested_scope == "full":
2942
+ high_signals.append("full scope explicitly requested")
2943
+
2944
+ if high_signals:
2945
+ detected_profile = "high-risk"
2946
+ profile_reasons.extend(high_signals)
2947
+
2948
+ effective_profile = detected_profile if configured_profile == "auto" else configured_profile
2949
+ if configured_profile != "auto":
2950
+ profile_reasons.append(f"configured profile baseline: {configured_profile}")
2951
+ if requested_profile_value:
2952
+ requested_effective = detected_profile if requested_profile_value == "auto" else requested_profile_value
2953
+ configured_floor = None if configured_profile == "auto" else configured_profile
2954
+ if configured_floor and _PROFILE_RANK[requested_effective] < _PROFILE_RANK[configured_floor]:
2955
+ effective_profile = configured_floor
2956
+ profile_reasons.append(
2957
+ f"configured profile={configured_floor} cannot be downgraded to {requested_effective}"
2958
+ )
2959
+ else:
2960
+ effective_profile = requested_effective
2961
+ if detected_profile == "high-risk" and effective_profile != "high-risk":
2962
+ effective_profile = "high-risk"
2963
+ profile_reasons.append("high-risk signals cannot be downgraded")
2964
+ effective_mode = requested_mode_value or configured_mode
2965
+ if configured_mode == "verify":
2966
+ effective_mode = "verify"
2967
+ if effective_mode == "verify" and effective_profile != "high-risk":
2968
+ effective_profile = "high-risk"
2969
+ profile_reasons.append("verify mode requires high-risk execution")
2970
+ if not profile_reasons:
2971
+ profile_reasons.append(f"configured profile={configured_profile}")
2972
+
2973
+ selected_scope = _PROFILE_GATE_SCOPE[effective_profile]
2974
+ explicit_scope = _text(requested_scope).lower()
2975
+ if explicit_scope in _SCOPE_RANK and _SCOPE_RANK[explicit_scope] > _SCOPE_RANK[selected_scope]:
2976
+ selected_scope = explicit_scope
2977
+ if str(impact["selected_scope"]) == "full":
2978
+ selected_scope = "full"
2979
+ effective_mode = "verify" if effective_profile == "high-risk" else effective_mode
2980
+ execution_reasons = list(impact.get("reasons") or [])
2981
+ if selected_scope != str(impact["selected_scope"]):
2982
+ execution_reasons.append(f"profile={effective_profile} requires scope={selected_scope}")
2983
+
2666
2984
  jenkins_required = _verification_required(cfg, "jenkins", default=True)
2667
2985
  target_env_required = _verification_required(cfg, "target_env", default=True)
2668
- needs_jenkins = bool(path_classification["needs_jenkins"] and jenkins_required)
2669
- needs_target = bool(path_classification["needs_target"] and target_env_required)
2670
- selected_scope = str(impact["selected_scope"])
2671
- risk = "P3"
2672
- if needs_jenkins or selected_scope == "full":
2673
- risk = "P1"
2674
- elif needs_target or path_classification["needs_dd"]:
2675
- risk = "P2"
2676
- elif not paths:
2677
- risk = "P3"
2986
+ needs_jenkins = bool(classification["needs_jenkins"] and jenkins_required)
2987
+ needs_target = bool(classification["needs_target"] and target_env_required)
2988
+ needs_dd = bool(classification["needs_dd"] or effective_profile == "high-risk")
2989
+
2990
+ return {
2991
+ **impact,
2992
+ "reasons": execution_reasons,
2993
+ "configured_profile": configured_profile,
2994
+ "requested_profile": requested_profile_value or None,
2995
+ "profile": effective_profile,
2996
+ "profile_reasons": profile_reasons,
2997
+ "configured_mode": configured_mode,
2998
+ "requested_mode": requested_mode_value or None,
2999
+ "effective_mode": effective_mode,
3000
+ "selected_scope": selected_scope,
3001
+ "categories": sorted(categories),
3002
+ "needs_dd": needs_dd,
3003
+ "needs_adr": classification["needs_adr"],
3004
+ "needs_browser": classification["needs_browser"],
3005
+ "needs_jenkins": needs_jenkins,
3006
+ "needs_target": needs_target,
3007
+ "recommended_agents": _recommended_agents(effective_profile, categories, classification),
3008
+ }
3009
+
3010
+
3011
+ def cmd_classify(args: argparse.Namespace) -> None:
3012
+ repo = Path(args.repo).resolve()
3013
+ cfg = _load_cfg(repo)
3014
+ plan = _resolve_execution_plan(
3015
+ cfg,
3016
+ repo,
3017
+ requested_scope=_text(getattr(args, "scope", "")).lower(),
3018
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3019
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3020
+ base_ref=_text(getattr(args, "base", "")),
3021
+ )
3022
+ risk = {"micro": "P3", "standard": "P2", "high-risk": "P1"}[plan["profile"]]
2678
3023
  commands = [
2679
3024
  "python3 docs/tools/autopipeline/ap.py impact --scope auto",
2680
3025
  "python3 docs/tools/autopipeline/ap.py structure-check --scope auto",
2681
- f"python3 docs/tools/autopipeline/ap.py light-gate --scope {selected_scope} --explain",
3026
+ f"python3 docs/tools/autopipeline/ap.py light-gate --profile {plan['profile']} --explain",
2682
3027
  ]
2683
- if needs_jenkins:
3028
+ if plan["needs_dd"]:
3029
+ commands.append("python3 docs/tools/autopipeline/ap.py scaffold design --write")
3030
+ if plan["needs_jenkins"]:
2684
3031
  commands.append("python3 docs/tools/autopipeline/ap.py verify-jenkins")
2685
3032
  result = {
2686
- "requested_scope": impact["requested_scope"],
2687
- "selected_scope": selected_scope,
3033
+ **plan,
2688
3034
  "risk": risk,
2689
- "changed_files": paths,
2690
- "categories": path_classification["categories"],
2691
- "needs_dd": path_classification["needs_dd"],
2692
- "needs_adr": path_classification["needs_adr"],
2693
- "needs_browser": path_classification["needs_browser"],
2694
- "needs_jenkins": needs_jenkins,
2695
- "needs_target": needs_target,
2696
3035
  "recommended_commands": commands,
2697
- "reasons": impact.get("reasons") or [],
2698
- "matched_rules": impact.get("matched_rules") or [],
2699
3036
  }
2700
3037
  if args.json:
2701
3038
  print(json.dumps(result, ensure_ascii=False, indent=2))
2702
3039
  else:
2703
3040
  print(f"[classify] risk={risk}")
2704
- print(f"[classify] selected_scope={selected_scope}")
3041
+ print(f"[classify] profile={result['profile']}")
3042
+ print(f"[classify] effective_mode={result['effective_mode']}")
3043
+ print(f"[classify] selected_scope={result['selected_scope']}")
2705
3044
  print("[classify] categories=" + (", ".join(result["categories"]) or "(none)"))
3045
+ print("[classify] agents=" + (", ".join(result["recommended_agents"]) or "(main agent only)"))
2706
3046
  for key in ["needs_dd", "needs_adr", "needs_browser", "needs_jenkins", "needs_target"]:
2707
3047
  print(f"[classify] {key}={result[key]}")
2708
3048
  for command in commands:
@@ -2736,15 +3076,29 @@ def cmd_run(args: argparse.Namespace) -> None:
2736
3076
  def cmd_light_gate(args: argparse.Namespace) -> None:
2737
3077
  repo = Path(args.repo).resolve()
2738
3078
  light_gate_start = time.time()
2739
- cmd_doctor(argparse.Namespace(repo=str(repo)))
3079
+ cmd_doctor(
3080
+ argparse.Namespace(
3081
+ repo=str(repo),
3082
+ profile=_text(getattr(args, "profile", "")).lower(),
3083
+ mode=_text(getattr(args, "mode", "")).lower(),
3084
+ )
3085
+ )
2740
3086
  cfg = _load_cfg(repo)
2741
- requested_scope = str(getattr(args, "scope", "") or "").strip().lower()
2742
- impact = _impact_summary(cfg, repo, requested_scope=requested_scope, base_ref=str(getattr(args, "base", "") or ""))
3087
+ plan = _resolve_execution_plan(
3088
+ cfg,
3089
+ repo,
3090
+ requested_scope=_text(getattr(args, "scope", "")).lower(),
3091
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3092
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3093
+ base_ref=_text(getattr(args, "base", "")),
3094
+ )
2743
3095
  if getattr(args, "explain", False):
2744
- _print_impact(impact)
3096
+ _print_impact(plan)
3097
+ for reason in plan["profile_reasons"]:
3098
+ print(f"[impact] profile_reason: {reason}")
2745
3099
 
2746
- selected_scope = str(impact["selected_scope"])
2747
- paths = list(impact.get("changed_files") or [])
3100
+ selected_scope = str(plan["selected_scope"])
3101
+ paths = list(plan.get("changed_files") or [])
2748
3102
  matching_rules = _matching_gate_rules(paths, _gate_cfg(cfg))
2749
3103
  executed: list[str] = []
2750
3104
  executed.extend(_run_structure_check_for_gate(repo, cfg, selected_scope, str(getattr(args, "base", "") or "")))
@@ -2771,16 +3125,32 @@ def cmd_light_gate(args: argparse.Namespace) -> None:
2771
3125
  cfg,
2772
3126
  "light_gate",
2773
3127
  "pass",
2774
- {"scope": selected_scope, "executed": executed, "duration_s": round(duration_s, 3), "changed_files": paths},
3128
+ {
3129
+ "profile": plan["profile"],
3130
+ "effective_mode": plan["effective_mode"],
3131
+ "scope": selected_scope,
3132
+ "executed": executed,
3133
+ "duration_s": round(duration_s, 3),
3134
+ "changed_files": paths,
3135
+ },
3136
+ )
3137
+ print(
3138
+ f"[light-gate] OK profile={plan['profile']} mode={plan['effective_mode']} "
3139
+ f"scope={selected_scope}: " + ", ".join(executed)
2775
3140
  )
2776
- print(f"[light-gate] OK scope={selected_scope}: " + ", ".join(executed))
2777
3141
 
2778
3142
 
2779
3143
  def cmd_impact(args: argparse.Namespace) -> None:
2780
3144
  repo = Path(args.repo).resolve()
2781
3145
  cfg = _load_cfg(repo)
2782
- scope = str(args.scope or "").strip().lower()
2783
- summary = _impact_summary(cfg, repo, requested_scope=scope, base_ref=str(args.base or ""))
3146
+ summary = _resolve_execution_plan(
3147
+ cfg,
3148
+ repo,
3149
+ requested_scope=_text(getattr(args, "scope", "")).lower(),
3150
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3151
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3152
+ base_ref=_text(getattr(args, "base", "")),
3153
+ )
2784
3154
  _print_impact(summary, as_json=bool(args.json))
2785
3155
  _record_evidence(repo, cfg, "impact", "pass", summary)
2786
3156
 
@@ -2930,41 +3300,100 @@ def cmd_doctor(args: argparse.Namespace) -> None:
2930
3300
  jenkins_cfg = (cfg.get("jenkins") or {})
2931
3301
  docs_cfg = (cfg.get("docs") or {})
2932
3302
  runtime_cfg = (cfg.get("runtime") or {})
3303
+ structure_cfg = _structure_cfg(cfg)
2933
3304
 
2934
3305
  missing: List[str] = []
2935
3306
  validation_errors: List[str] = []
2936
3307
 
2937
3308
  mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
3309
+ profile = str(workflow_cfg.get("profile") or "auto").strip().lower()
2938
3310
  target_env_required = _verification_required(cfg, "target_env", default=True)
2939
3311
  jenkins_required = _verification_required(cfg, "jenkins", default=True)
2940
3312
  if mode not in {"dev", "verify"}:
2941
3313
  missing.append("workflow.mode (must be dev or verify)")
3314
+ if profile not in _WORKFLOW_PROFILES:
3315
+ missing.append("workflow.profile (must be auto, micro, standard, or high-risk)")
2942
3316
  if not str(project_cfg.get("name") or "").strip():
2943
3317
  missing.append("project.name")
2944
- if not (
2945
- str(commands.get("gate_changed") or "").strip()
2946
- or str(commands.get("gate_standard") or "").strip()
2947
- or str(commands.get("gate_full") or "").strip()
2948
- or str(commands.get("full_gate") or "").strip()
2949
- or str(commands.get("light_gate") or "").strip()
2950
- or str(commands.get("quick_test") or "").strip()
2951
- or str(commands.get("test") or "").strip()
2952
- or str(commands.get("build") or "").strip()
2953
- ):
2954
- missing.append(
2955
- "commands.gate_changed/gate_standard/gate_full, commands.light_gate, "
2956
- "commands.quick_test, commands.test, or commands.build"
2957
- )
3318
+ enforcement = _text(structure_cfg.get("enforcement")).lower()
3319
+ if enforcement and enforcement not in {"advisory", "blocking"}:
3320
+ validation_errors.append("structure.enforcement must be advisory or blocking")
3321
+ gate_cfg = _gate_cfg(cfg)
3322
+ raw_rules = gate_cfg.get("rules") or []
3323
+ rules_valid = isinstance(raw_rules, list)
3324
+ if not rules_valid:
3325
+ validation_errors.append("gate.rules must be a list")
3326
+ raw_rules = []
3327
+ for index, rule in enumerate(raw_rules):
3328
+ if not isinstance(rule, dict):
3329
+ rules_valid = False
3330
+ validation_errors.append(f"gate.rules[{index}] must be a mapping")
3331
+ continue
3332
+ rule_profile = _text(rule.get("profile")).lower()
3333
+ if rule_profile and rule_profile not in _WORKFLOW_PROFILES - {"auto"}:
3334
+ rules_valid = False
3335
+ validation_errors.append(
3336
+ f"gate.rules[{index}].profile must be micro, standard, or high-risk"
3337
+ )
3338
+ rule_scope = _text(rule.get("scope")).lower()
3339
+ if rule_scope and rule_scope not in {"changed", "standard", "full"}:
3340
+ rules_valid = False
3341
+ validation_errors.append(
3342
+ f"gate.rules[{index}].scope must be changed, standard, or full"
3343
+ )
3344
+
3345
+ if mode in {"dev", "verify"} and profile in _WORKFLOW_PROFILES and rules_valid:
3346
+ try:
3347
+ plan = _resolve_execution_plan(
3348
+ cfg,
3349
+ repo,
3350
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3351
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3352
+ )
3353
+ except APError as exc:
3354
+ validation_errors.append(str(exc))
3355
+ else:
3356
+ effective_profile = str(plan["profile"])
3357
+ changed_files = list(plan.get("changed_files") or [])
3358
+ matching_rules = _matching_gate_rules(changed_files, gate_cfg)
3359
+ rule_changed_gate = any(
3360
+ any(_configured_command(cfg, _command_name(ref)) for ref in _as_list(rule.get("commands")))
3361
+ for rule in matching_rules
3362
+ )
3363
+ changed_gate = bool(
3364
+ _configured_command(cfg, "gate_changed")
3365
+ or _configured_command(cfg, "quick_test")
3366
+ or _configured_command(cfg, "test")
3367
+ or _configured_command(cfg, "build")
3368
+ or rule_changed_gate
3369
+ or _docs_only(changed_files)
3370
+ )
3371
+ standard_gate = bool(
3372
+ _configured_command(cfg, "gate_standard")
3373
+ or _configured_command(cfg, "light_gate")
3374
+ or _configured_command(cfg, "quick_test")
3375
+ or _configured_command(cfg, "test")
3376
+ or _configured_command(cfg, "build")
3377
+ )
3378
+ full_gate = bool(
3379
+ _configured_command(cfg, "gate_full")
3380
+ or _configured_command(cfg, "full_gate")
3381
+ )
3382
+ if effective_profile == "micro" and not changed_gate:
3383
+ missing.append(
3384
+ "micro gate command: commands.gate_changed, quick_test, test, build, "
3385
+ "or a matching gate rule command"
3386
+ )
3387
+ elif effective_profile == "standard" and not standard_gate:
3388
+ missing.append(
3389
+ "standard gate command: commands.gate_standard, light_gate, quick_test, test, or build"
3390
+ )
3391
+ elif effective_profile == "high-risk" and not full_gate:
3392
+ missing.append(
3393
+ "full gate command: commands.gate_full or commands.full_gate "
3394
+ "(required for high-risk/verify execution)"
3395
+ )
2958
3396
  if target_env_required:
2959
- _require_explicit_field(missing, "target_env.name", target_cfg.get("name"))
2960
- _require_explicit_field(missing, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
2961
- _require_explicit_field(missing, "target_env.frontend_username", target_cfg.get("frontend_username"))
2962
- _require_secret_reference(missing, "target_env", target_cfg, "frontend_password")
2963
- _require_explicit_field(missing, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
2964
- _require_explicit_field(missing, "target_env.backend_username", target_cfg.get("backend_username"))
2965
- _require_secret_reference(missing, "target_env", target_cfg, "backend_password")
2966
- _require_explicit_field(missing, "target_env.backend_root_username", target_cfg.get("backend_root_username"))
2967
- _require_secret_reference(missing, "target_env", target_cfg, "backend_root_password")
2968
3397
  _require_explicit_field(missing, "target_env.health_base_url", target_cfg.get("health_base_url"))
2969
3398
  _require_explicit_field(missing, "target_env.health_path", target_cfg.get("health_path"))
2970
3399
 
@@ -2983,9 +3412,17 @@ def cmd_doctor(args: argparse.Namespace) -> None:
2983
3412
  repo_docs = {
2984
3413
  "docs.taskbook": Path(repo, str(docs_cfg.get("taskbook", "docs/tasks/taskbook.md"))),
2985
3414
  "docs.closure_log": Path(repo, str(docs_cfg.get("closure_log", "docs/tasks/closure-log.md"))),
2986
- "docs.api_doc": Path(repo, str(docs_cfg.get("api_doc", "docs/interfaces/api.md"))),
2987
- "docs.api_change_log": Path(repo, str(docs_cfg.get("api_change_log", "docs/interfaces/api-change-log.md"))),
2988
3415
  }
3416
+ api_doc = Path(repo, str(docs_cfg.get("api_doc", "docs/interfaces/api.md")))
3417
+ api_change_log = Path(repo, str(docs_cfg.get("api_change_log", "docs/interfaces/api-change-log.md")))
3418
+ api_docs_enabled = (
3419
+ _bool_config(docs_cfg.get("api_docs_required"), False)
3420
+ if "api_docs_required" in docs_cfg
3421
+ else api_doc.exists() or api_change_log.exists()
3422
+ )
3423
+ if api_docs_enabled:
3424
+ repo_docs["docs.api_doc"] = api_doc
3425
+ repo_docs["docs.api_change_log"] = api_change_log
2989
3426
  for key, path in repo_docs.items():
2990
3427
  if not path.exists():
2991
3428
  validation_errors.append(f"{key} missing on disk: {path}")
@@ -3163,23 +3600,76 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
3163
3600
 
3164
3601
 
3165
3602
  def cmd_verify_api_docs(args: argparse.Namespace) -> None:
3166
- """Ensure API markdown doc and change-log exist."""
3603
+ """Ensure enabled or already materialized API docs are complete."""
3167
3604
  repo = Path(args.repo).resolve()
3168
3605
  cfg = _load_cfg(repo)
3169
3606
  docs = (cfg.get("docs") or {})
3170
3607
  api_doc = Path(repo, str(docs.get("api_doc", "docs/interfaces/api.md")))
3171
3608
  change_log = Path(repo, str(docs.get("api_change_log", "docs/interfaces/api-change-log.md")))
3609
+ if "api_docs_required" in docs:
3610
+ required = _bool_config(docs.get("api_docs_required"), False)
3611
+ else:
3612
+ required = api_doc.exists() or change_log.exists()
3613
+ if not required:
3614
+ _record_evidence(repo, cfg, "verify_api_docs", "skipped", {"reason": "api_docs_required=false"})
3615
+ print("[verify-api-docs] skipped: optional API docs are not enabled")
3616
+ return
3172
3617
  missing = [p for p in [api_doc, change_log] if not p.exists()]
3173
3618
  if missing:
3174
- raise APError("Missing API docs: " + ", ".join([str(p) for p in missing]))
3619
+ raise APError(
3620
+ "Missing API docs: "
3621
+ + ", ".join([str(p) for p in missing])
3622
+ + ". Create them with `ap.py scaffold api --write`."
3623
+ )
3175
3624
  _record_evidence(repo, cfg, "verify_api_docs", "pass", {"api_doc": str(api_doc), "api_change_log": str(change_log)})
3176
3625
  print(f"[verify-api-docs] OK: {api_doc} + {change_log}")
3177
3626
 
3178
3627
 
3628
+ def _validate_closure_result(effective_mode: str, result: str) -> None:
3629
+ mode = _text(effective_mode).lower()
3630
+ normalized_result = _text(result).upper()
3631
+ if mode == "dev" and normalized_result == "PASS":
3632
+ raise APError("PASS requires verify mode; use DEV-CLOSED, PARTIAL, or FAIL for dev execution.")
3633
+ if mode == "verify" and normalized_result == "DEV-CLOSED":
3634
+ raise APError("DEV-CLOSED is only valid for dev mode; use PASS, PARTIAL, or FAIL for verify execution.")
3635
+
3636
+
3637
+ def _validate_closure_evidence(result: str, verification_items: list[str]) -> None:
3638
+ if _text(result).upper() != "PASS":
3639
+ return
3640
+ meaningful = [
3641
+ _text(item)
3642
+ for item in verification_items
3643
+ if _text(item) and not _is_placeholder(item) and _text(item).lower() not in {"none", "n/a", "not run"}
3644
+ ]
3645
+ if not meaningful:
3646
+ raise APError("PASS requires at least one concrete --verification evidence item.")
3647
+
3648
+
3179
3649
  def cmd_record_closure(args: argparse.Namespace) -> None:
3180
3650
  repo = Path(args.repo).resolve()
3181
3651
  ensure_git_repo(repo)
3182
3652
  cfg = _load_cfg(repo)
3653
+ plan = _resolve_execution_plan(
3654
+ cfg,
3655
+ repo,
3656
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3657
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3658
+ )
3659
+ if not plan.get("changed_files"):
3660
+ commit_paths = _commit_changed_files(repo, _text(getattr(args, "commit", "")) or "HEAD")
3661
+ if commit_paths:
3662
+ plan = _resolve_execution_plan(
3663
+ cfg,
3664
+ repo,
3665
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3666
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3667
+ changed_paths=commit_paths,
3668
+ )
3669
+ profile = str(plan["profile"])
3670
+ _validate_closure_result(str(plan["effective_mode"]), str(args.result))
3671
+ verification_items = list(args.verification or [])
3672
+ _validate_closure_evidence(str(args.result), verification_items)
3183
3673
  docs_cfg = (cfg.get("docs") or {})
3184
3674
  target_cfg = (cfg.get("target_env") or {})
3185
3675
  taskbook = Path(repo, str(docs_cfg.get("taskbook", "docs/tasks/taskbook.md")))
@@ -3193,12 +3683,10 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
3193
3683
  timestamp = _dt.datetime.now().strftime("%Y-%m-%d %H:%M")
3194
3684
  commit_value = _resolve_git_short_sha(repo, args.commit)
3195
3685
  target_env = str(args.target_env or target_cfg.get("name") or "").strip() or "(not set)"
3196
- verification_items = args.verification or []
3197
3686
  verification_text = "; ".join(verification_items) if verification_items else "TODO"
3198
3687
  follow_up = str(args.follow_up or "").strip() or "none"
3199
3688
  jenkins_build = str(args.jenkins or "").strip() or "TODO"
3200
3689
  structure_check = str(getattr(args, "structure_check", "") or "").strip() or "TODO"
3201
-
3202
3690
  lines = [
3203
3691
  f"## {task_id} — {title} — {timestamp}",
3204
3692
  f"- Task: {task_id}",
@@ -3206,6 +3694,7 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
3206
3694
  f"- CI/Jenkins Build: {jenkins_build}",
3207
3695
  f"- Target Env: {target_env}",
3208
3696
  f"- Verification: {verification_text}",
3697
+ f"- Effective Profile: {profile}",
3209
3698
  f"- Structure Check: {structure_check}",
3210
3699
  f"- Result: {args.result}",
3211
3700
  f"- Follow-up: {follow_up}",
@@ -3227,7 +3716,13 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
3227
3716
  cfg,
3228
3717
  "record_closure",
3229
3718
  "pass",
3230
- {"task_id": task_id, "result": args.result, "commit": commit_value, "structure_check": structure_check},
3719
+ {
3720
+ "task_id": task_id,
3721
+ "result": args.result,
3722
+ "commit": commit_value,
3723
+ "profile": profile,
3724
+ "structure_check": structure_check,
3725
+ },
3231
3726
  )
3232
3727
  print(f"[record-closure] OK: {closure_log}")
3233
3728
 
@@ -3255,6 +3750,7 @@ def _record_commit_push_closure(
3255
3750
  verification=verification,
3256
3751
  result=result,
3257
3752
  follow_up=follow_up,
3753
+ profile=str(getattr(args, "effective_profile", "") or getattr(args, "profile", "") or ""),
3258
3754
  structure_check=structure_check,
3259
3755
  initial_commit=args.initial_commit,
3260
3756
  jenkins_failure=args.jenkins_failure,
@@ -3266,9 +3762,25 @@ def _record_commit_push_closure(
3266
3762
  def cmd_commit_push(args: argparse.Namespace) -> None:
3267
3763
  repo = Path(args.repo).resolve()
3268
3764
  ensure_git_repo(repo)
3269
- cmd_doctor(argparse.Namespace(repo=str(repo)))
3765
+ cmd_doctor(
3766
+ argparse.Namespace(
3767
+ repo=str(repo),
3768
+ profile=_text(getattr(args, "profile", "")).lower(),
3769
+ mode=_text(getattr(args, "mode", "")).lower(),
3770
+ )
3771
+ )
3270
3772
  cfg = _load_cfg(repo)
3271
- mode = _workflow_mode(cfg, args)
3773
+ plan = _resolve_execution_plan(
3774
+ cfg,
3775
+ repo,
3776
+ requested_scope="",
3777
+ requested_profile=_text(getattr(args, "profile", "")).lower(),
3778
+ requested_mode=_text(getattr(args, "mode", "")).lower(),
3779
+ )
3780
+ mode = str(plan["effective_mode"])
3781
+ args.effective_profile = str(plan["profile"])
3782
+ if args.result:
3783
+ _validate_closure_result(mode, str(args.result))
3272
3784
  target_cfg = (cfg.get("target_env") or {})
3273
3785
  target_env_required = _verification_required(cfg, "target_env", default=True)
3274
3786
  jenkins_required = _verification_required(cfg, "jenkins", default=True)
@@ -3280,7 +3792,16 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
3280
3792
  cmd_wait_health(argparse.Namespace(repo=str(repo), scope="runtime"))
3281
3793
 
3282
3794
  if mode in {"dev", "verify"} or args.require_light_gate:
3283
- cmd_light_gate(argparse.Namespace(repo=str(repo)))
3795
+ cmd_light_gate(
3796
+ argparse.Namespace(
3797
+ repo=str(repo),
3798
+ scope=plan["selected_scope"],
3799
+ profile=plan["profile"],
3800
+ mode=mode,
3801
+ base="",
3802
+ explain=False,
3803
+ )
3804
+ )
3284
3805
  structure_check_status = "passed via light-gate" if _structure_gate_enabled(cfg) else "skipped (structure disabled)"
3285
3806
 
3286
3807
  if args.require_jenkins:
@@ -3391,7 +3912,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
3391
3912
  follow_up=args.follow_up or "none",
3392
3913
  structure_check=args.structure_check or structure_check_status,
3393
3914
  )
3394
- print(f"[commit-push] OK - mode={mode}")
3915
+ print(f"[commit-push] OK - profile={plan['profile']} mode={mode} scope={plan['selected_scope']}")
3395
3916
 
3396
3917
 
3397
3918
  def main(argv: Optional[List[str]] = None) -> int:
@@ -3402,8 +3923,16 @@ def main(argv: Optional[List[str]] = None) -> int:
3402
3923
  s = sp.add_parser("install")
3403
3924
  s.add_argument("--bridges", action="store_true")
3404
3925
  s.add_argument("--force", action="store_true")
3926
+ s.add_argument("--full", action="store_true", help="Also materialize all optional document templates")
3405
3927
  s.set_defaults(func=cmd_install)
3406
3928
 
3929
+ s = sp.add_parser("scaffold")
3930
+ s.add_argument("group", choices=scaffold_groups() + ["all"])
3931
+ s.add_argument("--write", action="store_true")
3932
+ s.add_argument("--force", action="store_true")
3933
+ s.add_argument("--json", action="store_true")
3934
+ s.set_defaults(func=cmd_scaffold)
3935
+
3407
3936
  s = sp.add_parser("upgrade")
3408
3937
  s.add_argument("--dry-run", action="store_true")
3409
3938
  s.add_argument("--write", action="store_true")
@@ -3434,12 +3963,16 @@ def main(argv: Optional[List[str]] = None) -> int:
3434
3963
 
3435
3964
  s = sp.add_parser("impact")
3436
3965
  s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
3966
+ s.add_argument("--profile", choices=sorted(_WORKFLOW_PROFILES), default="")
3967
+ s.add_argument("--mode", choices=["dev", "verify"], default="")
3437
3968
  s.add_argument("--base")
3438
3969
  s.add_argument("--json", action="store_true")
3439
3970
  s.set_defaults(func=cmd_impact)
3440
3971
 
3441
3972
  s = sp.add_parser("classify")
3442
3973
  s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
3974
+ s.add_argument("--profile", choices=sorted(_WORKFLOW_PROFILES), default="")
3975
+ s.add_argument("--mode", choices=["dev", "verify"], default="")
3443
3976
  s.add_argument("--base")
3444
3977
  s.add_argument("--json", action="store_true")
3445
3978
  s.set_defaults(func=cmd_classify)
@@ -3469,6 +4002,8 @@ def main(argv: Optional[List[str]] = None) -> int:
3469
4002
 
3470
4003
  s = sp.add_parser("light-gate")
3471
4004
  s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
4005
+ s.add_argument("--profile", choices=sorted(_WORKFLOW_PROFILES), default="")
4006
+ s.add_argument("--mode", choices=["dev", "verify"], default="")
3472
4007
  s.add_argument("--base")
3473
4008
  s.add_argument("--explain", action="store_true")
3474
4009
  s.set_defaults(func=cmd_light_gate)
@@ -3519,6 +4054,7 @@ def main(argv: Optional[List[str]] = None) -> int:
3519
4054
  s.add_argument("--ci-build", "--jenkins", dest="jenkins", metavar="CI_BUILD")
3520
4055
  s.add_argument("--target-env")
3521
4056
  s.add_argument("--verification", action="append")
4057
+ s.add_argument("--profile", choices=sorted(_WORKFLOW_PROFILES - {"auto"}))
3522
4058
  s.add_argument("--structure-check")
3523
4059
  s.add_argument("--result", choices=["DEV-CLOSED", "PASS", "FAIL", "PARTIAL"], required=True)
3524
4060
  s.add_argument("--follow-up")
@@ -3532,6 +4068,7 @@ def main(argv: Optional[List[str]] = None) -> int:
3532
4068
  s.add_argument("--title")
3533
4069
  s.add_argument("--msg", required=True)
3534
4070
  s.add_argument("--mode", choices=["dev", "verify"])
4071
+ s.add_argument("--profile", choices=sorted(_WORKFLOW_PROFILES))
3535
4072
  s.add_argument("--require-light-gate", action="store_true")
3536
4073
  s.add_argument("--require-runtime-health", action="store_true")
3537
4074
  s.add_argument("--require-jenkins", action="store_true")