@elvis1513/auto-coding-skill 4.1.1 → 4.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -46,12 +46,12 @@ _GENERATED_NOISE_PATTERNS = [
46
46
  ]
47
47
  _AGENT_CONTRACT_VERSION = 1
48
48
  _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
49
- _MAX_FINAL_COMMAND_SECONDS = 120.0
50
- _MAX_FINAL_TOTAL_SECONDS = 180.0
49
+ _RECOMMENDED_FINAL_COMMAND_SECONDS = 120.0
50
+ _RECOMMENDED_FINAL_TOTAL_SECONDS = 180.0
51
51
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
52
52
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
53
53
  "schema_version": 1,
54
- "managed_versions": {"agents": "4.1.1", "engineering": "4.1.1"},
54
+ "managed_versions": {"agents": "4.1.3", "engineering": "4.1.3"},
55
55
  "known_official_engineering_body_sha256": [
56
56
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
57
57
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -638,8 +638,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
638
638
  if _text(workflow_cfg.get("completion")).lower() != "push":
639
639
  workflow_cfg["completion"] = "push"
640
640
  changed.append("workflow.completion")
641
- if _text(workflow_cfg.get("skill_version")) != "4.1.1":
642
- workflow_cfg["skill_version"] = "4.1.1"
641
+ if _text(workflow_cfg.get("skill_version")) != "4.1.3":
642
+ workflow_cfg["skill_version"] = "4.1.3"
643
643
  changed.append("workflow.skill_version")
644
644
 
645
645
  commands_cfg = cfg.setdefault("commands", {})
@@ -689,8 +689,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
689
689
  validation_cfg["on_unmapped"] = "error"
690
690
  changed.append("validation.on_unmapped")
691
691
  for key, default_value in [
692
- ("max_command_seconds", int(_MAX_FINAL_COMMAND_SECONDS)),
693
- ("max_total_seconds", int(_MAX_FINAL_TOTAL_SECONDS)),
692
+ ("max_command_seconds", int(_RECOMMENDED_FINAL_COMMAND_SECONDS)),
693
+ ("max_total_seconds", int(_RECOMMENDED_FINAL_TOTAL_SECONDS)),
694
694
  ]:
695
695
  if key not in validation_cfg:
696
696
  validation_cfg[key] = default_value
@@ -952,16 +952,16 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
952
952
  if current_agents:
953
953
  archive_dir = repo / "docs" / "archive" / "workflow"
954
954
  archive_header = (
955
- "# Archived AGENTS.md before auto-coding-skill 4.1.1\n\n"
955
+ "# Archived AGENTS.md before auto-coding-skill 4.1.3\n\n"
956
956
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
957
957
  "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
958
958
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
959
959
  )
960
960
  archive_content = archive_header + current_agents
961
- archive = archive_dir / "AGENTS.pre-4.1.1.md"
961
+ archive = archive_dir / "AGENTS.pre-4.1.3.md"
962
962
  if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
963
963
  digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
964
- archive = archive_dir / f"AGENTS.pre-4.1.1-{digest}.md"
964
+ archive = archive_dir / f"AGENTS.pre-4.1.3-{digest}.md"
965
965
  if not archive.exists():
966
966
  add_action("policy", archive, "archive", "historical and non-authoritative")
967
967
  if write:
@@ -1732,6 +1732,17 @@ def _task_registry_path(repo: Path, task_id: str) -> Path:
1732
1732
  return _task_state_root(repo) / "tasks" / f"{_validate_task_id(task_id)}.json"
1733
1733
 
1734
1734
 
1735
+ def _has_registered_active_task(repo: Path) -> bool:
1736
+ registry = _task_state_root(repo) / "tasks"
1737
+ if not registry.exists():
1738
+ return False
1739
+ for path in sorted(registry.glob("*.json")):
1740
+ payload = _read_json_object(path) or {}
1741
+ if _text(payload.get("state")) not in {"", "integrated", "cleanup-pending"}:
1742
+ return True
1743
+ return False
1744
+
1745
+
1735
1746
  def _worktree_manifest_path(repo: Path) -> Path:
1736
1747
  return _git_dir(repo) / "auto-coding-skill-task.json"
1737
1748
 
@@ -2466,6 +2477,8 @@ def _resolve_secret(section_name: str, section_cfg: dict, field: str) -> str:
2466
2477
 
2467
2478
  _GATE_SCOPES = {"auto", "changed", "standard", "full"}
2468
2479
  _WORKFLOW_PROFILES = {"auto", "micro", "standard", "high-risk"}
2480
+ _TASK_KINDS = {"none", "read_only", "change", "terminal_maintenance"}
2481
+ _REQUESTED_TASK_KINDS = (_TASK_KINDS - {"none"}) | {"auto"}
2469
2482
  _PROFILE_GATE_SCOPE = {"micro": "changed", "standard": "changed", "high-risk": "changed"}
2470
2483
  _PROFILE_RANK = {"micro": 0, "standard": 1, "high-risk": 2}
2471
2484
  _SCOPE_RANK = {"changed": 0, "standard": 1, "full": 2}
@@ -2529,24 +2542,14 @@ def _final_gate_budget(cfg: dict) -> dict[str, float]:
2529
2542
  validation_cfg = _validation_cfg(cfg)
2530
2543
  command_seconds = _positive_seconds(
2531
2544
  validation_cfg.get("max_command_seconds"),
2532
- _MAX_FINAL_COMMAND_SECONDS,
2545
+ _RECOMMENDED_FINAL_COMMAND_SECONDS,
2533
2546
  "validation.max_command_seconds",
2534
2547
  )
2535
2548
  total_seconds = _positive_seconds(
2536
2549
  validation_cfg.get("max_total_seconds"),
2537
- _MAX_FINAL_TOTAL_SECONDS,
2550
+ _RECOMMENDED_FINAL_TOTAL_SECONDS,
2538
2551
  "validation.max_total_seconds",
2539
2552
  )
2540
- if command_seconds > _MAX_FINAL_COMMAND_SECONDS:
2541
- raise APError(
2542
- f"validation.max_command_seconds cannot exceed {_MAX_FINAL_COMMAND_SECONDS:.0f}; "
2543
- "move slower checks to an explicit diagnostic command"
2544
- )
2545
- if total_seconds > _MAX_FINAL_TOTAL_SECONDS:
2546
- raise APError(
2547
- f"validation.max_total_seconds cannot exceed {_MAX_FINAL_TOTAL_SECONDS:.0f}; "
2548
- "move slower checks to an explicit diagnostic command"
2549
- )
2550
2553
  if command_seconds > total_seconds:
2551
2554
  raise APError("validation.max_command_seconds cannot exceed validation.max_total_seconds")
2552
2555
  return {"command_seconds": command_seconds, "total_seconds": total_seconds}
@@ -2588,6 +2591,7 @@ def _run_configured_command_list(
2588
2591
  *,
2589
2592
  deadline: Optional[float] = None,
2590
2593
  command_timeout_s: Optional[float] = None,
2594
+ command_timeouts: Optional[dict[str, float]] = None,
2591
2595
  ) -> list[str]:
2592
2596
  executed: list[str] = []
2593
2597
  missing: list[str] = []
@@ -2597,6 +2601,9 @@ def _run_configured_command_list(
2597
2601
  continue
2598
2602
  if _configured_command(cfg, name):
2599
2603
  timeout_s = command_timeout_s
2604
+ route_timeout = (command_timeouts or {}).get(name)
2605
+ if route_timeout is not None:
2606
+ timeout_s = min(timeout_s, route_timeout) if timeout_s is not None else route_timeout
2600
2607
  if deadline is not None:
2601
2608
  remaining = deadline - time.monotonic()
2602
2609
  if remaining <= 0:
@@ -2784,6 +2791,7 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
2784
2791
  normalized = _unique_paths(paths)
2785
2792
  routes = _validation_routes(cfg)
2786
2793
  command_names: list[str] = []
2794
+ command_timeouts: dict[str, float] = {}
2787
2795
  matched_routes: list[str] = []
2788
2796
  coverage: dict[str, list[str]] = {}
2789
2797
  unmapped: list[str] = []
@@ -2794,6 +2802,13 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
2794
2802
  if not _validation_route_matches(path, route):
2795
2803
  continue
2796
2804
  route_name = _text(route.get("name")) or f"route-{index + 1}"
2805
+ route_timeout: Optional[float] = None
2806
+ if route.get("timeout_seconds") not in {None, ""}:
2807
+ route_timeout = _positive_seconds(
2808
+ route.get("timeout_seconds"),
2809
+ 1.0,
2810
+ f"validation.routes[{index}].timeout_seconds",
2811
+ )
2797
2812
  names.append(route_name)
2798
2813
  if route_name not in matched_routes:
2799
2814
  matched_routes.append(route_name)
@@ -2801,6 +2816,13 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
2801
2816
  command_name = _command_name(command_ref)
2802
2817
  if command_name and command_name not in command_names:
2803
2818
  command_names.append(command_name)
2819
+ if command_name and route_timeout is not None:
2820
+ current_timeout = command_timeouts.get(command_name)
2821
+ command_timeouts[command_name] = (
2822
+ min(current_timeout, route_timeout)
2823
+ if current_timeout is not None
2824
+ else route_timeout
2825
+ )
2804
2826
  coverage[path] = names
2805
2827
  if not names and not _path_matches(path, _DOC_PATH_PATTERNS):
2806
2828
  unmapped.append(path)
@@ -2829,6 +2851,7 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
2829
2851
  return {
2830
2852
  "paths": normalized,
2831
2853
  "commands": command_names,
2854
+ "command_timeouts": command_timeouts,
2832
2855
  "matched_routes": matched_routes,
2833
2856
  "coverage": coverage,
2834
2857
  "unmapped": unmapped,
@@ -2965,6 +2988,7 @@ def _run_changed_gate(
2965
2988
  plan["commands"],
2966
2989
  deadline=deadline,
2967
2990
  command_timeout_s=command_timeout_s,
2991
+ command_timeouts=plan["command_timeouts"],
2968
2992
  )
2969
2993
  print(
2970
2994
  "[validation] routes="
@@ -2990,6 +3014,7 @@ def cmd_validation_map_check(args: argparse.Namespace) -> None:
2990
3014
  result = {
2991
3015
  "paths": plan["paths"],
2992
3016
  "commands": plan["commands"],
3017
+ "command_timeouts": plan["command_timeouts"],
2993
3018
  "matched_routes": plan["matched_routes"],
2994
3019
  "coverage": plan["coverage"],
2995
3020
  "docs_only": plan["docs_only"],
@@ -4402,7 +4427,7 @@ def _classify_paths(paths: list[str]) -> dict:
4402
4427
  categories.add("api")
4403
4428
  if words & {"auth", "authentication", "authorization", "permission", "permissions", "role", "roles", "tenant", "security"}:
4404
4429
  categories.add("auth")
4405
- if words & {"payment", "payments", "billing", "invoice", "invoices", "checkout", "order", "orders"}:
4430
+ if words & {"payment", "payments", "billing", "invoice", "invoices", "checkout"}:
4406
4431
  categories.add("payment")
4407
4432
  if words & {"upload", "uploads", "download", "downloads", "attachment", "attachments"}:
4408
4433
  categories.add("file_transfer")
@@ -4464,6 +4489,88 @@ def _classify_intent(intent: str) -> list[str]:
4464
4489
  )
4465
4490
 
4466
4491
 
4492
+ def _resolve_task_kind(
4493
+ requested: str,
4494
+ paths: list[str],
4495
+ intent: str,
4496
+ ) -> str:
4497
+ value = _text(requested).lower().replace("-", "_") or "auto"
4498
+ if value not in _REQUESTED_TASK_KINDS:
4499
+ raise APError("task kind must be one of: " + ", ".join(sorted(_REQUESTED_TASK_KINDS)))
4500
+ if _is_terminal_ledger_maintenance(paths):
4501
+ if value in {"change", "read_only"}:
4502
+ return value
4503
+ return "terminal_maintenance"
4504
+ normalized_intent = _text(intent).lower()
4505
+ terminal_action = bool(
4506
+ re.search(r"\b(archive|close|reconcile)\b", normalized_intent)
4507
+ or any(keyword in normalized_intent for keyword in ["归档", "对账", "收口"])
4508
+ )
4509
+ terminal_subject = bool(
4510
+ re.search(r"\b(closure|ledger|task\s+records?|taskbook)\b", normalized_intent)
4511
+ or any(keyword in normalized_intent for keyword in ["台账", "任务记录", "关闭记录"])
4512
+ )
4513
+ if terminal_action and terminal_subject:
4514
+ detected = "terminal_maintenance"
4515
+ elif paths:
4516
+ detected = "change"
4517
+ elif not normalized_intent:
4518
+ detected = "none"
4519
+ else:
4520
+ detected = ""
4521
+ if value == "terminal_maintenance" and detected != "terminal_maintenance":
4522
+ raise APError(
4523
+ "terminal_maintenance is valid only for task ledger/closure/archive reconciliation; "
4524
+ "code or unrelated documentation paths require task-kind=change"
4525
+ )
4526
+ if value != "auto":
4527
+ return value
4528
+ if detected:
4529
+ return detected
4530
+ english_change = re.search(
4531
+ r"\b(add|build|change|create|delete|deploy|develop|fix|implement|migrate|optimize|publish|refactor|release|remove|rename|resolve|update|upgrade)\b",
4532
+ normalized_intent,
4533
+ )
4534
+ chinese_change = any(
4535
+ keyword in normalized_intent
4536
+ for keyword in [
4537
+ "修改", "新增", "删除", "修复", "解决", "整改", "实现", "迁移", "发布",
4538
+ "重构", "改名", "升级", "优化", "完善", "补充", "清理", "落地", "提交", "推送",
4539
+ ]
4540
+ )
4541
+ return "change" if english_change or chinese_change else "read_only"
4542
+
4543
+
4544
+ def _optional_agent_candidates(
4545
+ *,
4546
+ task_kind: str,
4547
+ intent: str,
4548
+ categories: set[str],
4549
+ cross_module: bool,
4550
+ profile: str,
4551
+ ) -> list[str]:
4552
+ if task_kind not in {"read_only", "change"}:
4553
+ return []
4554
+ value = _text(intent).lower()
4555
+ roles: list[str] = []
4556
+ if task_kind == "read_only" or cross_module or profile == "high-risk":
4557
+ roles.append("explorer")
4558
+ if any(
4559
+ keyword in value
4560
+ for keyword in [
4561
+ "documentation", "docs", "framework", "library", "official", "sdk", "version",
4562
+ "依赖", "官方", "文档", "框架", "版本",
4563
+ ]
4564
+ ):
4565
+ roles.append("docs_researcher")
4566
+ if "ui" in categories and any(
4567
+ keyword in value
4568
+ for keyword in ["broken", "bug", "error", "fail", "fix", "reproduce", "报错", "复现", "失败", "异常", "修复"]
4569
+ ):
4570
+ roles.append("browser_debugger")
4571
+ return roles
4572
+
4573
+
4467
4574
  def _normalize_workflow_profile(value: object, default: str = "auto") -> str:
4468
4575
  profile = _text(value).lower() or default
4469
4576
  if profile not in _WORKFLOW_PROFILES:
@@ -4550,12 +4657,15 @@ def _validate_agent_plan(plan: dict) -> dict:
4550
4657
  "result_contract",
4551
4658
  "stages",
4552
4659
  "constraints",
4660
+ "optional_roles",
4553
4661
  }
4554
4662
  missing = sorted(required - set(plan))
4555
4663
  if missing or plan.get("contract_version") != _AGENT_CONTRACT_VERSION:
4556
4664
  raise APError("Invalid agent plan contract: " + (", ".join(missing) or "version"))
4557
4665
  if plan.get("contract_schema") != _AGENT_CONTRACT_SCHEMA:
4558
4666
  raise APError("Invalid agent plan schema path.")
4667
+ if plan.get("strategy") not in {"main-only", "orchestrated-subagents"}:
4668
+ raise APError("Invalid agent plan strategy.")
4559
4669
  if not all(
4560
4670
  isinstance(stage, dict)
4561
4671
  and {"id", "mode", "roles", "depends_on"} <= set(stage)
@@ -4572,11 +4682,12 @@ def _agent_execution_plan(
4572
4682
  *,
4573
4683
  parallel_writers: int = 1,
4574
4684
  review_required: bool = False,
4685
+ optional_roles: Optional[list[str]] = None,
4575
4686
  ) -> dict:
4576
4687
  assignment_contract, result_contract = _agent_contract_shape()
4577
- # Classification reports useful capabilities but never auto-dispatches
4578
- # discovery roles. The model chooses delegation only when expected benefit
4579
- # exceeds coordination cost.
4688
+ optional_roles = list(dict.fromkeys(optional_roles or []))
4689
+ # Optional roles are candidates, never automatic stages. The model selects
4690
+ # them only when expected benefit exceeds coordination cost.
4580
4691
  discovery_roles: list[str] = []
4581
4692
 
4582
4693
  policies = {
@@ -4629,7 +4740,7 @@ def _agent_execution_plan(
4629
4740
  "depends_on": [previous],
4630
4741
  }
4631
4742
  )
4632
- strategy = "parallel-writers" if parallel_writers > 1 else "risk-assisted"
4743
+ strategy = "orchestrated-subagents"
4633
4744
 
4634
4745
  return _validate_agent_plan({
4635
4746
  "contract_version": _AGENT_CONTRACT_VERSION,
@@ -4638,6 +4749,7 @@ def _agent_execution_plan(
4638
4749
  "policies": policies,
4639
4750
  "assignment_contract": assignment_contract,
4640
4751
  "result_contract": result_contract,
4752
+ "optional_roles": optional_roles,
4641
4753
  "stages": stages,
4642
4754
  "constraints": constraints,
4643
4755
  })
@@ -4645,46 +4757,66 @@ def _agent_execution_plan(
4645
4757
 
4646
4758
  def _mechanism_plan(
4647
4759
  *,
4648
- has_task_signal: bool,
4649
- terminal_maintenance: bool,
4760
+ task_kind: str,
4650
4761
  execution_mode: str,
4651
4762
  review_required: bool,
4652
4763
  design_required: bool,
4653
4764
  parallel_writers: int,
4654
4765
  ) -> dict:
4655
- code_delivery = has_task_signal and not terminal_maintenance
4656
- required = ["analysis"] if has_task_signal else []
4657
- if design_required:
4658
- required.append("durable_design")
4659
- if execution_mode == "isolated":
4660
- required.extend(["task_lifecycle", "worktree"])
4661
- elif review_required:
4662
- required.append("task_lifecycle")
4663
- if parallel_writers > 1:
4664
- required.append("parallel_fixers")
4665
- if review_required:
4666
- required.append("independent_review")
4667
- if code_delivery:
4766
+ universe = [
4767
+ "analysis",
4768
+ "targeted_consistency_check",
4769
+ "durable_design",
4770
+ "task_lifecycle",
4771
+ "worktree",
4772
+ "read_only_subagents",
4773
+ "parallel_fixers",
4774
+ "independent_review",
4775
+ "final_changed_scope_gate",
4776
+ "commit_push",
4777
+ ]
4778
+ required: list[str] = []
4779
+ optional: list[str] = []
4780
+ if task_kind == "read_only":
4781
+ required = ["analysis"]
4782
+ optional = ["read_only_subagents"]
4783
+ elif task_kind == "terminal_maintenance":
4784
+ required = ["analysis", "targeted_consistency_check", "commit_push"]
4785
+ elif task_kind == "change":
4786
+ required = ["analysis"]
4787
+ if design_required:
4788
+ required.append("durable_design")
4789
+ else:
4790
+ optional.append("durable_design")
4791
+ if execution_mode == "isolated":
4792
+ required.extend(["task_lifecycle", "worktree"])
4793
+ elif review_required:
4794
+ required.append("task_lifecycle")
4795
+ if parallel_writers > 1:
4796
+ required.append("parallel_fixers")
4797
+ else:
4798
+ optional.append("parallel_fixers")
4799
+ if review_required:
4800
+ required.append("independent_review")
4801
+ else:
4802
+ optional.append("independent_review")
4803
+ optional.append("read_only_subagents")
4668
4804
  required.extend(["final_changed_scope_gate", "commit_push"])
4669
4805
  ordered = list(dict.fromkeys(required))
4670
- optional = [
4671
- mechanism
4672
- for mechanism in [
4673
- "classify",
4674
- "durable_design",
4675
- "task_lifecycle",
4676
- "worktree",
4677
- "read_only_subagents",
4678
- "parallel_fixers",
4679
- "independent_review",
4680
- ]
4681
- if mechanism not in ordered
4682
- ]
4806
+ optional = [item for item in dict.fromkeys(optional) if item not in ordered]
4807
+ forbidden = [item for item in universe if item not in ordered and item not in optional]
4683
4808
  return {
4684
4809
  "required": ordered,
4685
- "not_required": optional,
4810
+ "optional_when_beneficial": optional,
4811
+ "forbidden": forbidden,
4812
+ # 4.1 compatibility: old clients treat only truly forbidden mechanisms
4813
+ # as not required; model-selectable mechanisms remain available.
4814
+ "not_required": forbidden,
4686
4815
  "lifecycle_required": "task_lifecycle" in ordered,
4687
- "rule": "do not add a mechanism that is not required unless the user explicitly requests it",
4816
+ "rule": (
4817
+ "run required mechanisms; select optional mechanisms only when expected value exceeds "
4818
+ "coordination cost; do not run forbidden mechanisms unless the user explicitly overrides"
4819
+ ),
4688
4820
  }
4689
4821
 
4690
4822
 
@@ -4700,6 +4832,8 @@ def _resolve_execution_plan(
4700
4832
  planned_paths: Optional[list[str]] = None,
4701
4833
  intent: str = "",
4702
4834
  parallel_writers: int = 1,
4835
+ requested_task_kind: str = "",
4836
+ continue_direct: bool = False,
4703
4837
  ) -> dict:
4704
4838
  impact = _impact_summary(
4705
4839
  cfg,
@@ -4713,9 +4847,11 @@ def _resolve_execution_plan(
4713
4847
  {_normalize_owned_path(item) for item in (planned_paths or []) if _text(item)}
4714
4848
  )
4715
4849
  classification_inputs = [*paths, *normalized_planned_paths]
4716
- classification = _classify_paths(classification_inputs)
4850
+ task_kind = _resolve_task_kind(requested_task_kind, classification_inputs, intent)
4851
+ path_classification = _classify_paths(classification_inputs)
4852
+ path_categories = set(path_classification["categories"])
4717
4853
  intent_categories = _classify_intent(intent)
4718
- merged_categories = set(classification["categories"]) | set(intent_categories)
4854
+ merged_categories = path_categories | set(intent_categories)
4719
4855
  classification = _classification_for_categories(merged_categories, len(classification_inputs))
4720
4856
  categories = set(classification["categories"])
4721
4857
  matching_rules = _matching_risk_rules(classification_inputs, cfg)
@@ -4733,8 +4869,11 @@ def _resolve_execution_plan(
4733
4869
  (docs_only_paths and str(impact["selected_scope"]) != "full")
4734
4870
  or _tests_only(classification_inputs)
4735
4871
  )
4736
- terminal_maintenance = _is_terminal_ledger_maintenance(classification_inputs)
4737
- if docs_or_tests_only and str(impact["selected_scope"]) != "full":
4872
+ terminal_maintenance = task_kind == "terminal_maintenance"
4873
+ if task_kind in {"read_only", "terminal_maintenance", "none"}:
4874
+ detected_profile = "micro"
4875
+ profile_reasons.append(f"task kind: {task_kind}")
4876
+ elif docs_or_tests_only and str(impact["selected_scope"]) != "full":
4738
4877
  detected_profile = "micro"
4739
4878
  profile_reasons.append("only docs/test files changed")
4740
4879
 
@@ -4745,10 +4884,10 @@ def _resolve_execution_plan(
4745
4884
  "matched gate rule has invalid profile: " + ", ".join(sorted(invalid_rule_profiles))
4746
4885
  )
4747
4886
  rule_profiles = raw_rule_profiles
4748
- if "micro" in rule_profiles and detected_profile == "standard":
4887
+ if task_kind == "change" and "micro" in rule_profiles and detected_profile == "standard":
4749
4888
  detected_profile = "micro"
4750
4889
  profile_reasons.append("matched gate rule with profile=micro")
4751
- if "standard" in rule_profiles and detected_profile == "micro":
4890
+ if task_kind == "change" and "standard" in rule_profiles and detected_profile == "micro":
4752
4891
  detected_profile = "standard"
4753
4892
  profile_reasons.append("matched gate rule with profile=standard")
4754
4893
 
@@ -4761,10 +4900,23 @@ def _resolve_execution_plan(
4761
4900
  "prod_config",
4762
4901
  "release_or_tooling",
4763
4902
  }
4903
+ default_high_path_categories: set[str] = set()
4904
+ for path in classification_inputs:
4905
+ per_path = set(_classify_paths([path])["categories"])
4906
+ default_high_path_categories.update(
4907
+ per_path & {"db", "gateway", "prod_config", "release_or_tooling"}
4908
+ )
4909
+ if "ui" not in per_path:
4910
+ default_high_path_categories.update(
4911
+ per_path & {"auth", "payment", "file_transfer"}
4912
+ )
4913
+ intent_risk_candidates = sorted(set(intent_categories) & high_categories)
4764
4914
  high_signals: list[str] = []
4765
- if categories & high_categories and not docs_or_tests_only:
4766
- high_signals.append("high-risk category: " + ", ".join(sorted(categories & high_categories)))
4767
- if "high-risk" in rule_profiles:
4915
+ if task_kind == "change" and default_high_path_categories and not docs_or_tests_only:
4916
+ high_signals.append(
4917
+ "high-risk path category: " + ", ".join(sorted(default_high_path_categories))
4918
+ )
4919
+ if task_kind == "change" and "high-risk" in rule_profiles:
4768
4920
  high_signals.append("matched gate rule with profile=high-risk")
4769
4921
  if high_signals:
4770
4922
  detected_profile = "high-risk"
@@ -4817,40 +4969,68 @@ def _resolve_execution_plan(
4817
4969
  and categories & {"api", "db", "auth", "payment", "file_transfer", "gateway", "prod_config"}
4818
4970
  )
4819
4971
  review_required = bool(
4820
- not terminal_maintenance
4972
+ task_kind == "change"
4821
4973
  and (effective_profile == "high-risk" or writer_count > 1 or cross_module_contract_risk or rule_review)
4822
4974
  )
4823
4975
  design_required = bool(
4824
- not terminal_maintenance
4976
+ task_kind == "change"
4825
4977
  and (rule_design or (effective_profile == "high-risk" and cross_module))
4826
4978
  )
4827
- has_task_signal = bool(classification_inputs or _text(intent))
4828
- workspace_dirty = bool(_working_tree_paths(repo))
4979
+ dirty_paths = _working_tree_paths(repo)
4980
+ workspace_dirty = bool(dirty_paths)
4981
+ dirty_outside_plan = [
4982
+ path for path in dirty_paths if not _path_is_owned(path, normalized_planned_paths)
4983
+ ] if normalized_planned_paths else list(dirty_paths)
4984
+ active_writer = _has_registered_active_task(repo)
4829
4985
  configured_isolation = _task_isolation(cfg)
4830
- if terminal_maintenance or not has_task_signal:
4986
+ if continue_direct and task_kind != "change":
4987
+ raise APError("--continue-direct is valid only for task-kind=change")
4988
+ if continue_direct and not normalized_planned_paths:
4989
+ raise APError("--continue-direct requires every current task path via --planned-path")
4990
+ continued_direct = bool(
4991
+ continue_direct
4992
+ and configured_isolation == "adaptive"
4993
+ and writer_count == 1
4994
+ and not active_writer
4995
+ and not dirty_outside_plan
4996
+ )
4997
+ if task_kind != "change":
4831
4998
  execution_mode = "none"
4832
- elif configured_isolation == "worktree" or writer_count > 1 or workspace_dirty:
4999
+ elif continued_direct:
5000
+ execution_mode = "direct"
5001
+ elif configured_isolation == "worktree" or writer_count > 1 or workspace_dirty or active_writer:
4833
5002
  execution_mode = "isolated"
4834
5003
  else:
4835
5004
  execution_mode = "direct"
4836
5005
  execution_reasons.append(
4837
5006
  "execution mode is adaptive: clean single-writer work is direct; dirty or parallel work is isolated"
4838
5007
  )
5008
+ if continued_direct:
5009
+ execution_reasons.append(
5010
+ "continued direct mode: all current dirty paths are covered by declared planned paths"
5011
+ )
4839
5012
 
4840
5013
  needs_jenkins = False
4841
5014
  needs_target = False
4842
5015
  needs_dd = design_required
4843
5016
 
5017
+ optional_agents = _optional_agent_candidates(
5018
+ task_kind=task_kind,
5019
+ intent=intent,
5020
+ categories=categories,
5021
+ cross_module=cross_module,
5022
+ profile=effective_profile,
5023
+ )
4844
5024
  agent_plan = _agent_execution_plan(
4845
5025
  effective_profile,
4846
5026
  categories,
4847
5027
  classification,
4848
5028
  parallel_writers=writer_count,
4849
5029
  review_required=review_required,
5030
+ optional_roles=optional_agents,
4850
5031
  )
4851
5032
  mechanism_plan = _mechanism_plan(
4852
- has_task_signal=has_task_signal,
4853
- terminal_maintenance=terminal_maintenance,
5033
+ task_kind=task_kind,
4854
5034
  execution_mode=execution_mode,
4855
5035
  review_required=review_required,
4856
5036
  design_required=design_required,
@@ -4863,7 +5043,9 @@ def _resolve_execution_plan(
4863
5043
  "planned_files": normalized_planned_paths,
4864
5044
  "classification_files": classification_inputs,
4865
5045
  "intent_provided": bool(_text(intent)),
5046
+ "task_kind": task_kind,
4866
5047
  "intent_categories": intent_categories,
5048
+ "intent_risk_candidates": intent_risk_candidates,
4867
5049
  "reasons": execution_reasons,
4868
5050
  "configured_profile": configured_profile,
4869
5051
  "requested_profile": requested_profile_value or None,
@@ -4875,6 +5057,10 @@ def _resolve_execution_plan(
4875
5057
  "execution_mode": execution_mode,
4876
5058
  "terminal_maintenance": terminal_maintenance,
4877
5059
  "workspace_dirty": workspace_dirty,
5060
+ "dirty_paths": dirty_paths,
5061
+ "dirty_outside_plan": dirty_outside_plan,
5062
+ "continued_direct": continued_direct,
5063
+ "active_writer": active_writer,
4878
5064
  "parallel_writers": writer_count,
4879
5065
  "cross_module": cross_module,
4880
5066
  "review_required": review_required,
@@ -4893,6 +5079,7 @@ def _resolve_execution_plan(
4893
5079
  parallel_writers=writer_count,
4894
5080
  review_required=review_required,
4895
5081
  ),
5082
+ "optional_agents": optional_agents,
4896
5083
  "agent_plan": agent_plan,
4897
5084
  "mechanism_plan": mechanism_plan,
4898
5085
  }
@@ -4923,6 +5110,8 @@ def cmd_classify(args: argparse.Namespace) -> None:
4923
5110
  planned_paths=list(getattr(args, "planned_path", []) or []),
4924
5111
  intent="\n".join(part for part in intent_parts if part),
4925
5112
  parallel_writers=int(getattr(args, "writers", 1) or 1),
5113
+ requested_task_kind=_text(getattr(args, "task_kind", "")),
5114
+ continue_direct=bool(getattr(args, "continue_direct", False)),
4926
5115
  )
4927
5116
  risk = {"micro": "P3", "standard": "P2", "high-risk": "P1"}[plan["profile"]]
4928
5117
  commands: list[str] = []
@@ -4937,6 +5126,7 @@ def cmd_classify(args: argparse.Namespace) -> None:
4937
5126
  print(json.dumps(result, ensure_ascii=False, indent=2))
4938
5127
  else:
4939
5128
  print(f"[classify] risk={risk}")
5129
+ print(f"[classify] task_kind={result['task_kind']}")
4940
5130
  print(f"[classify] profile={result['profile']}")
4941
5131
  print(f"[classify] effective_mode={result['effective_mode']}")
4942
5132
  print(f"[classify] execution_mode={result['execution_mode']}")
@@ -4945,14 +5135,22 @@ def cmd_classify(args: argparse.Namespace) -> None:
4945
5135
  print(f"[classify] selected_scope={result['selected_scope']}")
4946
5136
  print("[classify] categories=" + (", ".join(result["categories"]) or "(none)"))
4947
5137
  print("[classify] agents=" + (", ".join(result["recommended_agents"]) or "(main agent only)"))
5138
+ print(
5139
+ "[classify] optional_agents="
5140
+ + (", ".join(result["optional_agents"]) or "(none)")
5141
+ )
4948
5142
  print(f"[classify] agent_strategy={result['agent_plan']['strategy']}")
4949
5143
  print(
4950
5144
  "[classify] required_mechanisms="
4951
5145
  + (", ".join(result["mechanism_plan"]["required"]) or "(none)")
4952
5146
  )
4953
5147
  print(
4954
- "[classify] not_required="
4955
- + (", ".join(result["mechanism_plan"]["not_required"]) or "(none)")
5148
+ "[classify] optional_when_beneficial="
5149
+ + (", ".join(result["mechanism_plan"]["optional_when_beneficial"]) or "(none)")
5150
+ )
5151
+ print(
5152
+ "[classify] forbidden="
5153
+ + (", ".join(result["mechanism_plan"]["forbidden"]) or "(none)")
4956
5154
  )
4957
5155
  for stage in result["agent_plan"]["stages"]:
4958
5156
  print(
@@ -5217,6 +5415,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
5217
5415
 
5218
5416
  missing: List[str] = []
5219
5417
  validation_errors: List[str] = []
5418
+ advisories: List[str] = []
5220
5419
  validation_errors.extend(_workflow_policy_issues(repo, cfg))
5221
5420
 
5222
5421
  mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
@@ -5303,9 +5502,23 @@ def cmd_doctor(args: argparse.Namespace) -> None:
5303
5502
  if on_unmapped not in {"error", "fallback"}:
5304
5503
  validation_errors.append("validation.on_unmapped must be error or fallback")
5305
5504
  try:
5306
- _final_gate_budget(cfg)
5505
+ final_budget = _final_gate_budget(cfg)
5506
+ if final_budget["command_seconds"] > _RECOMMENDED_FINAL_COMMAND_SECONDS:
5507
+ advisories.append(
5508
+ "validation.max_command_seconds exceeds the recommended 120s default; "
5509
+ "keep the affected-scope route targeted"
5510
+ )
5511
+ if final_budget["total_seconds"] > _RECOMMENDED_FINAL_TOTAL_SECONDS:
5512
+ advisories.append(
5513
+ "validation.max_total_seconds exceeds the recommended 180s default; "
5514
+ "keep the final gate bounded to affected scope"
5515
+ )
5307
5516
  except APError as exc:
5308
5517
  validation_errors.append(str(exc))
5518
+ final_budget = {
5519
+ "command_seconds": _RECOMMENDED_FINAL_COMMAND_SECONDS,
5520
+ "total_seconds": _RECOMMENDED_FINAL_TOTAL_SECONDS,
5521
+ }
5309
5522
  routes = validation_cfg.get("routes") or []
5310
5523
  if not isinstance(routes, list):
5311
5524
  validation_errors.append("validation.routes must be a list")
@@ -5324,6 +5537,20 @@ def cmd_doctor(args: argparse.Namespace) -> None:
5324
5537
  validation_errors.append(
5325
5538
  f"validation.routes[{index}] references missing commands.{command_name}"
5326
5539
  )
5540
+ if "timeout_seconds" in route:
5541
+ try:
5542
+ route_timeout = _positive_seconds(
5543
+ route.get("timeout_seconds"),
5544
+ final_budget["command_seconds"],
5545
+ f"validation.routes[{index}].timeout_seconds",
5546
+ )
5547
+ if route_timeout > final_budget["command_seconds"]:
5548
+ advisories.append(
5549
+ f"validation.routes[{index}].timeout_seconds exceeds max_command_seconds "
5550
+ "and will be capped"
5551
+ )
5552
+ except APError as exc:
5553
+ validation_errors.append(str(exc))
5327
5554
  fallback_name = _command_name(validation_cfg.get("fallback_command"))
5328
5555
  if on_unmapped == "fallback" and not fallback_name:
5329
5556
  validation_errors.append(
@@ -5390,6 +5617,8 @@ def cmd_doctor(args: argparse.Namespace) -> None:
5390
5617
  "pass",
5391
5618
  {"mode": mode, "completion": completion, "access_fields": len(_REQUIRED_ACCESS_FIELDS)},
5392
5619
  )
5620
+ for advisory in advisories:
5621
+ print(f"[doctor] WARN: {advisory}")
5393
5622
  print("[doctor] OK")
5394
5623
 
5395
5624
 
@@ -6600,6 +6829,50 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6600
6829
  repo = Path(args.repo).resolve()
6601
6830
  ensure_git_repo(repo)
6602
6831
  cfg = _load_cfg(repo)
6832
+ _require_control_checkout(repo)
6833
+ task_id = _validate_task_id(args.task_id)
6834
+ owned_paths = sorted({_normalize_owned_path(item) for item in (args.owned_path or [])})
6835
+ if not owned_paths:
6836
+ raise APError("task-start requires at least one --owned-path.")
6837
+ if _is_terminal_ledger_maintenance(owned_paths):
6838
+ raise APError(
6839
+ "Pure taskbook/closure/archive reconciliation is terminal maintenance and must not "
6840
+ "create another task lifecycle. Run the targeted document check, commit once, and push."
6841
+ )
6842
+ writer_count = max(1, int(getattr(args, "writers", 1) or 1))
6843
+ if writer_count != 1:
6844
+ raise APError(
6845
+ "task-start creates exactly one writer lease and one worktree. Start each parallel "
6846
+ "writer as its own task ID; use --writers only with classify for planning."
6847
+ )
6848
+ continue_direct = bool(getattr(args, "continue_direct", False))
6849
+ explicit_lifecycle = bool(
6850
+ getattr(args, "isolated", False)
6851
+ or getattr(args, "review_required", False)
6852
+ or getattr(args, "force_lifecycle", False)
6853
+ or continue_direct
6854
+ )
6855
+ preflight_plan = _resolve_execution_plan(
6856
+ cfg,
6857
+ repo,
6858
+ planned_paths=owned_paths,
6859
+ parallel_writers=writer_count,
6860
+ requested_task_kind="change",
6861
+ continue_direct=continue_direct,
6862
+ )
6863
+ if continue_direct and preflight_plan["execution_mode"] != "direct":
6864
+ detail = ", ".join(preflight_plan["dirty_outside_plan"]) or "policy or active-writer conflict"
6865
+ raise APError(
6866
+ "Cannot continue the existing direct task because isolation is still required: "
6867
+ + detail
6868
+ )
6869
+ if not preflight_plan["mechanism_plan"]["lifecycle_required"] and not explicit_lifecycle:
6870
+ raise APError(
6871
+ "This clean serial task does not need a machine task lifecycle. Work directly on "
6872
+ "the current branch, run the routed final gate, commit, and push. Use task-start "
6873
+ "only when classify requires isolation/review or the user explicitly requests it."
6874
+ )
6875
+
6603
6876
  _require_workflow_policy_clean(repo, cfg)
6604
6877
  configured_isolation = _task_isolation(cfg)
6605
6878
  access_issues = _access_config_issues(cfg)
@@ -6608,8 +6881,6 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6608
6881
  "Project initialization is incomplete; fill docs/ENGINEERING.md before starting work:\n- "
6609
6882
  + "\n- ".join(access_issues)
6610
6883
  )
6611
- task_id = _validate_task_id(args.task_id)
6612
- _require_control_checkout(repo)
6613
6884
  remote, target_branch, base_ref = _task_remote_and_target(cfg, args)
6614
6885
  concurrency_cfg = _concurrency_cfg(cfg)
6615
6886
  timeout_s = float(concurrency_cfg.get("lock_timeout_sec") or 30)
@@ -6626,20 +6897,6 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6626
6897
  if not getattr(args, "no_fetch", False) and base_ref.startswith(f"{remote}/"):
6627
6898
  _fetch_target(repo, remote, target_branch)
6628
6899
  base_sha = _resolve_commit(repo, base_ref)
6629
- owned_paths = sorted({_normalize_owned_path(item) for item in (args.owned_path or [])})
6630
- if not owned_paths:
6631
- raise APError("task-start requires at least one --owned-path.")
6632
- if _is_terminal_ledger_maintenance(owned_paths):
6633
- raise APError(
6634
- "Pure taskbook/closure/archive reconciliation is terminal maintenance and must not "
6635
- "create another task lifecycle. Run the targeted document check, commit once, and push."
6636
- )
6637
- writer_count = max(1, int(getattr(args, "writers", 1) or 1))
6638
- if writer_count != 1:
6639
- raise APError(
6640
- "task-start creates exactly one writer lease and one worktree. Start each parallel "
6641
- "writer as its own task ID; use --writers only with classify for planning."
6642
- )
6643
6900
  registry_dir = _task_state_root(repo) / "tasks"
6644
6901
  for manifest_path in sorted(registry_dir.glob("*.json")) if registry_dir.exists() else []:
6645
6902
  active_manifest = _read_json_object(manifest_path) or {}
@@ -6679,11 +6936,8 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6679
6936
  repo,
6680
6937
  planned_paths=owned_paths,
6681
6938
  parallel_writers=writer_count,
6682
- )
6683
- explicit_lifecycle = bool(
6684
- getattr(args, "isolated", False)
6685
- or getattr(args, "review_required", False)
6686
- or getattr(args, "force_lifecycle", False)
6939
+ requested_task_kind="change",
6940
+ continue_direct=continue_direct,
6687
6941
  )
6688
6942
  if not plan["mechanism_plan"]["lifecycle_required"] and not explicit_lifecycle:
6689
6943
  raise APError(
@@ -6702,15 +6956,25 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6702
6956
  )
6703
6957
  ) if registry_dir.exists() else False
6704
6958
  current_branch = _current_branch(repo)
6959
+ task_paths = _task_commit_paths(repo)
6960
+ direct_changes_owned = bool(
6961
+ continue_direct
6962
+ and all(_path_is_owned(path, owned_paths) for path in task_paths)
6963
+ )
6705
6964
  direct = bool(
6706
6965
  configured_isolation == "adaptive"
6707
6966
  and not bool(getattr(args, "isolated", False))
6708
6967
  and writer_count == 1
6709
6968
  and not other_active
6710
- and not _task_commit_paths(repo)
6969
+ and (not task_paths or direct_changes_owned)
6711
6970
  and current_branch
6712
6971
  and current_branch == target_branch
6713
6972
  )
6973
+ if continue_direct and not direct:
6974
+ raise APError(
6975
+ "Cannot register continued direct work on this checkout; verify target branch, "
6976
+ "owned paths, active writers, and concurrency.isolation"
6977
+ )
6714
6978
  if direct:
6715
6979
  direct_base = _resolve_commit(repo, "HEAD")
6716
6980
  manifest = {
@@ -6971,6 +7235,11 @@ def cmd_task_review(args: argparse.Namespace) -> None:
6971
7235
  reviewer = _text(getattr(args, "reviewer", "")) or _text(os.environ.get("CODEX_THREAD_ID"))
6972
7236
  if not reviewer:
6973
7237
  raise APError("task-review requires --reviewer or CODEX_THREAD_ID.")
7238
+ if bool(manifest.get("review_required")):
7239
+ if not _text(getattr(args, "reviewer", "")):
7240
+ raise APError("Independent review requires an explicit --reviewer identity.")
7241
+ if reviewer == _text(manifest.get("owner")):
7242
+ raise APError("Independent reviewer identity must differ from the task lifecycle owner.")
6974
7243
  manifest["review"] = {
6975
7244
  "verdict": args.verdict,
6976
7245
  "diff_base": _text(manifest.get("base_sha")),
@@ -7925,6 +8194,8 @@ def main(argv: Optional[List[str]] = None) -> int:
7925
8194
  s.add_argument("--planned-path", action="append")
7926
8195
  s.add_argument("--intent")
7927
8196
  s.add_argument("--intent-file")
8197
+ s.add_argument("--task-kind", choices=sorted(_REQUESTED_TASK_KINDS), default="auto")
8198
+ s.add_argument("--continue-direct", action="store_true")
7928
8199
  s.add_argument("--writers", type=int, default=1)
7929
8200
  s.add_argument("--json", action="store_true")
7930
8201
  s.set_defaults(func=cmd_classify)
@@ -8033,6 +8304,7 @@ def main(argv: Optional[List[str]] = None) -> int:
8033
8304
  s.add_argument("--writers", type=int, default=1)
8034
8305
  s.add_argument("--isolated", action="store_true")
8035
8306
  s.add_argument("--review-required", action="store_true")
8307
+ s.add_argument("--continue-direct", action="store_true")
8036
8308
  s.add_argument(
8037
8309
  "--force-lifecycle",
8038
8310
  action="store_true",