@elvis1513/auto-coding-skill 4.0.0 → 4.1.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.
@@ -49,7 +49,7 @@ _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
49
49
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
50
50
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
51
51
  "schema_version": 1,
52
- "managed_versions": {"agents": "4.0.0", "engineering": "4.0.0"},
52
+ "managed_versions": {"agents": "4.1.0", "engineering": "4.1.0"},
53
53
  "known_official_engineering_body_sha256": [
54
54
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
55
55
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -575,10 +575,6 @@ def _copy_conflicts(src: Path, dst: Path) -> list[Path]:
575
575
  return conflicts
576
576
 
577
577
 
578
- _MANAGED_EXTRA_CLEANUP_DIRS = {
579
- Path("data/templates/bridges"),
580
- }
581
-
582
578
  _CORE_DOC_TEMPLATES: list[Path] = []
583
579
 
584
580
 
@@ -634,8 +630,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
634
630
  if _text(workflow_cfg.get("completion")).lower() != "push":
635
631
  workflow_cfg["completion"] = "push"
636
632
  changed.append("workflow.completion")
637
- if _text(workflow_cfg.get("skill_version")) != "4.0.0":
638
- workflow_cfg["skill_version"] = "4.0.0"
633
+ if _text(workflow_cfg.get("skill_version")) != "4.1.0":
634
+ workflow_cfg["skill_version"] = "4.1.0"
639
635
  changed.append("workflow.skill_version")
640
636
 
641
637
  commands_cfg = cfg.setdefault("commands", {})
@@ -716,17 +712,6 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
716
712
  gate_cfg["rules"] = []
717
713
  changed.append("gate.rules")
718
714
 
719
- if not validation_routes:
720
- validation_routes.append(
721
- {
722
- "name": "project-code",
723
- "paths": ["**"],
724
- "exclude": ["*.md", "docs/**"],
725
- "commands": ["project_fast"],
726
- }
727
- )
728
- changed.append("validation.routes[0]")
729
-
730
715
  concurrency_cfg = cfg.setdefault("concurrency", {})
731
716
  if not isinstance(concurrency_cfg, dict):
732
717
  concurrency_cfg = {}
@@ -822,8 +807,19 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
822
807
  source_root = _find_skill_asset_root(repo)
823
808
  templates = source_root / "data" / "templates"
824
809
  template_engineering = templates / "ENGINEERING.md"
810
+ template_agents = templates / "bridges" / "AGENTS.md"
825
811
  actions: list[dict] = []
826
812
 
813
+ registry = _task_state_root(repo) / "tasks"
814
+ active_manifests = sorted(registry.glob("*.json")) if registry.exists() else []
815
+ if active_manifests:
816
+ names = ", ".join(path.name for path in active_manifests)
817
+ raise APError(
818
+ "Upgrade refused because registered tasks are still active: "
819
+ f"{names}. Finish, integrate, or clean them with the installed runtime first; "
820
+ "workflow semantics must not change mid-task."
821
+ )
822
+
827
823
  def add_action(kind: str, path: Path, action: str, detail: str = "") -> None:
828
824
  actions.append({
829
825
  "kind": kind,
@@ -836,7 +832,15 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
836
832
  # are safe migration inputs; every remaining match is project-owned and must
837
833
  # be handled explicitly instead of being overwritten by a partial upgrade.
838
834
  workflow_plans = _workflow_policy_plans(repo)
839
- workflow_issues = [issue for plan in workflow_plans for issue in plan["issues"]]
835
+ # Root AGENTS.md is a whole-file managed bridge in 4.1. Unknown legacy text
836
+ # is archived and replaced, so only ENGINEERING policy conflicts block the
837
+ # upgrade preflight.
838
+ workflow_issues = [
839
+ issue
840
+ for plan in workflow_plans
841
+ if plan["path"] == "docs/ENGINEERING.md"
842
+ for issue in plan["issues"]
843
+ ]
840
844
  if workflow_issues:
841
845
  raise APError(
842
846
  "Upgrade preflight found unknown workflow policy conflicts; no files were written:\n- "
@@ -851,6 +855,35 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
851
855
  body_start = frontmatter[1] if frontmatter else 0
852
856
  engineering_plan["output"] = current[:body_start] + template_body
853
857
 
858
+ section_migrations = [
859
+ item
860
+ for item in engineering_plan.get("migrations") or []
861
+ if _text(item.get("id")).startswith("engineering-section-")
862
+ ]
863
+ if section_migrations and engineering_plan.get("original"):
864
+ version_match = re.search(
865
+ r"auto-coding-skill:managed-workflow:start\s+version=([0-9]+\.[0-9]+\.[0-9]+)",
866
+ template_engineering.read_text(encoding="utf-8"),
867
+ )
868
+ version = version_match.group(1) if version_match else "current"
869
+ archive_header = (
870
+ f"# Archived ENGINEERING.md before auto-coding-skill {version} docs convergence\n\n"
871
+ "This file is historical and non-authoritative. Known duplicate workflow sections\n"
872
+ "were removed from docs/ENGINEERING.md. Move any still-current project facts into\n"
873
+ "docs/ENGINEERING.md project-fact sections or docs/project/.\n\n---\n\n"
874
+ )
875
+ archive_content = archive_header + engineering_plan["original"]
876
+ archive_dir = repo / "docs" / "archive" / "workflow"
877
+ archive = archive_dir / f"ENGINEERING.pre-{version}.md"
878
+ if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
879
+ digest = hashlib.sha256(engineering_plan["original"].encode("utf-8")).hexdigest()[:12]
880
+ archive = archive_dir / f"ENGINEERING.pre-{version}-{digest}.md"
881
+ if not archive.exists():
882
+ add_action("policy", archive, "archive", "before duplicate workflow section cleanup")
883
+ if write:
884
+ archive.parent.mkdir(parents=True, exist_ok=True)
885
+ archive.write_text(archive_content, encoding="utf-8")
886
+
854
887
  tool_files = [
855
888
  (
856
889
  source_root / "data" / "templates" / "tools" / "ap.py",
@@ -889,26 +922,39 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
889
922
  for dst in _iter_files(project_skill):
890
923
  rel = dst.relative_to(project_skill)
891
924
  if not (source_root / rel).exists():
892
- if rel.parts[:3] == ("data", "templates", "docs"):
893
- continue
894
- if rel.parent in _MANAGED_EXTRA_CLEANUP_DIRS:
895
- add_action("skill", dst, "delete", "stale managed template")
896
- if write:
897
- dst.unlink()
898
- else:
899
- add_action("skill", dst, "extra", "present only in project copy")
925
+ add_action("skill", dst, "delete", "stale file in fully managed Skill copy")
926
+ if write:
927
+ dst.unlink()
900
928
  else:
901
929
  add_action("skill", project_skill, "create", "install runtime required by the project launcher")
902
930
  if write:
903
931
  copy_tree(source_root, project_skill)
904
932
 
905
- agents_plan = workflow_plan_by_path["AGENTS.md"]
906
933
  agents_path = repo / "AGENTS.md"
907
- if agents_plan["output"] != agents_plan["original"]:
908
- migrated = ", ".join(item["id"] for item in agents_plan["migrations"])
909
- add_action("policy", agents_path, "migrate", migrated)
934
+ canonical_agents = template_agents.read_text(encoding="utf-8") if template_agents.exists() else ""
935
+ current_agents = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
936
+ if canonical_agents and current_agents != canonical_agents:
937
+ if current_agents:
938
+ archive_dir = repo / "docs" / "archive" / "workflow"
939
+ archive_header = (
940
+ "# Archived AGENTS.md before auto-coding-skill 4.1.0\n\n"
941
+ "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
942
+ "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
943
+ "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
944
+ )
945
+ archive_content = archive_header + current_agents
946
+ archive = archive_dir / "AGENTS.pre-4.1.0.md"
947
+ if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
948
+ digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
949
+ archive = archive_dir / f"AGENTS.pre-4.1.0-{digest}.md"
950
+ if not archive.exists():
951
+ add_action("policy", archive, "archive", "historical and non-authoritative")
952
+ if write:
953
+ archive.parent.mkdir(parents=True, exist_ok=True)
954
+ archive.write_text(archive_content, encoding="utf-8")
955
+ add_action("policy", agents_path, "replace", "fully managed canonical AGENTS.md")
910
956
  if write:
911
- agents_path.write_text(agents_plan["output"], encoding="utf-8")
957
+ agents_path.write_text(canonical_agents, encoding="utf-8")
912
958
 
913
959
  docs_template = templates / "docs"
914
960
  for rel in _CORE_DOC_TEMPLATES:
@@ -928,6 +974,10 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
928
974
  engineering = repo / "docs" / "ENGINEERING.md"
929
975
  if engineering.exists() and template_engineering.exists():
930
976
  planned_engineering = engineering_plan["output"] or engineering.read_text(encoding="utf-8")
977
+ planned_engineering = _sync_managed_workflow_text(
978
+ planned_engineering,
979
+ template_engineering.read_text(encoding="utf-8"),
980
+ )
931
981
  current_cfg, body = _parse_frontmatter_markdown_text(planned_engineering, engineering)
932
982
  template_cfg, _ = _read_frontmatter_markdown(template_engineering)
933
983
  merged_cfg = json.loads(json.dumps(current_cfg))
@@ -1223,7 +1273,7 @@ def _load_workflow_migration_policy(repo: Path) -> dict:
1223
1273
  for index, fragment in enumerate(policy["known_official_fragments"]):
1224
1274
  if not isinstance(fragment, dict):
1225
1275
  raise APError(f"Workflow migration policy fragment[{index}] must be an object")
1226
- if fragment.get("match") not in {"exact-line", "exact-block"}:
1276
+ if fragment.get("match") not in {"exact-line", "exact-block", "heading-section"}:
1227
1277
  raise APError(f"Workflow migration policy fragment[{index}] has invalid match mode")
1228
1278
  if not _text(fragment.get("id")) or not isinstance(fragment.get("paths"), list):
1229
1279
  raise APError(f"Workflow migration policy fragment[{index}] is incomplete")
@@ -1292,6 +1342,30 @@ def _managed_document_span(text: str, kind: str, rel: str) -> Optional[tuple[int
1292
1342
  return starts[0].start(), ends[0].end()
1293
1343
 
1294
1344
 
1345
+ def _sync_managed_workflow_text(current: str, template: str) -> str:
1346
+ """Install the canonical managed workflow while preserving project facts."""
1347
+ template_span = _managed_document_span(template, "workflow", "template ENGINEERING.md")
1348
+ if not template_span:
1349
+ raise APError("Packaged ENGINEERING template has no managed workflow block")
1350
+ block = template[template_span[0]:template_span[1]]
1351
+ current_span = _managed_document_span(current, "workflow", "docs/ENGINEERING.md")
1352
+ if current_span:
1353
+ return current[:current_span[0]] + block + current[current_span[1]:]
1354
+
1355
+ frontmatter = _frontmatter_span(current, "docs/ENGINEERING.md")
1356
+ body_start = frontmatter[1] if frontmatter else 0
1357
+ body = current[body_start:]
1358
+ heading = re.search(r"^# Engineering Workflow[^\n]*(?:\n|$)", body, flags=re.MULTILINE)
1359
+ insertion = body_start + (heading.end() if heading else 0)
1360
+ before = current[:insertion]
1361
+ after = current[insertion:]
1362
+ if before and not before.endswith("\n"):
1363
+ before += "\n"
1364
+ if after and not after.startswith("\n"):
1365
+ after = "\n" + after
1366
+ return before + block + after
1367
+
1368
+
1295
1369
  def _frontmatter_span(text: str, rel: str) -> Optional[tuple[int, int]]:
1296
1370
  if not text.startswith("---\n"):
1297
1371
  return None
@@ -1314,6 +1388,28 @@ def _known_fragment_spans(
1314
1388
  replacement = str(fragment.get("replacement") or "")
1315
1389
  match_mode = _text(fragment.get("match"))
1316
1390
  expected = str(fragment.get("text") or "").replace("\r\n", "\n")
1391
+ if fragment.get("match") == "heading-section":
1392
+ lines = visible.splitlines(keepends=True)
1393
+ offsets: list[int] = []
1394
+ cursor = 0
1395
+ for line in lines:
1396
+ offsets.append(cursor)
1397
+ cursor += len(line)
1398
+ for index, line in enumerate(lines):
1399
+ heading = re.match(r"^\s*(#{1,6})\s+(.+?)\s*#*\s*$", line.rstrip("\n"))
1400
+ if not heading or heading.group(2).strip() != expected.strip():
1401
+ continue
1402
+ level = len(heading.group(1))
1403
+ end_index = index + 1
1404
+ while end_index < len(lines):
1405
+ next_heading = re.match(r"^\s*(#{1,6})\s+", lines[end_index])
1406
+ if next_heading and len(next_heading.group(1)) <= level:
1407
+ break
1408
+ end_index += 1
1409
+ end = offsets[end_index] if end_index < len(offsets) else len(visible)
1410
+ start = offsets[index]
1411
+ found.append((start, end, fragment_id, visible.count("\n", 0, start) + 1, replacement, match_mode))
1412
+ continue
1317
1413
  if fragment.get("match") == "exact-line":
1318
1414
  cursor = 0
1319
1415
  for line in visible.splitlines(keepends=True):
@@ -1330,7 +1426,17 @@ def _known_fragment_spans(
1330
1426
  end = start + len(expected)
1331
1427
  found.append((start, end, fragment_id, visible.count("\n", 0, start) + 1, replacement, match_mode))
1332
1428
  cursor = end
1333
- return found
1429
+ section_spans = [
1430
+ (start, end)
1431
+ for start, end, _, _, _, match_mode in found
1432
+ if match_mode == "heading-section"
1433
+ ]
1434
+ return [
1435
+ item
1436
+ for item in found
1437
+ if item[5] == "heading-section"
1438
+ or not any(start <= item[0] and item[1] <= end for start, end in section_spans)
1439
+ ]
1334
1440
 
1335
1441
 
1336
1442
  def _workflow_document_plan(repo: Path, rel: str, policy: dict) -> dict:
@@ -1953,6 +2059,36 @@ def _path_is_owned(path: str, owned_paths: list[str]) -> bool:
1953
2059
  )
1954
2060
 
1955
2061
 
2062
+ def _owned_paths_overlap(left: list[str], right: list[str]) -> bool:
2063
+ for first in left:
2064
+ first = _normalize_owned_path(first)
2065
+ for second in right:
2066
+ second = _normalize_owned_path(second)
2067
+ if (
2068
+ first == "."
2069
+ or second == "."
2070
+ or first == second
2071
+ or first.startswith(second.rstrip("/") + "/")
2072
+ or second.startswith(first.rstrip("/") + "/")
2073
+ ):
2074
+ return True
2075
+ return False
2076
+
2077
+
2078
+ _TERMINAL_LEDGER_PATTERNS = [
2079
+ "docs/tasks/taskbook.md",
2080
+ "docs/tasks/closure-log.md",
2081
+ "docs/tasks/archive-index.md",
2082
+ "docs/tasks/archives/**",
2083
+ "docs/tasks/closures/**",
2084
+ "docs/archive/design/**",
2085
+ ]
2086
+
2087
+
2088
+ def _is_terminal_ledger_maintenance(paths: list[str]) -> bool:
2089
+ return bool(paths) and all(_path_matches(path, _TERMINAL_LEDGER_PATTERNS) for path in paths)
2090
+
2091
+
1956
2092
  def _task_managed_paths(cfg: dict, manifest: dict) -> list[str]:
1957
2093
  if int(manifest.get("schema") or 2) >= 3:
1958
2094
  return []
@@ -4208,9 +4344,10 @@ def _classification_for_categories(categories: set[str], file_count: int) -> dic
4208
4344
  "needs_dd": bool(
4209
4345
  categories
4210
4346
  & {"api", "db", "auth", "payment", "file_transfer", "gateway", "prod_config", "release_or_tooling"}
4211
- )
4212
- or file_count > 12,
4213
- "needs_adr": bool(categories & {"structure", "release_or_tooling"}) and not categories <= {"docs"},
4347
+ ),
4348
+ # Path names and file counts do not justify a durable architecture
4349
+ # record. The model or an explicit project rule decides.
4350
+ "needs_adr": False,
4214
4351
  "needs_browser": "ui" in categories,
4215
4352
  "needs_jenkins": bool(
4216
4353
  categories & {"release_or_tooling", "db", "auth", "payment", "gateway", "prod_config"}
@@ -4354,13 +4491,10 @@ def _agent_execution_plan(
4354
4491
  review_required: bool = False,
4355
4492
  ) -> dict:
4356
4493
  assignment_contract, result_contract = _agent_contract_shape()
4494
+ # Classification reports useful capabilities but never auto-dispatches
4495
+ # discovery roles. The model chooses delegation only when expected benefit
4496
+ # exceeds coordination cost.
4357
4497
  discovery_roles: list[str] = []
4358
- if categories & {"api", "release_or_tooling"}:
4359
- discovery_roles.append("docs_researcher")
4360
- if classification.get("needs_browser"):
4361
- discovery_roles.append("browser_debugger")
4362
- if profile == "high-risk" and not discovery_roles:
4363
- discovery_roles.append("explorer")
4364
4498
 
4365
4499
  policies = {
4366
4500
  "one_writer_per_worktree": True,
@@ -4471,6 +4605,7 @@ def _resolve_execution_plan(
4471
4605
  (docs_only_paths and str(impact["selected_scope"]) != "full")
4472
4606
  or _tests_only(classification_inputs)
4473
4607
  )
4608
+ terminal_maintenance = _is_terminal_ledger_maintenance(classification_inputs)
4474
4609
  if docs_or_tests_only and str(impact["selected_scope"]) != "full":
4475
4610
  detected_profile = "micro"
4476
4611
  profile_reasons.append("only docs/test files changed")
@@ -4503,9 +4638,6 @@ def _resolve_execution_plan(
4503
4638
  high_signals.append("high-risk category: " + ", ".join(sorted(categories & high_categories)))
4504
4639
  if "high-risk" in rule_profiles:
4505
4640
  high_signals.append("matched gate rule with profile=high-risk")
4506
- if len(classification_inputs) > 12 and not docs_or_tests_only:
4507
- high_signals.append("change spans more than 12 files")
4508
-
4509
4641
  if high_signals:
4510
4642
  detected_profile = "high-risk"
4511
4643
  profile_reasons.extend(high_signals)
@@ -4552,12 +4684,22 @@ def _resolve_execution_plan(
4552
4684
  _text(rule.get("design")).lower() in {"required", "true", "yes"}
4553
4685
  for rule in matching_rules
4554
4686
  )
4555
- review_required = bool(effective_profile == "high-risk" or writer_count > 1 or cross_module or rule_review)
4556
- design_required = bool(rule_design or (effective_profile == "high-risk" and cross_module))
4687
+ cross_module_contract_risk = bool(
4688
+ cross_module
4689
+ and categories & {"api", "db", "auth", "payment", "file_transfer", "gateway", "prod_config"}
4690
+ )
4691
+ review_required = bool(
4692
+ not terminal_maintenance
4693
+ and (effective_profile == "high-risk" or writer_count > 1 or cross_module_contract_risk or rule_review)
4694
+ )
4695
+ design_required = bool(
4696
+ not terminal_maintenance
4697
+ and (rule_design or (effective_profile == "high-risk" and cross_module))
4698
+ )
4557
4699
  has_task_signal = bool(classification_inputs or _text(intent))
4558
4700
  workspace_dirty = bool(_working_tree_paths(repo))
4559
4701
  configured_isolation = _task_isolation(cfg)
4560
- if not has_task_signal:
4702
+ if terminal_maintenance or not has_task_signal:
4561
4703
  execution_mode = "none"
4562
4704
  elif configured_isolation == "worktree" or writer_count > 1 or workspace_dirty:
4563
4705
  execution_mode = "isolated"
@@ -4595,6 +4737,7 @@ def _resolve_execution_plan(
4595
4737
  "requested_mode": requested_mode_value or None,
4596
4738
  "effective_mode": effective_mode,
4597
4739
  "execution_mode": execution_mode,
4740
+ "terminal_maintenance": terminal_maintenance,
4598
4741
  "workspace_dirty": workspace_dirty,
4599
4742
  "parallel_writers": writer_count,
4600
4743
  "cross_module": cross_module,
@@ -4920,12 +5063,15 @@ def cmd_doctor(args: argparse.Namespace) -> None:
4920
5063
  mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
4921
5064
  profile = str(workflow_cfg.get("profile") or "auto").strip().lower()
4922
5065
  completion = str(workflow_cfg.get("completion") or "").strip().lower()
5066
+ skill_version = _text(workflow_cfg.get("skill_version"))
4923
5067
  if mode != "dev":
4924
5068
  missing.append("workflow.mode (must be dev; external verification is owner-managed)")
4925
5069
  if profile not in _WORKFLOW_PROFILES:
4926
5070
  missing.append("workflow.profile (must be auto, micro, standard, or high-risk)")
4927
5071
  if completion != "push":
4928
5072
  missing.append("workflow.completion (must be push)")
5073
+ if skill_version.startswith("4.1") and _text(docs_cfg.get("framework")) != "engineering-centered":
5074
+ missing.append("docs.framework (must be engineering-centered for auto-coding-skill 4.1)")
4929
5075
  isolation = _text(concurrency_cfg.get("isolation")).lower() or "adaptive"
4930
5076
  if isolation not in {"adaptive", "worktree"}:
4931
5077
  validation_errors.append(
@@ -5028,6 +5174,26 @@ def cmd_doctor(args: argparse.Namespace) -> None:
5028
5174
  validation_errors.append(
5029
5175
  "validation.routes is empty and no 3.x commands.gate_changed compatibility fallback exists"
5030
5176
  )
5177
+ tracked_validation_paths = [
5178
+ path
5179
+ for path in _tracked_files(repo)
5180
+ if not _path_matches(
5181
+ path,
5182
+ [
5183
+ "*.md",
5184
+ "docs/**",
5185
+ ".agents/**",
5186
+ ".local/**",
5187
+ "AGENTS.md",
5188
+ ],
5189
+ )
5190
+ ]
5191
+ if tracked_validation_paths:
5192
+ try:
5193
+ tracked_plan = _validation_plan(cfg, tracked_validation_paths)
5194
+ _validate_validation_plan(cfg, tracked_plan)
5195
+ except APError as exc:
5196
+ validation_errors.append(f"tracked validation coverage: {exc}")
5031
5197
 
5032
5198
  repo_docs: dict[str, Path] = {}
5033
5199
  api_doc = Path(repo, str(docs_cfg.get("api_doc", "docs/interfaces/api.md")))
@@ -6300,6 +6466,30 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6300
6466
  owned_paths = sorted({_normalize_owned_path(item) for item in (args.owned_path or [])})
6301
6467
  if not owned_paths:
6302
6468
  raise APError("task-start requires at least one --owned-path.")
6469
+ if _is_terminal_ledger_maintenance(owned_paths):
6470
+ raise APError(
6471
+ "Pure taskbook/closure/archive reconciliation is terminal maintenance and must not "
6472
+ "create another task lifecycle. Run the targeted document check, commit once, and push."
6473
+ )
6474
+ writer_count = max(1, int(getattr(args, "writers", 1) or 1))
6475
+ if writer_count != 1:
6476
+ raise APError(
6477
+ "task-start creates exactly one writer lease and one worktree. Start each parallel "
6478
+ "writer as its own task ID; use --writers only with classify for planning."
6479
+ )
6480
+ registry_dir = _task_state_root(repo) / "tasks"
6481
+ for manifest_path in sorted(registry_dir.glob("*.json")) if registry_dir.exists() else []:
6482
+ active_manifest = _read_json_object(manifest_path) or {}
6483
+ if _text(active_manifest.get("state")) in {"integrated", "cleanup-pending"}:
6484
+ continue
6485
+ active_owned = active_manifest.get("owned_paths") or []
6486
+ if isinstance(active_owned, list) and _owned_paths_overlap(owned_paths, active_owned):
6487
+ active_id = _text(active_manifest.get("task_id")) or manifest_path.stem
6488
+ raise APError(
6489
+ f"Owned paths overlap active task {active_id}: "
6490
+ + ", ".join(active_owned)
6491
+ + ". Split ownership into non-overlapping task units or finish the active writer first."
6492
+ )
6303
6493
  depends_on: list[str] = []
6304
6494
  prerequisite_shas: dict[str, str] = {}
6305
6495
  for raw_dependency in args.depends_on or []:
@@ -6321,7 +6511,6 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6321
6511
  if not owner:
6322
6512
  raise APError("task-start requires --owner or CODEX_THREAD_ID.")
6323
6513
  writer = _text(getattr(args, "writer", "")) or owner
6324
- writer_count = max(1, int(getattr(args, "writers", 1) or 1))
6325
6514
  plan = _resolve_execution_plan(
6326
6515
  cfg,
6327
6516
  repo,
@@ -6352,6 +6541,7 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6352
6541
  direct_base = _resolve_commit(repo, "HEAD")
6353
6542
  manifest = {
6354
6543
  "schema": 3,
6544
+ "skill_version": _text((cfg.get("workflow") or {}).get("skill_version")),
6355
6545
  "execution_mode": "direct",
6356
6546
  "review_required": review_required,
6357
6547
  "task_id": task_id,
@@ -6431,6 +6621,7 @@ def cmd_task_start(args: argparse.Namespace) -> None:
6431
6621
  )
6432
6622
  manifest = {
6433
6623
  "schema": 3,
6624
+ "skill_version": _text((cfg.get("workflow") or {}).get("skill_version")),
6434
6625
  "execution_mode": "isolated",
6435
6626
  "review_required": review_required,
6436
6627
  "task_id": task_id,
@@ -5,6 +5,41 @@ from __future__ import annotations
5
5
 
6
6
 
7
7
  TEMPLATES: dict[str, dict[str, str]] = {
8
+ "project": {
9
+ "docs/project/overview.md": """# Project Overview
10
+
11
+ Record durable project facts, not workflow rules.
12
+
13
+ ## Product scope and non-goals
14
+ ## Domain boundaries and invariants
15
+ ## Users, roles, and critical journeys
16
+ ## External systems and safety boundaries
17
+ ## Current contracts and decision links
18
+ """,
19
+ "docs/project/repository-map.md": """# Repository Map
20
+
21
+ Map existing ownership and reuse points. Keep behavior details in code/tests.
22
+
23
+ | Area | Paths | Responsibility | Generated / source | Validation route |
24
+ | --- | --- | --- | --- | --- |
25
+
26
+ ## Cross-module dependencies
27
+ ## Shared components and helpers
28
+ ## Files or directories with special ownership
29
+ """,
30
+ "docs/project/runtime.md": """# Runtime And Deployment Facts
31
+
32
+ Record current environment topology and operating constraints, not normal
33
+ development gate rules.
34
+
35
+ ## Local runtime
36
+ ## Shared services and dependencies
37
+ ## Jenkins and artifact flow
38
+ ## Deployment topology
39
+ ## External-device / production-write safeguards
40
+ ## Fixtures, simulators, and repeatable diagnostic entry points
41
+ """,
42
+ },
8
43
  "api": {
9
44
  "docs/interfaces/api.md": """# API Contract
10
45
 
@@ -23,10 +58,10 @@ Record only current, externally relevant endpoints or events.
23
58
  """,
24
59
  },
25
60
  "design": {
26
- "docs/design/_TEMPLATE-DD.md": """# DD — <Task ID> <Title>
61
+ "docs/design/_TEMPLATE-DD.md": """# DD — <Decision ID> <Title>
27
62
 
28
63
  - Status: Draft | Reviewed | Approved
29
- - Related task: `docs/tasks/taskbook.md`
64
+ - Related requirement / commit:
30
65
 
31
66
  ## Context and goal
32
67
  ## Scope and non-goals
@@ -56,7 +91,7 @@ Project conventions are authoritative. The generic checker is advisory unless
56
91
 
57
92
  - Status: Proposed | Accepted | Superseded
58
93
  - Date: YYYY-MM-DD
59
- - Related task: <task id>
94
+ - Related requirement / commit:
60
95
 
61
96
  ## Context
62
97
  ## Decision
@@ -67,7 +102,7 @@ Project conventions are authoritative. The generic checker is advisory unless
67
102
  """,
68
103
  },
69
104
  "review": {
70
- "docs/reviews/_TEMPLATE-REVIEW.md": """# Review — <Task ID>
105
+ "docs/reviews/_TEMPLATE-REVIEW.md": """# Review — <Change ID>
71
106
 
72
107
  - Scope:
73
108
  - Evidence:
@@ -79,7 +114,7 @@ List P0/P1/P2/P3 findings with impact, evidence, and remediation.
79
114
 
80
115
  ## Verdict
81
116
 
82
- PASS | PARTIAL | FAIL
117
+ approved | changes-requested
83
118
  """,
84
119
  },
85
120
  "testing": {