@elvis1513/auto-coding-skill 4.2.8 → 4.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,6 +11,7 @@ import contextlib
11
11
  import hashlib
12
12
  import datetime as _dt
13
13
  import fnmatch
14
+ import hmac
14
15
  import io
15
16
  import json
16
17
  import os
@@ -35,9 +36,31 @@ import uuid
35
36
  from pathlib import Path
36
37
  from typing import Iterator, Optional, List
37
38
 
38
- from core import APError, ensure_git_repo, copy_tree, run, load_yaml, find_config, run_shell, http_get_status, require_yaml
39
+ from core import (
40
+ APError,
41
+ PROJECT_CONFIG_PATH,
42
+ PROJECT_CONFIG_SCHEMA,
43
+ copy_tree,
44
+ ensure_git_repo,
45
+ http_get_status,
46
+ load_effective_config,
47
+ load_managed_config,
48
+ load_project_overrides,
49
+ merge_project_config,
50
+ parse_managed_config_payload,
51
+ parse_project_overrides_payload,
52
+ require_yaml,
53
+ run,
54
+ run_shell,
55
+ )
39
56
  from install_integrity import verify_managed_install
40
- from scaffold_templates import MANAGED_FRAMEWORK_DOCS, scaffold_groups, templates_for
57
+ from scaffold_templates import (
58
+ MANAGED_FRAMEWORK_DOCS,
59
+ PROJECT_FEEDBACK_PATTERNS,
60
+ PROJECT_OWNED_DOC_ROOTS,
61
+ scaffold_groups,
62
+ templates_for,
63
+ )
41
64
 
42
65
 
43
66
  _JENKINS_CRUMB_CACHE: dict[tuple[str, str], dict[str, str]] = {}
@@ -78,6 +101,102 @@ _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
78
101
  _REVIEW_DIFF_ARTIFACT_FORMAT = "git-binary-patch-v1"
79
102
  _REVIEW_DIFF_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024
80
103
  _REVIEW_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
104
+ _FEEDBACK_SCHEMAS = {
105
+ "auto-coding-skill-feedback/v1",
106
+ "auto-coding-skill-feedback/v2",
107
+ }
108
+ _FEEDBACK_COLLECTION_SCHEMA = "auto-coding-skill-feedback-collection/v2"
109
+ _FEEDBACK_RESOLUTION_SCHEMA = "auto-coding-skill-feedback-resolutions/v1"
110
+ _FEEDBACK_RESOLUTION_POLICY = Path("data/policies/feedback-resolutions-v1.json")
111
+ _FEEDBACK_RESOLUTION_MAX_BYTES = 64 * 1024
112
+ _FEEDBACK_REPORT_MAX_BYTES = 16 * 1024
113
+ _FEEDBACK_PROJECT_MAX_REPORTS = 100
114
+ _FEEDBACK_PROJECT_MAX_ENTRIES = 200
115
+ _FEEDBACK_COLLECTION_MAX_BYTES = 1024 * 1024
116
+ _FEEDBACK_COLLECTION_MAX_REPORTS = 500
117
+ _FEEDBACK_COLLECTION_MAX_PROJECTS = 100
118
+ _PROJECT_CONFIG_RELATIVE = PROJECT_CONFIG_PATH
119
+ _INSTALL_TRANSACTION_RELATIVE = Path(".agents/.auto-coding-skill-install-transaction")
120
+ _EFFECTIVE_CONFIG_PATHS = {
121
+ "docs/ENGINEERING.md",
122
+ _PROJECT_CONFIG_RELATIVE.as_posix(),
123
+ }
124
+ _FEEDBACK_V1_FIELDS = (
125
+ "schema",
126
+ "report_id",
127
+ "status",
128
+ "created_at",
129
+ "project",
130
+ "observed_skill_version",
131
+ "component",
132
+ "kind",
133
+ "impact",
134
+ "origin_surface",
135
+ "suspected_scope",
136
+ "signature",
137
+ "export",
138
+ )
139
+ _FEEDBACK_V2_FIELDS = (
140
+ *_FEEDBACK_V1_FIELDS,
141
+ "updated_at",
142
+ "last_verified_skill_version",
143
+ "resolution",
144
+ )
145
+ _FEEDBACK_STATUSES = {"open", "needs-evidence", "accepted", "duplicate", "resolved", "rejected"}
146
+ _FEEDBACK_ACTIVE_STATUSES = {"open", "needs-evidence", "accepted"}
147
+ _FEEDBACK_KINDS = {"defect", "gap"}
148
+ _FEEDBACK_IMPACTS = {"blocking", "degraded", "minor"}
149
+ _FEEDBACK_ORIGIN_SURFACES = {
150
+ "managed-template",
151
+ "managed-script",
152
+ "managed-agent",
153
+ "cli",
154
+ "installer",
155
+ }
156
+ _FEEDBACK_RESOLUTIONS = {
157
+ "pending",
158
+ "fixed",
159
+ "duplicate",
160
+ "project-config",
161
+ "environment",
162
+ "not-shared",
163
+ "not-reproducible",
164
+ "wont-fix",
165
+ }
166
+ _FEEDBACK_CATALOG_DISPOSITIONS = {
167
+ "fixed",
168
+ "project-config",
169
+ "environment",
170
+ "duplicate",
171
+ "rejected",
172
+ }
173
+ _FEEDBACK_HEADINGS = (
174
+ "Symptom",
175
+ "Expected",
176
+ "Minimal reproduction",
177
+ "Evidence",
178
+ "Workaround",
179
+ "Why shared",
180
+ )
181
+ _FEEDBACK_SAFE_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
182
+ _FEEDBACK_SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
183
+ _FEEDBACK_SIGNATURE_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
184
+ _FEEDBACK_FILENAME_RE = re.compile(
185
+ r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}\.md$"
186
+ )
187
+ _FEEDBACK_SENSITIVE_PATTERNS = (
188
+ re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----", re.IGNORECASE),
189
+ re.compile(r"\bAuthorization\s*:\s*Bearer\s+\S+", re.IGNORECASE),
190
+ re.compile(r"https?://[^\s/:@]+:[^\s/@]+@", re.IGNORECASE),
191
+ re.compile(r"(?:^|[\s`])/(?:Users|home)/[^/\s]+/"),
192
+ re.compile(r"\b[A-Za-z]:\\Users\\[^\\\s]+\\", re.IGNORECASE),
193
+ )
194
+ _FEEDBACK_SEMVER_RE = re.compile(
195
+ r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
196
+ r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)"
197
+ r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?"
198
+ r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
199
+ )
81
200
  _DEEP_REVIEW_CATEGORIES = {
82
201
  "api",
83
202
  "auth",
@@ -168,7 +287,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
168
287
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
169
288
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
170
289
  "schema_version": 1,
171
- "managed_versions": {"agents": "4.2.8", "engineering": "4.2.8"},
290
+ "managed_versions": {"agents": "4.3.1", "engineering": "4.3.1"},
172
291
  "known_official_engineering_body_sha256": [
173
292
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
174
293
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -263,7 +382,7 @@ def _join_url(base: str, path: str) -> str:
263
382
  base = str(base or "").strip().rstrip("/")
264
383
  path = str(path or "").strip()
265
384
  if not base or not path:
266
- raise APError("Health URL config incomplete. Fill base url and path in docs/ENGINEERING.md.")
385
+ raise APError("Health URL config incomplete. Fill the project configuration overlay.")
267
386
  if not path.startswith("/"):
268
387
  path = "/" + path
269
388
  return base + path
@@ -391,7 +510,7 @@ def _require_http_url(field: str, value: object) -> str:
391
510
  raw = _text(value).rstrip("/")
392
511
  parsed = urllib.parse.urlparse(raw)
393
512
  if not _is_explicit_fill(raw) or parsed.scheme not in {"http", "https"} or not parsed.netloc:
394
- raise APError(f"Missing or invalid {field}; fill an http/https URL in docs/ENGINEERING.md.")
513
+ raise APError(f"Missing or invalid {field}; fill an http/https URL in the project configuration overlay.")
395
514
  return raw
396
515
 
397
516
 
@@ -619,7 +738,7 @@ def _jenkins_api_get_json(
619
738
  f"Jenkins API request failed: {url}\n"
620
739
  f"HTTP 403\n{body or '(empty response body)'}\n"
621
740
  "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
622
- "Fill jenkins.base_url in docs/ENGINEERING.md if needed."
741
+ "Fill jenkins.base_url in the project configuration overlay if needed."
623
742
  ) from exc
624
743
  else:
625
744
  raise APError(
@@ -727,7 +846,7 @@ def _resolve_jenkins_job_url(
727
846
  return _jenkins_job_url_from_name(base_url, requested_name)
728
847
  raise APError(
729
848
  f"Cannot resolve Jenkins job URL for job '{requested_name}'. "
730
- "Pass --job-url, or fill the selected Jenkins endpoint in docs/ENGINEERING.md."
849
+ "Pass --job-url, or fill the selected Jenkins endpoint in the project configuration overlay."
731
850
  )
732
851
  if configured_url:
733
852
  return configured_url.rstrip("/")
@@ -842,559 +961,1970 @@ def _inferred_gate_commands(repo: Path) -> dict[str, str]:
842
961
  return {}
843
962
 
844
963
 
845
- def _initialize_engineering_defaults(path: Path, repo: Path) -> None:
846
- if not path.exists():
847
- return
848
- text = path.read_text(encoding="utf-8")
849
- updated = text.replace(
850
- 'project:\n name: ""',
851
- f"project:\n name: {json.dumps(repo.name, ensure_ascii=False)}",
852
- 1,
853
- )
854
- for key, gate_command in _inferred_gate_commands(repo).items():
855
- for default_value in ['""', '"git diff --check"']:
856
- candidate = updated.replace(
857
- f" {key}: {default_value}",
858
- f" {key}: {json.dumps(gate_command)}",
859
- 1,
860
- )
861
- if candidate != updated:
862
- updated = candidate
863
- break
864
- if updated != text:
865
- path.write_text(updated, encoding="utf-8")
866
-
867
-
868
964
  def _mapping(value: object) -> dict:
869
965
  return value if isinstance(value, dict) else {}
870
966
 
871
967
 
872
- def _string_list(value: object) -> list[str]:
873
- if not isinstance(value, list):
874
- return []
875
- return [item.strip() for item in value if isinstance(item, str) and item.strip()]
876
-
968
+ _NO_CONFIG_DIFF = object()
877
969
 
878
- def _copy_scalar_path(source: dict, target: dict, path: tuple[str, ...]) -> None:
879
- current: object = source
880
- for key in path:
881
- if not isinstance(current, dict) or key not in current:
882
- return
883
- current = current[key]
884
- destination = target
885
- for key in path[:-1]:
886
- destination = destination[key]
887
- expected = destination[path[-1]]
888
- compatible = (
889
- (isinstance(expected, bool) and isinstance(current, bool))
890
- or (isinstance(expected, str) and isinstance(current, str))
891
- or (
892
- isinstance(expected, (int, float))
893
- and not isinstance(expected, bool)
894
- and isinstance(current, (int, float))
895
- and not isinstance(current, bool)
896
- )
897
- )
898
- if compatible:
899
- destination[path[-1]] = current
900
-
901
-
902
- def _normalize_validation_routes(value: object) -> list[dict]:
903
- routes: list[dict] = []
904
- if not isinstance(value, list):
905
- return routes
906
- for raw in value:
907
- if not isinstance(raw, dict):
908
- continue
909
- route: dict = {}
910
- name = _text(raw.get("name"))
911
- paths = _string_list(raw.get("paths"))
912
- commands = [_command_name(item) for item in _string_list(raw.get("commands"))]
913
- commands = [item for item in commands if item]
914
- if name:
915
- route["name"] = name
916
- if paths:
917
- route["paths"] = paths
918
- exclude = _string_list(raw.get("exclude"))
919
- if exclude:
920
- route["exclude"] = exclude
921
- if commands:
922
- route["commands"] = commands
923
- timeout = raw.get("timeout_seconds")
924
- if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) and timeout > 0:
925
- route["timeout_seconds"] = timeout
926
- if paths and commands:
927
- routes.append(route)
928
- return routes
929
-
930
-
931
- def _normalize_risk_rules(value: object) -> list[dict]:
932
- rules: list[dict] = []
933
- if not isinstance(value, list):
934
- return rules
935
- for raw in value:
936
- if not isinstance(raw, dict):
937
- continue
938
- rule: dict = {}
939
- name = _text(raw.get("name"))
940
- paths = _string_list(raw.get("paths"))
941
- if name:
942
- rule["name"] = name
943
- if paths:
944
- rule["paths"] = paths
945
- profile = _text(raw.get("profile")).lower()
946
- if profile in _WORKFLOW_PROFILES - {"auto"}:
947
- rule["profile"] = profile
948
- for key in ["review", "design"]:
949
- value_text = _text(raw.get(key)).lower()
950
- if value_text in {"required", "true", "yes", "false", "no"}:
951
- rule[key] = value_text
952
- if paths:
953
- rules.append(rule)
954
- return rules
955
-
956
-
957
- def _normalize_layer_rules(value: object) -> list[dict]:
958
- rules: list[dict] = []
959
- if not isinstance(value, list):
960
- return rules
961
- for raw in value:
962
- if not isinstance(raw, dict):
963
- continue
964
- paths = _string_list(raw.get("paths"))
965
- forbidden = _string_list(raw.get("forbidden_imports"))
966
- if not paths or not forbidden:
967
- continue
968
- rule = {"paths": paths, "forbidden_imports": forbidden}
969
- name = _text(raw.get("name"))
970
- if name:
971
- rule = {"name": name, **rule}
972
- rules.append(rule)
973
- return rules
974
970
 
971
+ def _config_values_equal(left: object, right: object) -> bool:
972
+ """Compare parsed configuration without Python's bool/number coercions."""
973
+ if type(left) is not type(right):
974
+ return False
975
+ if isinstance(left, dict):
976
+ return left.keys() == right.keys() and all(
977
+ _config_values_equal(left[key], right[key]) for key in left
978
+ )
979
+ if isinstance(left, list):
980
+ return len(left) == len(right) and all(
981
+ _config_values_equal(left_item, right_item)
982
+ for left_item, right_item in zip(left, right)
983
+ )
984
+ return left == right
975
985
 
976
- def _converged_engineering_document(repo: Path, template_path: Path) -> str:
977
- template_cfg, template_body = _read_frontmatter_markdown(template_path)
978
- engineering = repo / "docs" / "ENGINEERING.md"
979
- current_cfg: dict = {}
980
- if engineering.exists():
981
- try:
982
- current_cfg, _ = _read_frontmatter_markdown(engineering)
983
- except Exception:
984
- # Initialization is an authoritative reset. Malformed legacy policy
985
- # must not prevent the current schema from taking effect.
986
- current_cfg = {}
987
-
988
- converged = json.loads(json.dumps(template_cfg))
989
- preserve_scalar_paths = [
990
- ("project", "name"),
991
- ("project", "repo_root"),
992
- ("project", "stack"),
993
- ("access", "project", "frontend", "url"),
994
- ("access", "project", "frontend", "username"),
995
- ("access", "project", "frontend", "password"),
996
- ("access", "project", "backend", "url"),
997
- ("access", "project", "backend", "username"),
998
- ("access", "project", "backend", "password"),
999
- ("access", "jenkins", "frontend", "url"),
1000
- ("access", "jenkins", "frontend", "username"),
1001
- ("access", "jenkins", "frontend", "password"),
1002
- ("access", "jenkins", "backend", "url"),
1003
- ("access", "jenkins", "backend", "username"),
1004
- ("access", "jenkins", "backend", "password"),
1005
- ("access", "gitlab", "url"),
1006
- ("access", "gitlab", "username"),
1007
- ("access", "gitlab", "password"),
1008
- ("access", "nexus", "frontend", "url"),
1009
- ("access", "nexus", "frontend", "username"),
1010
- ("access", "nexus", "frontend", "password"),
1011
- ("concurrency", "base_ref"),
1012
- ("concurrency", "target_branch"),
1013
- ("concurrency", "branch_prefix"),
1014
- ("concurrency", "worktree_root"),
1015
- ("concurrency", "cleanup_merged"),
1016
- ("concurrency", "delete_remote_branch"),
1017
- ("validation", "max_command_seconds"),
1018
- ("validation", "max_total_seconds"),
1019
- ("structure", "enabled"),
1020
- ("structure", "enforcement"),
1021
- ("structure", "architecture_standard"),
1022
- ("structure", "layer_rules", "enabled"),
1023
- ("structure", "layer_rules", "block"),
1024
- ("optimization", "completion_policy"),
1025
- ("optimization", "require_baseline_for_global_review"),
1026
- ("optimization", "report_accepted_debt_as_findings"),
1027
- ("docs", "api_docs_required"),
1028
- ]
1029
- for field_path in preserve_scalar_paths:
1030
- _copy_scalar_path(current_cfg, converged, field_path)
1031
-
1032
- current_concurrency = _mapping(current_cfg.get("concurrency"))
1033
- isolation = _text(current_concurrency.get("isolation")).lower()
1034
- if isolation in {"adaptive", "worktree"}:
1035
- converged["concurrency"]["isolation"] = isolation
1036
- converged["concurrency"]["disposable_ignored"] = _string_list(
1037
- current_concurrency.get("disposable_ignored")
1038
- )
1039
-
1040
- current_commands = _mapping(current_cfg.get("commands"))
1041
- current_validation = _mapping(current_cfg.get("validation"))
1042
- routes = _normalize_validation_routes(current_validation.get("routes"))
1043
- referenced_commands = {
1044
- command
1045
- for route in routes
1046
- for command in _string_list(route.get("commands"))
1047
- }
1048
- referenced_commands.add("project_fast")
1049
- commands = {
1050
- str(name): value.strip()
1051
- for name, value in current_commands.items()
1052
- if name in referenced_commands and isinstance(name, str) and isinstance(value, str) and value.strip()
1053
- }
1054
- inferred = _inferred_gate_commands(repo)
1055
- if not commands.get("project_fast") and inferred.get("project_fast"):
1056
- commands["project_fast"] = inferred["project_fast"]
1057
- converged["commands"].update(commands)
1058
-
1059
- converged["validation"]["routes"] = routes
1060
- converged["risk"]["rules"] = _normalize_risk_rules(
1061
- _mapping(current_cfg.get("risk")).get("rules")
1062
- )
1063
- current_structure = _mapping(current_cfg.get("structure"))
1064
- for key in ("exclude", "allow_large_files", "reusable_tool_dirs"):
1065
- if isinstance(current_structure.get(key), list):
1066
- converged["structure"][key] = _string_list(current_structure.get(key))
1067
- for key in (
1068
- "max_file_lines_warn",
1069
- "max_file_lines_block",
1070
- "max_function_lines_warn",
1071
- "max_added_lines_to_large_file",
1072
- ):
1073
- value = current_structure.get(key)
1074
- if isinstance(value, int) and not isinstance(value, bool):
1075
- converged["structure"][key] = value
1076
- for key in (
1077
- "require_reuse_search",
1078
- "block_new_responsibility_in_large_file",
1079
- "block_warnings",
1080
- ):
1081
- value = current_structure.get(key)
1082
- if isinstance(value, bool):
1083
- converged["structure"][key] = value
1084
- converged["structure"]["accepted_debt_paths"] = _string_list(
1085
- current_structure.get("accepted_debt_paths")
1086
- )
1087
- current_layers = _mapping(current_structure.get("layer_rules"))
1088
- converged["structure"]["layer_rules"]["rules"] = _normalize_layer_rules(
1089
- current_layers.get("rules")
1090
- )
1091
-
1092
- if not _text(_mapping(converged.get("project")).get("name")):
1093
- converged["project"]["name"] = repo.name
1094
- dumped = require_yaml().safe_dump(converged, allow_unicode=True, sort_keys=False).strip()
1095
- return f"---\n{dumped}\n---\n{template_body.lstrip()}"
1096
-
1097
-
1098
- _PROJECT_ARTIFACT_PATTERNS = (
1099
- "docs/architecture/*.md",
1100
- "docs/architecture/adr/*.md",
1101
- "docs/deployment/deploy-records/*.md",
1102
- "docs/design/*.md",
1103
- "docs/interfaces/*.md",
1104
- "docs/reviews/*.md",
1105
- )
1106
986
 
987
+ def _config_semantic_diff(current: object, base: object, path: tuple[str, ...] = ()) -> object:
988
+ """Return only project-owned values, excluding the managed release identity."""
989
+ if path == ("workflow", "skill_version"):
990
+ return _NO_CONFIG_DIFF
991
+ if isinstance(current, dict) and isinstance(base, dict):
992
+ result: dict = {}
993
+ for key, value in current.items():
994
+ field_path = (*path, str(key))
995
+ if key not in base:
996
+ if field_path != ("workflow", "skill_version"):
997
+ result[key] = json.loads(json.dumps(value))
998
+ continue
999
+ difference = _config_semantic_diff(value, base[key], field_path)
1000
+ if difference is not _NO_CONFIG_DIFF:
1001
+ result[key] = difference
1002
+ return result if result else _NO_CONFIG_DIFF
1003
+ if not _config_values_equal(current, base):
1004
+ return json.loads(json.dumps(current))
1005
+ return _NO_CONFIG_DIFF
1006
+
1007
+
1008
+ def _config_difference_conflicts(
1009
+ difference: object,
1010
+ current: object,
1011
+ effective: object,
1012
+ path: tuple[str, ...] = (),
1013
+ ) -> list[str]:
1014
+ """Find legacy project values not preserved exactly by an existing overlay."""
1015
+ if difference is _NO_CONFIG_DIFF:
1016
+ return []
1017
+ if isinstance(difference, dict):
1018
+ if not isinstance(current, dict) or not isinstance(effective, dict):
1019
+ return [".".join(path) or "(root)"]
1020
+ conflicts: list[str] = []
1021
+ for key, value in difference.items():
1022
+ field_path = (*path, str(key))
1023
+ if key not in current or key not in effective:
1024
+ conflicts.append(".".join(field_path))
1025
+ continue
1026
+ conflicts.extend(
1027
+ _config_difference_conflicts(
1028
+ value,
1029
+ current[key],
1030
+ effective[key],
1031
+ field_path,
1032
+ )
1033
+ )
1034
+ return conflicts
1035
+ return [] if _config_values_equal(current, effective) else [".".join(path) or "(root)"]
1107
1036
 
1108
- def _is_allowed_project_doc(rel: Path) -> bool:
1109
- return any(rel.match(pattern) for pattern in _PROJECT_ARTIFACT_PATTERNS)
1110
1037
 
1038
+ _INSTALLED_ENGINEERING_TEMPLATE = Path(
1039
+ ".agents/skills/auto-coding-skill/data/templates/ENGINEERING.md"
1040
+ )
1041
+ _INSTALLED_MANIFEST = Path(".agents/managed-install.json")
1111
1042
 
1112
- def cmd_project_converge(args: argparse.Namespace) -> None:
1113
- repo = Path(args.repo).resolve()
1114
- template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
1115
- engineering = repo / "docs" / "ENGINEERING.md"
1116
- output = _converged_engineering_document(repo, template)
1117
- current = engineering.read_text(encoding="utf-8") if engineering.exists() else ""
1118
- changed = not bool(current)
1119
- if current:
1120
- try:
1121
- current_cfg, current_body = _parse_frontmatter_markdown_text(current, engineering)
1122
- output_cfg, output_body = _parse_frontmatter_markdown_text(output, engineering)
1123
- changed = current_cfg != output_cfg or current_body != output_body
1124
- except Exception:
1125
- changed = True
1126
- actions: list[dict] = []
1127
- version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
1128
1043
 
1129
- def archive_previous(source_path: Path, content: str, label: str) -> None:
1130
- archive_root = repo / ".agents" / "archive" / "auto-coding-skill" / version
1131
- archive = archive_root / source_path.relative_to(repo)
1132
- if archive.exists() and archive.read_text(encoding="utf-8") != content:
1133
- digest = hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
1134
- archive = archive.with_name(f"{archive.stem}-{digest}{archive.suffix}")
1135
- if archive.exists():
1136
- return
1137
- actions.append({"action": "archive", "path": _repo_rel(repo, archive), "detail": label})
1138
- if args.write:
1139
- archive.parent.mkdir(parents=True, exist_ok=True)
1140
- archive.write_text(content, encoding="utf-8")
1044
+ def _installed_template_config(repo: Path) -> dict | None:
1045
+ relative = _INSTALLED_ENGINEERING_TEMPLATE
1046
+ payload = _safe_read_project_file(repo, relative, max_bytes=1024 * 1024)
1047
+ if payload is None:
1048
+ return None
1049
+ manifest_payload = _safe_read_project_file(repo, _INSTALLED_MANIFEST, max_bytes=4 * 1024 * 1024)
1050
+ if manifest_payload is None:
1051
+ raise APError(
1052
+ "Cannot trust the installed default template without .agents/managed-install.json; "
1053
+ "no files were written."
1054
+ )
1141
1055
 
1142
- def archive_extra(source_path: Path, label: str) -> None:
1143
- content = source_path.read_bytes()
1144
- archive_root = repo / ".agents" / "archive" / "auto-coding-skill" / version
1145
- archive = archive_root / source_path.relative_to(repo)
1146
- if archive.exists() and archive.read_bytes() != content:
1147
- digest = hashlib.sha256(content).hexdigest()[:12]
1148
- archive = archive.with_name(f"{archive.stem}-{digest}{archive.suffix}")
1149
- if not archive.exists():
1150
- actions.append({"action": "archive", "path": _repo_rel(repo, archive), "detail": label})
1151
- if args.write:
1152
- archive.parent.mkdir(parents=True, exist_ok=True)
1153
- archive.write_bytes(content)
1056
+ def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
1057
+ result: dict = {}
1058
+ for key, value in pairs:
1059
+ if not isinstance(key, str) or key in result:
1060
+ raise ValueError("invalid manifest mapping")
1061
+ result[key] = value
1062
+ return result
1154
1063
 
1155
- if changed and current:
1156
- archive_header = (
1157
- f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
1158
- "Historical and non-authoritative. Do not use this file as workflow policy.\n\n---\n\n"
1064
+ try:
1065
+ manifest = json.loads(
1066
+ manifest_payload.decode("utf-8"),
1067
+ object_pairs_hook=reject_duplicate_keys,
1159
1068
  )
1160
- archive_previous(engineering, archive_header + current, "previous project configuration")
1161
- if changed:
1162
- actions.append({
1163
- "action": "create" if not current else "replace",
1164
- "path": "docs/ENGINEERING.md",
1165
- })
1166
- if args.write:
1167
- engineering.parent.mkdir(parents=True, exist_ok=True)
1168
- engineering.write_text(output, encoding="utf-8")
1069
+ except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
1070
+ raise APError("Installed managed manifest is invalid; no files were written.") from exc
1071
+ if (
1072
+ not isinstance(manifest, dict)
1073
+ or manifest.get("schema_version") != 1
1074
+ or manifest.get("manifest_path") != _INSTALLED_MANIFEST.as_posix()
1075
+ or not isinstance(manifest.get("entries"), list)
1076
+ ):
1077
+ raise APError("Installed managed manifest is invalid; no files were written.")
1078
+ if len(manifest["entries"]) > 10000:
1079
+ raise APError("Installed managed manifest has too many entries; no files were written.")
1080
+ matches = [
1081
+ entry
1082
+ for entry in manifest["entries"]
1083
+ if isinstance(entry, dict) and entry.get("path") == relative.as_posix()
1084
+ ]
1085
+ manifest_version = _text(manifest.get("skill_version"))
1086
+ if not re.fullmatch(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", manifest_version):
1087
+ raise APError("Installed managed manifest has an invalid Skill version; no files were written.")
1088
+ if len(matches) != 1:
1089
+ raise APError("Installed default template is not bound by the managed manifest; no files were written.")
1090
+ entry = matches[0]
1091
+ expected_hash = _text(entry.get("sha256"))
1092
+ if (
1093
+ entry.get("ownership") != "exact"
1094
+ or entry.get("source") != "skill/data/templates/ENGINEERING.md"
1095
+ or entry.get("version") != manifest_version
1096
+ or not re.fullmatch(r"[0-9a-f]{64}", expected_hash)
1097
+ or hashlib.sha256(payload).hexdigest() != expected_hash
1098
+ ):
1099
+ raise APError("Installed default template failed its managed manifest identity check; no files were written.")
1100
+ config = parse_managed_config_payload(payload)
1101
+ config_version = _text(_mapping(config.get("workflow")).get("skill_version"))
1102
+ if config_version != manifest_version:
1103
+ raise APError("Installed default template version is not bound to its manifest; no files were written.")
1104
+ return config
1105
+
1106
+
1107
+ def _render_project_overlay(overrides: dict) -> bytes:
1108
+ document = {"schema": PROJECT_CONFIG_SCHEMA, "overrides": overrides}
1109
+ dumped = require_yaml().safe_dump(document, allow_unicode=True, sort_keys=False)
1110
+ payload = dumped.encode("utf-8")
1111
+ # The installer must never create an overlay that its own runtime rejects.
1112
+ parse_project_overrides_payload(payload)
1113
+ return payload
1169
1114
 
1170
- for rel, canonical in sorted(templates_for("all").items()):
1171
- target = repo / rel
1172
- existing = target.read_text(encoding="utf-8") if target.exists() else ""
1173
- managed = rel in MANAGED_FRAMEWORK_DOCS
1174
- if existing and (not managed or existing == canonical):
1175
- continue
1176
- if existing:
1177
- archive_previous(target, existing, "previous managed documentation template")
1178
- actions.append({"action": "create" if not existing else "replace", "path": rel})
1179
- if args.write:
1180
- target.parent.mkdir(parents=True, exist_ok=True)
1181
- target.write_text(canonical, encoding="utf-8")
1182
1115
 
1183
- allowed_docs = {
1116
+ def _project_config_convergence_plan(repo: Path, template: Path) -> dict:
1117
+ template_payload = template.read_bytes()
1118
+ template_cfg = parse_managed_config_payload(template_payload)
1119
+ try:
1120
+ template_text = template_payload.decode("utf-8")
1121
+ except UnicodeDecodeError as exc:
1122
+ raise APError("Managed Skill template must be UTF-8.") from exc
1123
+ current_payload = _safe_read_project_file(
1124
+ repo,
1184
1125
  Path("docs/ENGINEERING.md"),
1185
- Path("docs/tools/autopipeline/ap.py"),
1186
- *(Path(rel) for rel in templates_for("all")),
1187
- }
1188
- docs_root = repo / "docs"
1189
- if docs_root.exists():
1190
- for candidate in sorted(docs_root.rglob("*")):
1191
- if not candidate.is_file() and not candidate.is_symlink():
1192
- continue
1193
- rel = candidate.relative_to(repo)
1194
- if rel in allowed_docs or _is_allowed_project_doc(rel):
1195
- continue
1196
- archive_extra(candidate, "removed from the exact docs framework")
1197
- actions.append({"action": "delete", "path": rel.as_posix()})
1198
- if args.write:
1199
- candidate.unlink()
1200
- if args.write:
1201
- for directory in sorted(
1202
- (item for item in docs_root.rglob("*") if item.is_dir()),
1203
- key=lambda item: len(item.parts),
1204
- reverse=True,
1126
+ max_bytes=1024 * 1024,
1127
+ )
1128
+ current_cfg: dict | None = None
1129
+ current_text = ""
1130
+ if current_payload is not None:
1131
+ try:
1132
+ current_text = current_payload.decode("utf-8")
1133
+ except UnicodeDecodeError as exc:
1134
+ raise APError("Managed project configuration must be UTF-8.") from exc
1135
+ current_cfg = parse_managed_config_payload(current_payload)
1136
+
1137
+ # Always validate an existing overlay before any installer write. Its bytes
1138
+ # are project-owned and are never normalized by ordinary convergence.
1139
+ overlay_payload = _safe_read_project_file(
1140
+ repo,
1141
+ _PROJECT_CONFIG_RELATIVE,
1142
+ max_bytes=128 * 1024,
1143
+ )
1144
+ overrides = (
1145
+ parse_project_overrides_payload(overlay_payload)
1146
+ if overlay_payload is not None
1147
+ else {}
1148
+ )
1149
+ old_base = None
1150
+ if current_cfg is not None:
1151
+ # A completed target document is self-identical to the trusted source
1152
+ # template, so retry does not depend on the previous install manifest.
1153
+ # Legacy/custom documents still require a manifest-bound old base.
1154
+ old_base = (
1155
+ template_cfg
1156
+ if current_payload == template_payload
1157
+ else _installed_template_config(repo)
1158
+ )
1159
+ overlay_output: bytes | None = None
1160
+ migrated_paths: list[str] = []
1161
+
1162
+ if overlay_payload is None:
1163
+ if current_cfg is not None and old_base is None:
1164
+ current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
1165
+ template_version = _text(_mapping(template_cfg.get("workflow")).get("skill_version"))
1166
+ if current_version != template_version:
1167
+ raise APError(
1168
+ "Cannot migrate project configuration without its installed default template; "
1169
+ "no files were written. Restore the current .agents Skill copy or create the "
1170
+ "project overlay explicitly."
1171
+ )
1172
+ old_base = template_cfg
1173
+ difference = (
1174
+ _config_semantic_diff(current_cfg, old_base or template_cfg)
1175
+ if current_cfg is not None
1176
+ else _NO_CONFIG_DIFF
1177
+ )
1178
+ overrides = difference if isinstance(difference, dict) else {}
1179
+ if current_cfg is not None:
1180
+ semantic_base = old_base or template_cfg
1181
+ current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
1182
+ base_version = _text(_mapping(semantic_base.get("workflow")).get("skill_version"))
1183
+ if current_version != base_version:
1184
+ raise APError(
1185
+ "Installed default template version does not match docs/ENGINEERING.md; "
1186
+ "no files were written."
1187
+ )
1188
+ if not _config_values_equal(
1189
+ merge_project_config(semantic_base, overrides),
1190
+ current_cfg,
1205
1191
  ):
1206
- try:
1207
- directory.rmdir()
1208
- except OSError:
1209
- pass
1192
+ raise APError(
1193
+ "Project configuration migration could not prove semantic equivalence; "
1194
+ "no files were written."
1195
+ )
1196
+ project_cfg = overrides.setdefault("project", {})
1197
+ if not isinstance(project_cfg, dict):
1198
+ raise APError("Legacy project.project must be a mapping before configuration migration.")
1199
+ if not _text(project_cfg.get("name")):
1200
+ project_cfg["name"] = repo.name
1201
+ if current_cfg is None:
1202
+ inferred = _inferred_gate_commands(repo)
1203
+ if inferred:
1204
+ overrides.setdefault("commands", {}).update(inferred)
1205
+ # Validate protected fields and merge behavior before writing the new file.
1206
+ merge_project_config(template_cfg, overrides)
1207
+ overlay_output = _render_project_overlay(overrides)
1208
+ migrated_paths = sorted(_flatten_config_paths(overrides))
1209
+ elif current_cfg is not None:
1210
+ if old_base is None:
1211
+ raise APError(
1212
+ "Cannot verify an existing project overlay without the installed default template; "
1213
+ "no files were written."
1214
+ )
1215
+ current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
1216
+ base_version = _text(_mapping(old_base.get("workflow")).get("skill_version"))
1217
+ if current_version != base_version:
1218
+ raise APError(
1219
+ "Installed default template version does not match docs/ENGINEERING.md; "
1220
+ "no files were written."
1221
+ )
1222
+ legacy_difference = _config_semantic_diff(current_cfg, old_base)
1223
+ legacy_overrides = legacy_difference if isinstance(legacy_difference, dict) else {}
1224
+ if not _config_values_equal(
1225
+ merge_project_config(old_base, legacy_overrides),
1226
+ current_cfg,
1227
+ ):
1228
+ raise APError(
1229
+ "Legacy project configuration cannot be represented as additive overrides; "
1230
+ "no files were written. Restore the deleted default field or create an explicit "
1231
+ "project overlay after reconciling the intended value."
1232
+ )
1233
+ legacy_effective = merge_project_config(old_base, overrides)
1234
+ conflicts = _config_difference_conflicts(
1235
+ legacy_difference,
1236
+ current_cfg,
1237
+ legacy_effective,
1238
+ )
1239
+ if conflicts:
1240
+ raise APError(
1241
+ "Existing project overlay conflicts with legacy project configuration; "
1242
+ "no files were written. Preserve these paths exactly in "
1243
+ "docs/project/auto-coding-skill.yaml: "
1244
+ + ", ".join(sorted(conflicts))
1245
+ )
1246
+ merge_project_config(template_cfg, overrides)
1210
1247
 
1211
- result = {"changed": bool(actions), "mode": "write" if args.write else "plan", "actions": actions}
1212
- if args.json:
1213
- print(json.dumps(result, ensure_ascii=False, indent=2))
1214
- return
1215
- for action in actions:
1216
- print(f"[project-converge] {action['action']}: {action['path']}")
1217
- if not actions:
1218
- print("[project-converge] OK: already current")
1248
+ return {
1249
+ "engineering_output": template_text,
1250
+ "engineering_current": current_text,
1251
+ "overlay_current": overlay_payload,
1252
+ "overlay_output": overlay_output,
1253
+ "migrated_paths": migrated_paths,
1254
+ }
1219
1255
 
1220
1256
 
1221
- def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
1222
- changed: list[str] = []
1223
-
1224
- workflow_cfg = cfg.setdefault("workflow", {})
1225
- if not isinstance(workflow_cfg, dict):
1226
- workflow_cfg = {}
1227
- cfg["workflow"] = workflow_cfg
1228
- if _text(workflow_cfg.get("mode")).lower() != "dev":
1229
- workflow_cfg["mode"] = "dev"
1230
- changed.append("workflow.mode")
1231
- if _text(workflow_cfg.get("completion")).lower() != "push":
1232
- workflow_cfg["completion"] = "push"
1233
- changed.append("workflow.completion")
1234
- if _text(workflow_cfg.get("skill_version")) != "4.2.8":
1235
- workflow_cfg["skill_version"] = "4.2.8"
1236
- changed.append("workflow.skill_version")
1237
-
1238
- commands_cfg = cfg.setdefault("commands", {})
1239
- if not isinstance(commands_cfg, dict):
1240
- commands_cfg = {}
1241
- cfg["commands"] = commands_cfg
1242
- current_changed_gate = _text(commands_cfg.get("gate_changed"))
1243
- project_fast = _text(commands_cfg.get("project_fast"))
1244
- inferred_fast = _inferred_gate_commands(repo).get("project_fast", "")
1245
- if not project_fast:
1246
- replacement = (
1247
- current_changed_gate
1248
- if current_changed_gate and current_changed_gate not in {"git diff --check", "npm test"}
1249
- else inferred_fast
1250
- )
1251
- commands_cfg["project_fast"] = replacement
1252
- changed.append("commands.project_fast")
1253
-
1254
- gate_cfg = cfg.setdefault("gate", {})
1255
- if not isinstance(gate_cfg, dict):
1256
- gate_cfg = {}
1257
- cfg["gate"] = gate_cfg
1258
- for key in ["default_scope", "fallback_scope", "no_change_scope"]:
1259
- if _text(gate_cfg.get(key)).lower() != "changed":
1260
- gate_cfg[key] = "changed"
1261
- changed.append(f"gate.{key}")
1262
- if _bool_config(gate_cfg.get("full_on_unknown"), False):
1263
- gate_cfg["full_on_unknown"] = False
1264
- changed.append("gate.full_on_unknown")
1265
- if "full_on" in gate_cfg:
1266
- del gate_cfg["full_on"]
1267
- changed.append("gate.full_on")
1268
- raw_rules = gate_cfg.get("rules")
1269
- risk_cfg = cfg.setdefault("risk", {})
1270
- if not isinstance(risk_cfg, dict):
1271
- risk_cfg = {}
1272
- cfg["risk"] = risk_cfg
1273
- risk_rules = risk_cfg.setdefault("rules", [])
1274
- if not isinstance(risk_rules, list):
1275
- risk_rules = []
1276
- risk_cfg["rules"] = risk_rules
1277
- validation_cfg = cfg.setdefault("validation", {})
1278
- if not isinstance(validation_cfg, dict):
1279
- validation_cfg = {}
1280
- cfg["validation"] = validation_cfg
1281
- if _text(validation_cfg.get("on_unmapped")).lower() != "error":
1282
- validation_cfg["on_unmapped"] = "error"
1283
- changed.append("validation.on_unmapped")
1284
- for key, default_value in [
1285
- ("max_command_seconds", int(_RECOMMENDED_FINAL_COMMAND_SECONDS)),
1286
- ("max_total_seconds", int(_RECOMMENDED_FINAL_TOTAL_SECONDS)),
1287
- ]:
1288
- if key not in validation_cfg:
1289
- validation_cfg[key] = default_value
1290
- changed.append(f"validation.{key}")
1291
- validation_routes = validation_cfg.setdefault("routes", [])
1292
- if not isinstance(validation_routes, list):
1293
- validation_routes = []
1294
- validation_cfg["routes"] = validation_routes
1295
- if isinstance(raw_rules, list):
1296
- migrated_rules: list = []
1297
- for index, rule in enumerate(raw_rules):
1298
- if not isinstance(rule, dict):
1299
- migrated_rules.append(rule)
1300
- continue
1301
- migrated_rule = {
1302
- key: value
1303
- for key, value in rule.items()
1304
- if key in {"name", "paths", "profile", "review", "design"}
1305
- }
1306
- if migrated_rule and migrated_rule not in risk_rules:
1307
- risk_rules.append(migrated_rule)
1308
- changed.append(f"risk.rules[{len(risk_rules) - 1}]")
1309
- legacy_commands = _as_list(rule.get("commands"))
1310
- if legacy_commands and _as_list(rule.get("paths")):
1311
- route = {
1312
- "name": _text(rule.get("name")) or f"migrated-{index + 1}",
1313
- "paths": _as_list(rule.get("paths")),
1314
- "commands": [_command_name(item) for item in legacy_commands if _command_name(item)],
1315
- }
1316
- if route["commands"] and route not in validation_routes:
1317
- validation_routes.append(route)
1318
- changed.append(f"validation.routes[{len(validation_routes) - 1}]")
1319
- if migrated_rules != raw_rules:
1320
- gate_cfg["rules"] = []
1321
- changed.append("gate.rules")
1257
+ def _flatten_config_paths(value: object, prefix: tuple[str, ...] = ()) -> list[str]:
1258
+ if not isinstance(value, dict) or not value:
1259
+ return [".".join(prefix)] if prefix else []
1260
+ result: list[str] = []
1261
+ for key, nested in value.items():
1262
+ result.extend(_flatten_config_paths(nested, (*prefix, str(key))))
1263
+ return result
1322
1264
 
1323
- concurrency_cfg = cfg.setdefault("concurrency", {})
1324
- if not isinstance(concurrency_cfg, dict):
1325
- concurrency_cfg = {}
1326
- cfg["concurrency"] = concurrency_cfg
1327
- if _text(concurrency_cfg.get("isolation")).lower() != "adaptive":
1328
- concurrency_cfg["isolation"] = "adaptive"
1329
- changed.append("concurrency.isolation")
1330
1265
 
1331
- return changed
1266
+ def _sha256_payload(payload: bytes) -> str:
1267
+ return hashlib.sha256(payload).hexdigest()
1332
1268
 
1333
1269
 
1334
- def cmd_scaffold(args: argparse.Namespace) -> None:
1335
- repo = Path(args.repo).resolve()
1336
- group = str(args.group or "").strip().lower()
1270
+ _ARCHIVE_TARGET_ATTEMPTS = 64
1271
+
1272
+
1273
+ def _select_project_archive_target(
1274
+ repo: Path,
1275
+ preferred: str | Path,
1276
+ payload: bytes,
1277
+ *,
1278
+ legacy_digest_payload: bytes | None = None,
1279
+ ) -> tuple[Path, bool]:
1280
+ """Select an archive path without ever treating different bytes as archived."""
1281
+ preferred_rel = _safe_project_relative_path(preferred)
1282
+ payload_digest = hashlib.sha256(payload).hexdigest()
1283
+ legacy_digest = hashlib.sha256(
1284
+ payload if legacy_digest_payload is None else legacy_digest_payload
1285
+ ).hexdigest()[:12]
1286
+ preferred_suffix = preferred_rel.suffix
1287
+ legacy_candidate = preferred_rel.with_name(
1288
+ f"{preferred_rel.stem}-{legacy_digest}{preferred_suffix}"
1289
+ )
1290
+ path_digest = hashlib.sha256(preferred_rel.as_posix().encode("utf-8")).hexdigest()[:12]
1291
+ compact_stem = f".autocoding-archive-{path_digest}-{payload_digest}"
1292
+
1293
+ candidates = [preferred_rel]
1337
1294
  try:
1338
- selected = templates_for(group)
1339
- except KeyError as exc:
1340
- choices = ", ".join(scaffold_groups() + ["all"])
1341
- raise APError(f"Unknown scaffold group '{group}'. Choose one of: {choices}") from exc
1295
+ if len(os.fsencode(legacy_candidate.name)) <= 240:
1296
+ candidates.append(legacy_candidate)
1297
+ except UnicodeEncodeError:
1298
+ pass
1299
+ candidates.append(preferred_rel.with_name(f"{compact_stem}{preferred_suffix}"))
1300
+ candidates.extend(
1301
+ preferred_rel.with_name(f"{compact_stem}-{attempt}{preferred_suffix}")
1302
+ for attempt in range(2, _ARCHIVE_TARGET_ATTEMPTS + 1)
1303
+ )
1304
+
1305
+ seen: set[str] = set()
1306
+ for candidate in candidates:
1307
+ key = candidate.as_posix()
1308
+ if key in seen:
1309
+ continue
1310
+ seen.add(key)
1311
+ archived = _safe_read_project_file(repo, candidate)
1312
+ if archived is None:
1313
+ return candidate, True
1314
+ if archived == payload:
1315
+ return candidate, False
1316
+ raise APError(
1317
+ "Cannot allocate a collision-free project archive target without overwriting "
1318
+ f"different content: {preferred_rel.as_posix()}"
1319
+ )
1320
+
1342
1321
 
1322
+ def cmd_project_config_prepare(args: argparse.Namespace) -> None:
1323
+ repo = Path(args.repo).resolve()
1324
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
1325
+ plan = _project_config_convergence_plan(repo, template)
1343
1326
  write = bool(args.write)
1344
- force = bool(args.force)
1327
+ current = plan["engineering_current"].encode("utf-8")
1328
+ engineering_output = plan["engineering_output"].encode("utf-8")
1329
+ overlay = plan["overlay_output"] or plan["overlay_current"]
1330
+ if overlay is None:
1331
+ raise APError("Project configuration prepare did not produce an overlay; no files were written.")
1332
+ finalize_required = bool(current and current != engineering_output)
1333
+ if finalize_required:
1334
+ template_cfg = parse_managed_config_payload(engineering_output)
1335
+ version = _text(_mapping(template_cfg.get("workflow")).get("skill_version")) or "current"
1336
+ archive_payload = (
1337
+ f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
1338
+ "Historical and non-authoritative. Project configuration was migrated to "
1339
+ "docs/project/auto-coding-skill.yaml.\n\n---\n\n"
1340
+ ).encode("utf-8") + current
1341
+ _select_project_archive_target(
1342
+ repo,
1343
+ Path(".agents/archive/auto-coding-skill") / version / "docs/ENGINEERING.md",
1344
+ archive_payload,
1345
+ legacy_digest_payload=current,
1346
+ )
1345
1347
  actions: list[dict] = []
1346
- for rel, content in sorted(selected.items()):
1347
- path = repo / rel
1348
- if path.exists() and not force:
1349
- actions.append({"path": rel, "action": "exists"})
1350
- continue
1351
- action = "write" if write else "would-write"
1352
- actions.append({"path": rel, "action": action})
1348
+ if plan["overlay_output"] is not None:
1349
+ actions.append({"action": "create", "path": _PROJECT_CONFIG_RELATIVE.as_posix()})
1353
1350
  if write:
1354
- path.parent.mkdir(parents=True, exist_ok=True)
1355
- path.write_text(content, encoding="utf-8")
1356
-
1357
- result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
1351
+ _safe_create_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay)
1352
+ if not current:
1353
+ actions.append({"action": "create", "path": "docs/ENGINEERING.md"})
1354
+ if write:
1355
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), engineering_output)
1356
+ elif finalize_required:
1357
+ actions.append({
1358
+ "action": "defer-replace",
1359
+ "path": "docs/ENGINEERING.md",
1360
+ "detail": "replace only after the effective-config runtime is installed",
1361
+ })
1362
+ result = {
1363
+ "mode": "write" if write else "plan",
1364
+ "actions": actions,
1365
+ "finalize_required": finalize_required,
1366
+ "engineering_before_sha256": _sha256_payload(current),
1367
+ "overlay_sha256": _sha256_payload(overlay),
1368
+ "template_sha256": _sha256_payload(engineering_output),
1369
+ }
1358
1370
  if args.json:
1359
1371
  print(json.dumps(result, ensure_ascii=False, indent=2))
1360
1372
  return
1361
1373
  for item in actions:
1362
- print(f"[scaffold] {item['action']}: {item['path']}")
1363
- if not write:
1364
- print("[scaffold] plan only; re-run with --write to create missing files")
1374
+ print(f"[project-config-prepare] {item['action']}: {item['path']}")
1365
1375
 
1366
1376
 
1367
- def cmd_install(args: argparse.Namespace) -> None:
1377
+ def cmd_project_config_finalize(args: argparse.Namespace) -> None:
1368
1378
  repo = Path(args.repo).resolve()
1369
- templates = _skill_root() / "data" / "templates"
1379
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
1380
+ template_payload = template.read_bytes()
1381
+ current = _safe_read_project_file(repo, Path("docs/ENGINEERING.md"), max_bytes=1024 * 1024)
1382
+ overlay = _safe_read_project_file(repo, _PROJECT_CONFIG_RELATIVE, max_bytes=128 * 1024)
1383
+ expected = {
1384
+ "engineering": _text(args.engineering_sha256),
1385
+ "overlay": _text(args.overlay_sha256),
1386
+ "template": _text(args.template_sha256),
1387
+ }
1388
+ if any(not re.fullmatch(r"[0-9a-f]{64}", value) for value in expected.values()):
1389
+ raise APError("Project configuration finalize requires valid SHA-256 bindings.")
1390
+ if current is None or overlay is None:
1391
+ raise APError("Prepared project configuration inputs are missing; no files were written.")
1392
+ actual = {
1393
+ "engineering": _sha256_payload(current),
1394
+ "overlay": _sha256_payload(overlay),
1395
+ "template": _sha256_payload(template_payload),
1396
+ }
1397
+ mismatched = [name for name in expected if expected[name] != actual[name]]
1398
+ if mismatched:
1399
+ raise APError(
1400
+ "Prepared project configuration changed before finalize; no files were written: "
1401
+ + ", ".join(mismatched)
1402
+ )
1403
+ # Validate the final layers before replacing the legacy managed document.
1404
+ template_cfg = parse_managed_config_payload(template_payload)
1405
+ overrides = parse_project_overrides_payload(overlay)
1406
+ merge_project_config(template_cfg, overrides)
1407
+ version = _text(_mapping(template_cfg.get("workflow")).get("skill_version")) or "current"
1408
+ archive_payload = (
1409
+ f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
1410
+ "Historical and non-authoritative. Project configuration was migrated to "
1411
+ "docs/project/auto-coding-skill.yaml.\n\n---\n\n"
1412
+ ).encode("utf-8") + current
1413
+ archive, archive_required = _select_project_archive_target(
1414
+ repo,
1415
+ Path(".agents/archive/auto-coding-skill") / version / "docs/ENGINEERING.md",
1416
+ archive_payload,
1417
+ legacy_digest_payload=current,
1418
+ )
1419
+ actions: list[dict] = []
1420
+ if archive_required:
1421
+ actions.append({"action": "archive", "path": archive.as_posix()})
1422
+ if args.write:
1423
+ _safe_create_project_file(repo, archive, archive_payload)
1424
+ if current != template_payload:
1425
+ actions.append({"action": "replace", "path": "docs/ENGINEERING.md"})
1426
+ if args.write:
1427
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), template_payload)
1428
+ result = {"mode": "write" if args.write else "plan", "actions": actions}
1429
+ if args.json:
1430
+ print(json.dumps(result, ensure_ascii=False, indent=2))
1431
+ return
1432
+ for item in actions:
1433
+ print(f"[project-config-finalize] {item['action']}: {item['path']}")
1370
1434
 
1371
- planned_copies = [(templates / "ENGINEERING.md", repo / "docs" / "ENGINEERING.md")]
1372
- for rel in _CORE_DOC_TEMPLATES:
1373
- planned_copies.append((templates / "docs" / rel, repo / "docs" / rel))
1374
1435
 
1375
- if args.bridges:
1376
- planned_copies.append((templates / "bridges" / "AGENTS.md", repo / "AGENTS.md"))
1436
+ _PROJECT_ARTIFACT_ROOTS = tuple(Path(value) for value in PROJECT_OWNED_DOC_ROOTS)
1377
1437
 
1378
- tools_dir = repo / "docs" / "tools" / "autopipeline"
1379
- planned_copies.append((templates / "tools" / "ap.py", tools_dir / "ap.py"))
1380
1438
 
1381
- conflicts: list[Path] = []
1382
- for src, dst in planned_copies:
1383
- conflicts.extend(_copy_conflicts(src, dst))
1384
- if conflicts and not args.force:
1385
- conflict_list = "\n".join(f"- {_repo_rel(repo, path)}" for path in conflicts[:20])
1386
- extra = "" if len(conflicts) <= 20 else f"\n- ... and {len(conflicts) - 20} more"
1387
- raise APError(
1388
- "Install would overwrite existing files:\n"
1389
- f"{conflict_list}{extra}\n"
1390
- "For existing projects, run `ap.py upgrade --dry-run` then `ap.py upgrade --write`. "
1391
- "Use `install --force` only when intentionally resetting generated docs/tooling."
1392
- )
1439
+ def _safe_project_relative_path(rel: str | Path) -> Path:
1440
+ value = Path(rel)
1441
+ if value.is_absolute() or not value.parts or any(part in {"", ".", ".."} for part in value.parts):
1442
+ raise APError(f"Unsafe project-relative path: {rel}")
1443
+ return value
1444
+
1445
+
1446
+ def _is_windows_reparse_point(metadata: os.stat_result) -> bool:
1447
+ attributes = int(getattr(metadata, "st_file_attributes", 0) or 0)
1448
+ reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))
1449
+ return stat.S_ISLNK(metadata.st_mode) or bool(attributes & reparse_flag)
1393
1450
 
1394
- for src, dst in planned_copies:
1395
- copy_tree(src, dst)
1396
1451
 
1397
- _initialize_engineering_defaults(repo / "docs" / "ENGINEERING.md", repo)
1452
+ def _project_path_identity(metadata: os.stat_result) -> tuple[int, int]:
1453
+ return int(metadata.st_dev), int(metadata.st_ino)
1454
+
1455
+
1456
+ def _validate_windows_project_directories(
1457
+ relative: Path,
1458
+ directories: list[tuple[Path, tuple[int, int]]],
1459
+ ) -> None:
1460
+ for directory, identity in directories:
1461
+ metadata = directory.lstat()
1462
+ if (
1463
+ _is_windows_reparse_point(metadata)
1464
+ or not stat.S_ISDIR(metadata.st_mode)
1465
+ or _project_path_identity(metadata) != identity
1466
+ ):
1467
+ raise APError(f"Project path parent changed during its safety check: {relative}")
1468
+
1469
+
1470
+ def _windows_project_path_snapshot(
1471
+ repo: Path,
1472
+ relative: Path,
1473
+ *,
1474
+ create_parents: bool,
1475
+ ) -> tuple[Path, list[tuple[Path, tuple[int, int]]], bool]:
1476
+ repo = Path(repo)
1477
+ repo_metadata = repo.lstat()
1478
+ if _is_windows_reparse_point(repo_metadata) or not stat.S_ISDIR(repo_metadata.st_mode):
1479
+ raise APError(f"Project repository root must be a real directory: {relative}")
1480
+
1481
+ directories = [(repo, _project_path_identity(repo_metadata))]
1482
+ current = repo
1483
+ for index, part in enumerate(relative.parts[:-1]):
1484
+ current = current / part
1485
+ if not os.path.lexists(current):
1486
+ if not create_parents:
1487
+ _validate_windows_project_directories(relative, directories)
1488
+ remaining = Path(*relative.parts[index + 1 :])
1489
+ return current / remaining, directories, False
1490
+ _validate_windows_project_directories(relative, directories)
1491
+ try:
1492
+ current.mkdir()
1493
+ except FileExistsError:
1494
+ # A concurrent creator is acceptable only when the result is
1495
+ # still a real directory and all previously checked parents
1496
+ # retain their identities.
1497
+ pass
1498
+ _validate_windows_project_directories(relative, directories)
1499
+ metadata = current.lstat()
1500
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
1501
+ raise APError(f"Project path component must be a real directory: {relative}")
1502
+ directories.append((current, _project_path_identity(metadata)))
1503
+
1504
+ _validate_windows_project_directories(relative, directories)
1505
+ return current / relative.parts[-1], directories, True
1506
+
1507
+
1508
+ def _fallback_safe_project_path(
1509
+ repo: Path,
1510
+ rel: str | Path,
1511
+ *,
1512
+ create_parents: bool = False,
1513
+ ) -> Path:
1514
+ relative = _safe_project_relative_path(rel)
1515
+ try:
1516
+ target, _, _ = _windows_project_path_snapshot(
1517
+ Path(repo),
1518
+ relative,
1519
+ create_parents=create_parents,
1520
+ )
1521
+ return target
1522
+ except APError:
1523
+ raise
1524
+ except OSError as exc:
1525
+ raise APError(f"Cannot access project path safely: {relative}") from exc
1526
+
1527
+
1528
+ def _inject_project_file_parent_swap(repo: Path, relative: Path) -> None:
1529
+ if os.environ.get("AUTOCODING_TEST_MODE") != "1":
1530
+ return
1531
+ if os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_PATH") != relative.as_posix():
1532
+ return
1533
+ if relative.parent == Path("."):
1534
+ raise APError("Project file parent-swap test requires a nested project path.")
1535
+ external = Path(os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_EXTERNAL", ""))
1536
+ backup = Path(os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_BACKUP", ""))
1537
+ target = Path(repo) / relative.parent
1538
+ if (
1539
+ not external.is_absolute()
1540
+ or not backup.is_absolute()
1541
+ or not external.is_dir()
1542
+ or external.is_symlink()
1543
+ or os.path.lexists(backup)
1544
+ ):
1545
+ raise APError("Invalid project file parent-swap test fixture.")
1546
+ target.rename(backup)
1547
+ target.symlink_to(external, target_is_directory=True)
1548
+
1549
+
1550
+ @contextlib.contextmanager
1551
+ def _open_project_parent(repo: Path, rel: str | Path, *, create: bool = False):
1552
+ relative = _safe_project_relative_path(rel)
1553
+ directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
1554
+ descriptors: list[int] = []
1555
+ bindings: list[tuple[int, str, tuple[int, int]]] = []
1556
+ root_identity: tuple[int, int] | None = None
1557
+
1558
+ def validate_bindings() -> None:
1559
+ assert root_identity is not None
1560
+ root_metadata = Path(repo).lstat()
1561
+ if (
1562
+ _is_windows_reparse_point(root_metadata)
1563
+ or not stat.S_ISDIR(root_metadata.st_mode)
1564
+ or _project_path_identity(root_metadata) != root_identity
1565
+ ):
1566
+ raise APError(f"Project repository root changed during its safety check: {relative}")
1567
+ for parent_fd, name, identity in bindings:
1568
+ metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
1569
+ if (
1570
+ stat.S_ISLNK(metadata.st_mode)
1571
+ or not stat.S_ISDIR(metadata.st_mode)
1572
+ or _project_path_identity(metadata) != identity
1573
+ ):
1574
+ raise APError(f"Project path parent changed during its safety check: {relative}")
1575
+
1576
+ try:
1577
+ current = os.open(repo, directory_flags)
1578
+ descriptors.append(current)
1579
+ root_metadata = os.fstat(current)
1580
+ if not stat.S_ISDIR(root_metadata.st_mode):
1581
+ raise APError(f"Project repository root must be a real directory: {relative}")
1582
+ root_identity = _project_path_identity(root_metadata)
1583
+ missing = False
1584
+ for part in relative.parts[:-1]:
1585
+ try:
1586
+ metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
1587
+ except FileNotFoundError:
1588
+ if not create:
1589
+ missing = True
1590
+ break
1591
+ os.mkdir(part, 0o755, dir_fd=current)
1592
+ metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
1593
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
1594
+ raise APError(f"Project path component must be a real directory: {relative}")
1595
+ next_descriptor = os.open(part, directory_flags, dir_fd=current)
1596
+ opened = os.fstat(next_descriptor)
1597
+ identity = _project_path_identity(opened)
1598
+ if not stat.S_ISDIR(opened.st_mode) or identity != _project_path_identity(metadata):
1599
+ os.close(next_descriptor)
1600
+ raise APError(f"Project path parent changed during its safety check: {relative}")
1601
+ bindings.append((current, part, identity))
1602
+ descriptors.append(next_descriptor)
1603
+ current = next_descriptor
1604
+ _inject_project_file_parent_swap(Path(repo), relative)
1605
+ validate_bindings()
1606
+ yield (None if missing else current), relative.parts[-1]
1607
+ validate_bindings()
1608
+ except OSError as exc:
1609
+ raise APError(f"Cannot access project path safely: {relative}") from exc
1610
+ finally:
1611
+ for descriptor in reversed(descriptors):
1612
+ with contextlib.suppress(OSError):
1613
+ os.close(descriptor)
1614
+
1615
+
1616
+ def _safe_read_project_file(
1617
+ repo: Path,
1618
+ rel: str | Path,
1619
+ *,
1620
+ max_bytes: int | None = None,
1621
+ ) -> bytes | None:
1622
+ relative = _safe_project_relative_path(rel)
1623
+ if max_bytes is not None and max_bytes <= 0:
1624
+ raise APError("max_bytes must be positive")
1625
+ if os.name == "nt":
1626
+ try:
1627
+ target, directories, parents_exist = _windows_project_path_snapshot(
1628
+ Path(repo),
1629
+ relative,
1630
+ create_parents=False,
1631
+ )
1632
+ if not parents_exist or not os.path.lexists(target):
1633
+ _validate_windows_project_directories(relative, directories)
1634
+ return None
1635
+ metadata = target.lstat()
1636
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
1637
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1638
+ identity = _project_path_identity(metadata)
1639
+ if max_bytes is not None and metadata.st_size > max_bytes:
1640
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1641
+ with target.open("rb") as handle:
1642
+ opened = os.fstat(handle.fileno())
1643
+ checked = target.lstat()
1644
+ if (
1645
+ not stat.S_ISREG(opened.st_mode)
1646
+ or _project_path_identity(opened) != identity
1647
+ or _is_windows_reparse_point(checked)
1648
+ or not stat.S_ISREG(checked.st_mode)
1649
+ or _project_path_identity(checked) != identity
1650
+ ):
1651
+ raise APError(f"Project file changed during its safety check: {relative}")
1652
+ _validate_windows_project_directories(relative, directories)
1653
+ payload = handle.read() if max_bytes is None else handle.read(max_bytes + 1)
1654
+ opened_after = os.fstat(handle.fileno())
1655
+ checked_after = target.lstat()
1656
+ if (
1657
+ not stat.S_ISREG(opened_after.st_mode)
1658
+ or _project_path_identity(opened_after) != identity
1659
+ or _is_windows_reparse_point(checked_after)
1660
+ or not stat.S_ISREG(checked_after.st_mode)
1661
+ or _project_path_identity(checked_after) != identity
1662
+ ):
1663
+ raise APError(f"Project file changed while it was read: {relative}")
1664
+ _validate_windows_project_directories(relative, directories)
1665
+ if max_bytes is not None and len(payload) > max_bytes:
1666
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1667
+ return payload
1668
+ except APError:
1669
+ raise
1670
+ except OSError as exc:
1671
+ raise APError(f"Cannot read project file safely: {relative}") from exc
1672
+ with _open_project_parent(repo, relative) as (parent_fd, leaf):
1673
+ if parent_fd is None:
1674
+ return None
1675
+ descriptor = -1
1676
+ try:
1677
+ descriptor = os.open(leaf, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0), dir_fd=parent_fd)
1678
+ except FileNotFoundError:
1679
+ return None
1680
+ except OSError as exc:
1681
+ raise APError(f"Project file must be a regular non-symlink file: {relative}") from exc
1682
+ try:
1683
+ metadata = os.fstat(descriptor)
1684
+ if not stat.S_ISREG(metadata.st_mode):
1685
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1686
+ if max_bytes is not None and metadata.st_size > max_bytes:
1687
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1688
+ with os.fdopen(descriptor, "rb") as handle:
1689
+ descriptor = -1
1690
+ payload = handle.read() if max_bytes is None else handle.read(max_bytes + 1)
1691
+ if max_bytes is not None and len(payload) > max_bytes:
1692
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1693
+ return payload
1694
+ finally:
1695
+ if descriptor >= 0:
1696
+ os.close(descriptor)
1697
+
1698
+
1699
+ @contextlib.contextmanager
1700
+ def _open_project_directory(repo: Path, rel: str | Path):
1701
+ relative = _safe_project_relative_path(rel)
1702
+ if os.name == "nt":
1703
+ try:
1704
+ target, directories, complete = _windows_project_path_snapshot(
1705
+ Path(repo),
1706
+ relative,
1707
+ create_parents=False,
1708
+ )
1709
+ except OSError as exc:
1710
+ raise APError(f"Cannot access project directory safely: {relative}") from exc
1711
+ if not complete or not os.path.lexists(target):
1712
+ yield None
1713
+ return
1714
+ metadata = target.lstat()
1715
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
1716
+ raise APError(f"Project directory must be a real directory: {relative}")
1717
+ identity = _project_path_identity(metadata)
1718
+ _validate_windows_project_directories(relative, directories)
1719
+ try:
1720
+ yield target
1721
+ finally:
1722
+ try:
1723
+ checked = target.lstat()
1724
+ _validate_windows_project_directories(relative, directories)
1725
+ except OSError as exc:
1726
+ raise APError(f"Project directory changed during its safety check: {relative}") from exc
1727
+ if (
1728
+ _is_windows_reparse_point(checked)
1729
+ or not stat.S_ISDIR(checked.st_mode)
1730
+ or _project_path_identity(checked) != identity
1731
+ ):
1732
+ raise APError(f"Project directory changed during its safety check: {relative}")
1733
+ return
1734
+ with _open_project_parent(repo, relative) as (parent_fd, leaf):
1735
+ if parent_fd is None:
1736
+ yield None
1737
+ return
1738
+ descriptor = -1
1739
+ try:
1740
+ descriptor = os.open(
1741
+ leaf,
1742
+ os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
1743
+ dir_fd=parent_fd,
1744
+ )
1745
+ except FileNotFoundError:
1746
+ yield None
1747
+ return
1748
+ except OSError as exc:
1749
+ raise APError(f"Project directory must be a real directory: {relative}") from exc
1750
+ try:
1751
+ metadata = os.fstat(descriptor)
1752
+ if not stat.S_ISDIR(metadata.st_mode):
1753
+ raise APError(f"Project directory must be a real directory: {relative}")
1754
+ yield descriptor
1755
+ finally:
1756
+ if descriptor >= 0:
1757
+ os.close(descriptor)
1758
+
1759
+
1760
+ def _safe_write_project_file(repo: Path, rel: str | Path, payload: bytes) -> None:
1761
+ relative = _safe_project_relative_path(rel)
1762
+ if os.name == "nt":
1763
+ temporary: Path | None = None
1764
+ try:
1765
+ target, directories, _ = _windows_project_path_snapshot(
1766
+ Path(repo),
1767
+ relative,
1768
+ create_parents=True,
1769
+ )
1770
+ _inject_project_file_parent_swap(Path(repo), relative)
1771
+ target_identity: tuple[int, int] | None = None
1772
+ if os.path.lexists(target):
1773
+ metadata = target.lstat()
1774
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
1775
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1776
+ target_identity = _project_path_identity(metadata)
1777
+ _validate_windows_project_directories(relative, directories)
1778
+
1779
+ temporary = target.with_name(f".{target.name}.autocoding-{uuid.uuid4().hex}")
1780
+ with temporary.open("xb") as handle:
1781
+ opened = os.fstat(handle.fileno())
1782
+ checked = temporary.lstat()
1783
+ temporary_identity = _project_path_identity(opened)
1784
+ if (
1785
+ not stat.S_ISREG(opened.st_mode)
1786
+ or _is_windows_reparse_point(checked)
1787
+ or not stat.S_ISREG(checked.st_mode)
1788
+ or _project_path_identity(checked) != temporary_identity
1789
+ ):
1790
+ raise APError(f"Temporary project file is unsafe: {relative}")
1791
+ _validate_windows_project_directories(relative, directories)
1792
+ handle.write(payload)
1793
+ handle.flush()
1794
+ os.fsync(handle.fileno())
1795
+ opened_after = os.fstat(handle.fileno())
1796
+ checked_after = temporary.lstat()
1797
+ if (
1798
+ not stat.S_ISREG(opened_after.st_mode)
1799
+ or _project_path_identity(opened_after) != temporary_identity
1800
+ or _is_windows_reparse_point(checked_after)
1801
+ or not stat.S_ISREG(checked_after.st_mode)
1802
+ or _project_path_identity(checked_after) != temporary_identity
1803
+ ):
1804
+ raise APError(f"Temporary project file changed while writing: {relative}")
1805
+ _validate_windows_project_directories(relative, directories)
1806
+
1807
+ if target_identity is None:
1808
+ if os.path.lexists(target):
1809
+ raise APError(f"Project file appeared while writing: {relative}")
1810
+ else:
1811
+ checked_target = target.lstat()
1812
+ if (
1813
+ _is_windows_reparse_point(checked_target)
1814
+ or not stat.S_ISREG(checked_target.st_mode)
1815
+ or _project_path_identity(checked_target) != target_identity
1816
+ ):
1817
+ raise APError(f"Project file changed while writing: {relative}")
1818
+ _validate_windows_project_directories(relative, directories)
1819
+ os.replace(temporary, target)
1820
+ replaced = target.lstat()
1821
+ if (
1822
+ _is_windows_reparse_point(replaced)
1823
+ or not stat.S_ISREG(replaced.st_mode)
1824
+ or _project_path_identity(replaced) != temporary_identity
1825
+ ):
1826
+ raise APError(f"Project file changed after replacement: {relative}")
1827
+ _validate_windows_project_directories(relative, directories)
1828
+ except APError:
1829
+ if temporary is not None:
1830
+ with contextlib.suppress(OSError):
1831
+ temporary.unlink()
1832
+ raise
1833
+ except OSError as exc:
1834
+ if temporary is not None:
1835
+ with contextlib.suppress(OSError):
1836
+ temporary.unlink()
1837
+ raise APError(f"Cannot write project file safely: {relative}") from exc
1838
+ return
1839
+ with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
1840
+ assert parent_fd is not None
1841
+ temporary = f".{leaf}.autocoding-{uuid.uuid4().hex}"
1842
+ descriptor = -1
1843
+ try:
1844
+ descriptor = os.open(
1845
+ temporary,
1846
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
1847
+ 0o644,
1848
+ dir_fd=parent_fd,
1849
+ )
1850
+ with os.fdopen(descriptor, "wb") as handle:
1851
+ descriptor = -1
1852
+ handle.write(payload)
1853
+ handle.flush()
1854
+ os.fsync(handle.fileno())
1855
+ os.replace(temporary, leaf, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
1856
+ except OSError as exc:
1857
+ with contextlib.suppress(OSError):
1858
+ os.unlink(temporary, dir_fd=parent_fd)
1859
+ raise APError(f"Cannot write project file safely: {relative}") from exc
1860
+ finally:
1861
+ if descriptor >= 0:
1862
+ os.close(descriptor)
1863
+
1864
+
1865
+ def _safe_create_project_file(repo: Path, rel: str | Path, payload: bytes) -> None:
1866
+ """Atomically publish a new project file without replacing a concurrent creator."""
1867
+ relative = _safe_project_relative_path(rel)
1868
+ if os.name == "nt":
1869
+ temporary: Path | None = None
1870
+ try:
1871
+ target, directories, _ = _windows_project_path_snapshot(
1872
+ Path(repo),
1873
+ relative,
1874
+ create_parents=True,
1875
+ )
1876
+ _inject_project_file_parent_swap(Path(repo), relative)
1877
+ _validate_windows_project_directories(relative, directories)
1878
+ temporary = target.with_name(f".{target.name}.autocoding-{uuid.uuid4().hex}")
1879
+ with temporary.open("xb") as handle:
1880
+ handle.write(payload)
1881
+ handle.flush()
1882
+ os.fsync(handle.fileno())
1883
+ temporary_metadata = os.fstat(handle.fileno())
1884
+ checked_temporary = temporary.lstat()
1885
+ temporary_identity = _project_path_identity(temporary_metadata)
1886
+ if (
1887
+ not stat.S_ISREG(temporary_metadata.st_mode)
1888
+ or _is_windows_reparse_point(checked_temporary)
1889
+ or not stat.S_ISREG(checked_temporary.st_mode)
1890
+ or _project_path_identity(checked_temporary) != temporary_identity
1891
+ ):
1892
+ raise APError(f"Temporary project file is unsafe: {relative}")
1893
+ _validate_windows_project_directories(relative, directories)
1894
+ try:
1895
+ os.link(temporary, target, follow_symlinks=False)
1896
+ except FileExistsError as exc:
1897
+ raise APError(f"Project file appeared before create-only publish: {relative}") from exc
1898
+ checked_target = target.lstat()
1899
+ if (
1900
+ _is_windows_reparse_point(checked_target)
1901
+ or not stat.S_ISREG(checked_target.st_mode)
1902
+ or _project_path_identity(checked_target) != temporary_identity
1903
+ ):
1904
+ raise APError(f"Project file changed during create-only publish: {relative}")
1905
+ _validate_windows_project_directories(relative, directories)
1906
+ except APError:
1907
+ raise
1908
+ except OSError as exc:
1909
+ raise APError(f"Cannot create project file safely: {relative}") from exc
1910
+ finally:
1911
+ if temporary is not None:
1912
+ with contextlib.suppress(OSError):
1913
+ temporary.unlink()
1914
+ return
1915
+
1916
+ with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
1917
+ assert parent_fd is not None
1918
+ temporary = f".{leaf}.autocoding-{uuid.uuid4().hex}"
1919
+ descriptor = -1
1920
+ try:
1921
+ descriptor = os.open(
1922
+ temporary,
1923
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
1924
+ 0o644,
1925
+ dir_fd=parent_fd,
1926
+ )
1927
+ with os.fdopen(descriptor, "wb") as handle:
1928
+ descriptor = -1
1929
+ handle.write(payload)
1930
+ handle.flush()
1931
+ os.fsync(handle.fileno())
1932
+ temporary_metadata = os.stat(
1933
+ temporary,
1934
+ dir_fd=parent_fd,
1935
+ follow_symlinks=False,
1936
+ )
1937
+ if stat.S_ISLNK(temporary_metadata.st_mode) or not stat.S_ISREG(
1938
+ temporary_metadata.st_mode
1939
+ ):
1940
+ raise APError(f"Temporary project file is unsafe: {relative}")
1941
+ temporary_identity = _project_path_identity(temporary_metadata)
1942
+ try:
1943
+ os.link(
1944
+ temporary,
1945
+ leaf,
1946
+ src_dir_fd=parent_fd,
1947
+ dst_dir_fd=parent_fd,
1948
+ follow_symlinks=False,
1949
+ )
1950
+ except FileExistsError as exc:
1951
+ raise APError(f"Project file appeared before create-only publish: {relative}") from exc
1952
+ published = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
1953
+ if (
1954
+ stat.S_ISLNK(published.st_mode)
1955
+ or not stat.S_ISREG(published.st_mode)
1956
+ or _project_path_identity(published) != temporary_identity
1957
+ ):
1958
+ raise APError(f"Project file changed during create-only publish: {relative}")
1959
+ except APError:
1960
+ raise
1961
+ except OSError as exc:
1962
+ raise APError(f"Cannot create project file safely: {relative}") from exc
1963
+ finally:
1964
+ if descriptor >= 0:
1965
+ os.close(descriptor)
1966
+ with contextlib.suppress(OSError):
1967
+ os.unlink(temporary, dir_fd=parent_fd)
1968
+
1969
+
1970
+ def _safe_chmod_project_file(repo: Path, rel: str | Path, mode: int) -> None:
1971
+ relative = _safe_project_relative_path(rel)
1972
+ if mode < 0 or mode > 0o777:
1973
+ raise APError(f"Project file mode must be between 000 and 777: {relative}")
1974
+ if os.name == "nt":
1975
+ try:
1976
+ target, directories, complete = _windows_project_path_snapshot(
1977
+ Path(repo),
1978
+ relative,
1979
+ create_parents=False,
1980
+ )
1981
+ _inject_project_file_parent_swap(Path(repo), relative)
1982
+ if not complete or not os.path.lexists(target):
1983
+ raise APError(f"Project file is missing: {relative}")
1984
+ metadata = target.lstat()
1985
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
1986
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1987
+ identity = _project_path_identity(metadata)
1988
+ _validate_windows_project_directories(relative, directories)
1989
+ os.chmod(target, mode, follow_symlinks=False)
1990
+ checked = target.lstat()
1991
+ _validate_windows_project_directories(relative, directories)
1992
+ if (
1993
+ _is_windows_reparse_point(checked)
1994
+ or not stat.S_ISREG(checked.st_mode)
1995
+ or _project_path_identity(checked) != identity
1996
+ ):
1997
+ raise APError(f"Project file changed while setting its mode: {relative}")
1998
+ except APError:
1999
+ raise
2000
+ except OSError as exc:
2001
+ raise APError(f"Cannot set project file mode safely: {relative}") from exc
2002
+ return
2003
+
2004
+ with _open_project_parent(repo, relative) as (parent_fd, leaf):
2005
+ if parent_fd is None:
2006
+ raise APError(f"Project file is missing: {relative}")
2007
+ descriptor = -1
2008
+ try:
2009
+ descriptor = os.open(
2010
+ leaf,
2011
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
2012
+ dir_fd=parent_fd,
2013
+ )
2014
+ metadata = os.fstat(descriptor)
2015
+ if not stat.S_ISREG(metadata.st_mode):
2016
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
2017
+ os.fchmod(descriptor, mode)
2018
+ checked = os.fstat(descriptor)
2019
+ if _project_path_identity(checked) != _project_path_identity(metadata):
2020
+ raise APError(f"Project file changed while setting its mode: {relative}")
2021
+ except APError:
2022
+ raise
2023
+ except OSError as exc:
2024
+ raise APError(f"Cannot set project file mode safely: {relative}") from exc
2025
+ finally:
2026
+ if descriptor >= 0:
2027
+ os.close(descriptor)
2028
+
2029
+
2030
+ _INTERNAL_PROJECT_FILE_MAX_BYTES = 32 * 1024 * 1024
2031
+ _INTERNAL_PROJECT_CHMOD_MAX_BYTES = 1024 * 1024
2032
+ _INTERNAL_PROJECT_CHMOD_MAX_ENTRIES = 4096
2033
+
2034
+
2035
+ def cmd_project_file_safe(args: argparse.Namespace) -> None:
2036
+ repo = Path(args.repo).resolve()
2037
+ operation = _text(args.operation).lower()
2038
+ relative: Path | None = None
2039
+ if operation != "chmod-batch":
2040
+ relative = _safe_project_relative_path(args.path)
2041
+ if operation in {"write", "create"}:
2042
+ assert relative is not None
2043
+ payload = sys.stdin.buffer.read(_INTERNAL_PROJECT_FILE_MAX_BYTES + 1)
2044
+ if len(payload) > _INTERNAL_PROJECT_FILE_MAX_BYTES:
2045
+ raise APError(
2046
+ f"Internal project file payload exceeds {_INTERNAL_PROJECT_FILE_MAX_BYTES} bytes: {relative}"
2047
+ )
2048
+ if operation == "create":
2049
+ _safe_create_project_file(repo, relative, payload)
2050
+ else:
2051
+ _safe_write_project_file(repo, relative, payload)
2052
+ if _text(args.mode):
2053
+ try:
2054
+ mode = int(_text(args.mode), 8)
2055
+ except ValueError as exc:
2056
+ raise APError("Internal project write requires an octal --mode") from exc
2057
+ _safe_chmod_project_file(repo, relative, mode)
2058
+ elif operation == "chmod":
2059
+ assert relative is not None
2060
+ try:
2061
+ mode = int(_text(args.mode), 8)
2062
+ except ValueError as exc:
2063
+ raise APError("Internal project chmod requires an octal --mode") from exc
2064
+ _safe_chmod_project_file(repo, relative, mode)
2065
+ elif operation == "chmod-batch":
2066
+ payload = sys.stdin.buffer.read(_INTERNAL_PROJECT_CHMOD_MAX_BYTES + 1)
2067
+ if len(payload) > _INTERNAL_PROJECT_CHMOD_MAX_BYTES:
2068
+ raise APError("Internal project chmod batch exceeds its size limit")
2069
+ try:
2070
+ entries = json.loads(payload.decode("utf-8"))
2071
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
2072
+ raise APError("Internal project chmod batch must be valid UTF-8 JSON") from exc
2073
+ if not isinstance(entries, list) or len(entries) > _INTERNAL_PROJECT_CHMOD_MAX_ENTRIES:
2074
+ raise APError("Internal project chmod batch has an invalid entry count")
2075
+ mutations: list[tuple[Path, int]] = []
2076
+ for index, entry in enumerate(entries):
2077
+ if not isinstance(entry, dict) or set(entry) != {"path", "mode"}:
2078
+ raise APError(f"Internal project chmod batch entry {index} is invalid")
2079
+ mode_text = entry.get("mode")
2080
+ path_text = entry.get("path")
2081
+ if not isinstance(mode_text, str) or not re.fullmatch(r"[0-7]{3}", mode_text):
2082
+ raise APError(f"Internal project chmod batch entry {index} has an invalid mode")
2083
+ if not isinstance(path_text, str) or not path_text:
2084
+ raise APError(f"Internal project chmod batch entry {index} has an invalid path")
2085
+ mutations.append(
2086
+ (_safe_project_relative_path(path_text), int(mode_text, 8))
2087
+ )
2088
+ for mutation_path, mutation_mode in mutations:
2089
+ _safe_chmod_project_file(repo, mutation_path, mutation_mode)
2090
+ else:
2091
+ raise APError(f"Unsupported internal project file operation: {operation}")
2092
+ if args.json:
2093
+ result = {"operation": operation, "ok": True}
2094
+ if relative is not None:
2095
+ result["path"] = relative.as_posix()
2096
+ else:
2097
+ result["entry_count"] = len(mutations)
2098
+ print(json.dumps(result))
2099
+
2100
+
2101
+ def _directory_handle_identity(handle: int | Path) -> tuple[int, int]:
2102
+ metadata = os.fstat(handle) if isinstance(handle, int) else handle.lstat()
2103
+ if (
2104
+ not stat.S_ISDIR(metadata.st_mode)
2105
+ or (not isinstance(handle, int) and _is_windows_reparse_point(metadata))
2106
+ ):
2107
+ raise APError("Install I/O requires real project directories.")
2108
+ return _project_path_identity(metadata)
2109
+
2110
+
2111
+ def _safe_ensure_project_directory(repo: Path, rel: str | Path) -> None:
2112
+ relative = _safe_project_relative_path(rel)
2113
+ if os.name == "nt":
2114
+ try:
2115
+ target, directories, _ = _windows_project_path_snapshot(
2116
+ Path(repo),
2117
+ relative,
2118
+ create_parents=True,
2119
+ )
2120
+ _validate_windows_project_directories(relative, directories)
2121
+ try:
2122
+ target.mkdir()
2123
+ except FileExistsError:
2124
+ pass
2125
+ metadata = target.lstat()
2126
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
2127
+ raise APError(f"Project directory must be a real directory: {relative}")
2128
+ _validate_windows_project_directories(relative, directories)
2129
+ except APError:
2130
+ raise
2131
+ except OSError as exc:
2132
+ raise APError(f"Cannot create project directory safely: {relative}") from exc
2133
+ return
2134
+ with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
2135
+ assert parent_fd is not None
2136
+ try:
2137
+ os.mkdir(leaf, 0o755, dir_fd=parent_fd)
2138
+ except FileExistsError:
2139
+ pass
2140
+ metadata = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
2141
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
2142
+ raise APError(f"Project directory must be a real directory: {relative}")
2143
+
2144
+
2145
+ def _require_bound_project_directory(
2146
+ repo: Path,
2147
+ relative: Path,
2148
+ handle: int | Path,
2149
+ identity: tuple[int, int],
2150
+ ) -> None:
2151
+ opened = os.fstat(handle) if isinstance(handle, int) else handle.lstat()
2152
+ if not stat.S_ISDIR(opened.st_mode) or _project_path_identity(opened) != identity:
2153
+ raise APError(f"Install I/O directory handle changed: {relative}")
2154
+ target = repo / relative
2155
+ try:
2156
+ current = target.lstat()
2157
+ except OSError as exc:
2158
+ raise APError(f"Install I/O project parent changed: {relative}") from exc
2159
+ if (
2160
+ _is_windows_reparse_point(current)
2161
+ or not stat.S_ISDIR(current.st_mode)
2162
+ or _project_path_identity(current) != identity
2163
+ ):
2164
+ raise APError(f"Install I/O project parent changed: {relative}")
2165
+
2166
+
2167
+ def _inject_install_io_parent_swap(repo: Path, phase: str) -> None:
2168
+ if os.environ.get("AUTOCODING_TEST_MODE") != "1":
2169
+ return
2170
+ if os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_PHASE") != phase:
2171
+ return
2172
+ relative_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_PARENT", "")
2173
+ external_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_EXTERNAL", "")
2174
+ backup_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_BACKUP", "")
2175
+ relative = _safe_project_relative_path(relative_text)
2176
+ target = repo / relative
2177
+ external = Path(external_text)
2178
+ backup = Path(backup_text)
2179
+ if (
2180
+ not external.is_absolute()
2181
+ or not backup.is_absolute()
2182
+ or not external.is_dir()
2183
+ or external.is_symlink()
2184
+ or os.path.lexists(backup)
2185
+ ):
2186
+ raise APError("Invalid install I/O parent-swap test fixture.")
2187
+ target.rename(backup)
2188
+ target.symlink_to(external, target_is_directory=True)
2189
+
2190
+
2191
+ def _open_directory_at(parent_fd: int, name: str) -> int:
2192
+ descriptor = os.open(
2193
+ name,
2194
+ os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
2195
+ dir_fd=parent_fd,
2196
+ )
2197
+ metadata = os.fstat(descriptor)
2198
+ if not stat.S_ISDIR(metadata.st_mode):
2199
+ os.close(descriptor)
2200
+ raise APError(f"Install I/O path must be a real directory: {name}")
2201
+ return descriptor
2202
+
2203
+
2204
+ def _remove_tree_at(parent_fd: int, name: str, *, missing_ok: bool = False) -> None:
2205
+ try:
2206
+ metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
2207
+ except FileNotFoundError:
2208
+ if missing_ok:
2209
+ return
2210
+ raise
2211
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
2212
+ raise APError(f"Install I/O refuses a symlink or non-directory tree: {name}")
2213
+ if not getattr(shutil.rmtree, "avoids_symlink_attacks", False):
2214
+ raise APError("This Python runtime cannot remove project trees without symlink attacks.")
2215
+ shutil.rmtree(name, dir_fd=parent_fd)
2216
+
2217
+
2218
+ def _copy_file_between_fds(
2219
+ source_parent_fd: int,
2220
+ source_name: str,
2221
+ destination_parent_fd: int,
2222
+ destination_name: str,
2223
+ ) -> None:
2224
+ source_fd = -1
2225
+ destination_fd = -1
2226
+ temporary = f".{destination_name}.autocoding-{uuid.uuid4().hex}"
2227
+ try:
2228
+ source_fd = os.open(
2229
+ source_name,
2230
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
2231
+ dir_fd=source_parent_fd,
2232
+ )
2233
+ source_metadata = os.fstat(source_fd)
2234
+ if not stat.S_ISREG(source_metadata.st_mode):
2235
+ raise APError(f"Install I/O source must be a regular file: {source_name}")
2236
+ destination_fd = os.open(
2237
+ temporary,
2238
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
2239
+ stat.S_IMODE(source_metadata.st_mode),
2240
+ dir_fd=destination_parent_fd,
2241
+ )
2242
+ while True:
2243
+ block = os.read(source_fd, 1024 * 1024)
2244
+ if not block:
2245
+ break
2246
+ view = memoryview(block)
2247
+ while view:
2248
+ written = os.write(destination_fd, view)
2249
+ view = view[written:]
2250
+ os.fsync(destination_fd)
2251
+ os.close(destination_fd)
2252
+ destination_fd = -1
2253
+ os.replace(
2254
+ temporary,
2255
+ destination_name,
2256
+ src_dir_fd=destination_parent_fd,
2257
+ dst_dir_fd=destination_parent_fd,
2258
+ )
2259
+ except APError:
2260
+ raise
2261
+ except OSError as exc:
2262
+ raise APError(f"Cannot copy install transaction file safely: {destination_name}") from exc
2263
+ finally:
2264
+ if source_fd >= 0:
2265
+ os.close(source_fd)
2266
+ if destination_fd >= 0:
2267
+ os.close(destination_fd)
2268
+ with contextlib.suppress(OSError):
2269
+ os.unlink(temporary, dir_fd=destination_parent_fd)
2270
+
2271
+
2272
+ def _copy_directory_contents_fd(source_fd: int, destination_fd: int) -> None:
2273
+ for name in sorted(os.listdir(source_fd)):
2274
+ metadata = os.stat(name, dir_fd=source_fd, follow_symlinks=False)
2275
+ if stat.S_ISDIR(metadata.st_mode) and not stat.S_ISLNK(metadata.st_mode):
2276
+ os.mkdir(name, stat.S_IMODE(metadata.st_mode), dir_fd=destination_fd)
2277
+ source_child = _open_directory_at(source_fd, name)
2278
+ destination_child = _open_directory_at(destination_fd, name)
2279
+ try:
2280
+ _copy_directory_contents_fd(source_child, destination_child)
2281
+ finally:
2282
+ os.close(destination_child)
2283
+ os.close(source_child)
2284
+ elif stat.S_ISREG(metadata.st_mode):
2285
+ _copy_file_between_fds(source_fd, name, destination_fd, name)
2286
+ else:
2287
+ raise APError(f"Install I/O refuses a non-regular tree entry: {name}")
2288
+
2289
+
2290
+ def _copy_directory_at(
2291
+ source_parent_fd: int,
2292
+ source_name: str,
2293
+ destination_parent_fd: int,
2294
+ destination_name: str,
2295
+ ) -> None:
2296
+ source_fd = _open_directory_at(source_parent_fd, source_name)
2297
+ destination_fd = -1
2298
+ try:
2299
+ source_metadata = os.fstat(source_fd)
2300
+ os.mkdir(destination_name, stat.S_IMODE(source_metadata.st_mode), dir_fd=destination_parent_fd)
2301
+ destination_fd = _open_directory_at(destination_parent_fd, destination_name)
2302
+ try:
2303
+ _copy_directory_contents_fd(source_fd, destination_fd)
2304
+ except BaseException:
2305
+ os.close(destination_fd)
2306
+ destination_fd = -1
2307
+ with contextlib.suppress(OSError, APError):
2308
+ _remove_tree_at(destination_parent_fd, destination_name, missing_ok=True)
2309
+ raise
2310
+ finally:
2311
+ if destination_fd >= 0:
2312
+ os.close(destination_fd)
2313
+ finally:
2314
+ os.close(source_fd)
2315
+
2316
+
2317
+ def _unlink_file_at(parent_fd: int, name: str, *, missing_ok: bool = False) -> None:
2318
+ try:
2319
+ metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
2320
+ except FileNotFoundError:
2321
+ if missing_ok:
2322
+ return
2323
+ raise
2324
+ if stat.S_ISDIR(metadata.st_mode):
2325
+ raise APError(f"Install I/O refuses to unlink a directory as a file: {name}")
2326
+ os.unlink(name, dir_fd=parent_fd)
2327
+
2328
+
2329
+ def _install_io_owner(repo: Path) -> dict:
2330
+ payload = _safe_read_project_file(
2331
+ repo,
2332
+ _INSTALL_TRANSACTION_RELATIVE / "owner.json",
2333
+ max_bytes=4096,
2334
+ )
2335
+ if payload is None:
2336
+ raise APError("Install I/O requires a valid transaction owner.")
2337
+ try:
2338
+ owner = json.loads(payload.decode("utf-8"))
2339
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
2340
+ raise APError("Install I/O transaction owner is invalid.") from exc
2341
+ return _mapping(owner)
2342
+
2343
+
2344
+ def _require_install_io_access(repo: Path, operation: str) -> None:
2345
+ owner = _install_io_owner(repo)
2346
+ token = os.environ.get("AUTOCODING_INSTALL_TRANSACTION_TOKEN", "")
2347
+ expected = _text(owner.get("token_sha256"))
2348
+ if re.fullmatch(r"[0-9a-f]{64}", token) and re.fullmatch(r"[0-9a-f]{64}", expected):
2349
+ actual = hashlib.sha256(token.encode("ascii")).hexdigest()
2350
+ if hmac.compare_digest(actual, expected):
2351
+ return
2352
+ if operation in {"recover", "complete"}:
2353
+ try:
2354
+ pid = int(owner.get("pid"))
2355
+ os.kill(pid, 0)
2356
+ except ProcessLookupError:
2357
+ return
2358
+ except PermissionError as exc:
2359
+ raise APError("Install I/O recovery owner is still active.") from exc
2360
+ except (TypeError, ValueError, OSError) as exc:
2361
+ raise APError("Install I/O recovery owner cannot be verified.") from exc
2362
+ raise APError("Install I/O recovery owner is still active.")
2363
+ raise APError("Install I/O requires the active installer token.")
2364
+
2365
+
2366
+ def _cmd_install_io_posix(args: argparse.Namespace, repo: Path) -> None:
2367
+ operation = _text(args.operation).lower()
2368
+ if operation in {"switch", "recover"}:
2369
+ _safe_ensure_project_directory(repo, Path(".agents/skills"))
2370
+ if operation == "recover":
2371
+ _safe_ensure_project_directory(repo, Path("docs"))
2372
+ with contextlib.ExitStack() as stack:
2373
+ agents = stack.enter_context(_open_project_directory(repo, Path(".agents")))
2374
+ transaction = stack.enter_context(
2375
+ _open_project_directory(repo, _INSTALL_TRANSACTION_RELATIVE)
2376
+ )
2377
+ if not isinstance(agents, int) or not isinstance(transaction, int):
2378
+ raise APError("Install I/O project directories are missing.")
2379
+ bindings: list[tuple[Path, int, tuple[int, int]]] = [
2380
+ (Path(".agents"), agents, _directory_handle_identity(agents)),
2381
+ (_INSTALL_TRANSACTION_RELATIVE, transaction, _directory_handle_identity(transaction)),
2382
+ ]
2383
+ skills: int | None = None
2384
+ docs: int | None = None
2385
+ if operation in {"switch", "recover"}:
2386
+ skills = stack.enter_context(_open_project_directory(repo, Path(".agents/skills")))
2387
+ if not isinstance(skills, int):
2388
+ raise APError("Install I/O skills directory is missing.")
2389
+ bindings.append((Path(".agents/skills"), skills, _directory_handle_identity(skills)))
2390
+ if operation == "recover":
2391
+ docs = stack.enter_context(_open_project_directory(repo, Path("docs")))
2392
+ if not isinstance(docs, int):
2393
+ raise APError("Install I/O docs directory is missing.")
2394
+ bindings.append((Path("docs"), docs, _directory_handle_identity(docs)))
2395
+
2396
+ _inject_install_io_parent_swap(repo, operation)
2397
+ for relative, handle, identity in bindings:
2398
+ _require_bound_project_directory(repo, relative, handle, identity)
2399
+
2400
+ if operation == "switch":
2401
+ assert skills is not None
2402
+ _remove_tree_at(skills, "auto-coding-skill", missing_ok=True)
2403
+ os.rename(
2404
+ "new-skill",
2405
+ "auto-coding-skill",
2406
+ src_dir_fd=transaction,
2407
+ dst_dir_fd=skills,
2408
+ )
2409
+ _copy_file_between_fds(transaction, "new-manifest.json", agents, "managed-install.json")
2410
+ elif operation == "recover":
2411
+ assert skills is not None and docs is not None
2412
+ _remove_tree_at(skills, "auto-coding-skill", missing_ok=True)
2413
+ if args.old_skill_present:
2414
+ _copy_directory_at(transaction, "old-skill", skills, "auto-coding-skill")
2415
+ if args.old_manifest_present:
2416
+ _copy_file_between_fds(transaction, "old-manifest.json", agents, "managed-install.json")
2417
+ else:
2418
+ _unlink_file_at(agents, "managed-install.json", missing_ok=True)
2419
+ if args.old_engineering_present:
2420
+ _copy_file_between_fds(transaction, "old-ENGINEERING.md", docs, "ENGINEERING.md")
2421
+ else:
2422
+ _unlink_file_at(docs, "ENGINEERING.md", missing_ok=True)
2423
+ elif operation == "complete":
2424
+ completed = f".auto-coding-skill-install-completed-{os.getpid()}-{uuid.uuid4().hex}"
2425
+ os.rename(
2426
+ _INSTALL_TRANSACTION_RELATIVE.name,
2427
+ completed,
2428
+ src_dir_fd=agents,
2429
+ dst_dir_fd=agents,
2430
+ )
2431
+ _remove_tree_at(agents, completed)
2432
+ else:
2433
+ raise APError(f"Unsupported install I/O operation: {operation}")
2434
+
2435
+
2436
+ def _cmd_install_io_windows(args: argparse.Namespace, repo: Path) -> None:
2437
+ operation = _text(args.operation).lower()
2438
+ if operation in {"switch", "recover"}:
2439
+ _safe_ensure_project_directory(repo, Path(".agents/skills"))
2440
+ if operation == "recover":
2441
+ _safe_ensure_project_directory(repo, Path("docs"))
2442
+ transaction = repo / _INSTALL_TRANSACTION_RELATIVE
2443
+ skills = repo / ".agents" / "skills"
2444
+ agents = repo / ".agents"
2445
+ docs = repo / "docs"
2446
+ snapshots: list[tuple[Path, tuple[int, int]]] = []
2447
+ for directory in [agents, transaction, *([skills] if operation in {"switch", "recover"} else []), *([docs] if operation == "recover" else [])]:
2448
+ metadata = directory.lstat()
2449
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
2450
+ raise APError(f"Install I/O project directory is unsafe: {directory.relative_to(repo)}")
2451
+ snapshots.append((directory, _project_path_identity(metadata)))
2452
+ _inject_install_io_parent_swap(repo, operation)
2453
+
2454
+ def validate() -> None:
2455
+ for directory, identity in snapshots:
2456
+ metadata = directory.lstat()
2457
+ if (
2458
+ _is_windows_reparse_point(metadata)
2459
+ or not stat.S_ISDIR(metadata.st_mode)
2460
+ or _project_path_identity(metadata) != identity
2461
+ ):
2462
+ raise APError(f"Install I/O project parent changed: {directory.relative_to(repo)}")
2463
+
2464
+ validate()
2465
+ if operation == "switch":
2466
+ target = skills / "auto-coding-skill"
2467
+ if os.path.lexists(target):
2468
+ shutil.rmtree(target)
2469
+ os.replace(transaction / "new-skill", target)
2470
+ _safe_write_project_file(repo, Path(".agents/managed-install.json"), (transaction / "new-manifest.json").read_bytes())
2471
+ elif operation == "recover":
2472
+ target = skills / "auto-coding-skill"
2473
+ if os.path.lexists(target):
2474
+ shutil.rmtree(target)
2475
+ if args.old_skill_present:
2476
+ shutil.copytree(transaction / "old-skill", target, symlinks=True)
2477
+ if args.old_manifest_present:
2478
+ _safe_write_project_file(repo, Path(".agents/managed-install.json"), (transaction / "old-manifest.json").read_bytes())
2479
+ elif os.path.lexists(agents / "managed-install.json"):
2480
+ (agents / "managed-install.json").unlink()
2481
+ if args.old_engineering_present:
2482
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), (transaction / "old-ENGINEERING.md").read_bytes())
2483
+ elif os.path.lexists(docs / "ENGINEERING.md"):
2484
+ (docs / "ENGINEERING.md").unlink()
2485
+ elif operation == "complete":
2486
+ completed = agents / f".auto-coding-skill-install-completed-{os.getpid()}-{uuid.uuid4().hex}"
2487
+ os.replace(transaction, completed)
2488
+ shutil.rmtree(completed)
2489
+ else:
2490
+ raise APError(f"Unsupported install I/O operation: {operation}")
2491
+ validate()
2492
+
2493
+
2494
+ def cmd_install_io(args: argparse.Namespace) -> None:
2495
+ repo = Path(args.repo).resolve()
2496
+ operation = _text(args.operation).lower()
2497
+ _require_install_io_access(repo, operation)
2498
+ if os.name == "nt":
2499
+ _cmd_install_io_windows(args, repo)
2500
+ else:
2501
+ _cmd_install_io_posix(args, repo)
2502
+ if args.json:
2503
+ print(json.dumps({"operation": operation, "ok": True}))
2504
+
2505
+
2506
+ def _managed_scaffold_convergence(
2507
+ repo: Path,
2508
+ selected: dict[str, str],
2509
+ version: str,
2510
+ *,
2511
+ write: bool,
2512
+ ) -> list[dict]:
2513
+ actions: list[dict] = []
2514
+ for rel, canonical in sorted(selected.items()):
2515
+ if rel not in MANAGED_FRAMEWORK_DOCS:
2516
+ continue
2517
+ current = _safe_read_project_file(repo, rel)
2518
+ expected = canonical.encode("utf-8")
2519
+ if current == expected:
2520
+ continue
2521
+ if current is not None:
2522
+ archive_rel, archive_required = _select_project_archive_target(
2523
+ repo,
2524
+ Path(".agents") / "archive" / "auto-coding-skill" / version / rel,
2525
+ current,
2526
+ legacy_digest_payload=current,
2527
+ )
2528
+ if archive_required:
2529
+ actions.append({"action": "archive", "path": archive_rel.as_posix()})
2530
+ if write:
2531
+ _safe_create_project_file(repo, archive_rel, current)
2532
+ actions.append({"action": "create" if current is None else "replace", "path": rel})
2533
+ if write:
2534
+ _safe_write_project_file(repo, rel, expected)
2535
+ return actions
2536
+
2537
+
2538
+ def _is_allowed_project_doc(rel: Path, candidate: Path | None = None) -> bool:
2539
+ if rel == _PROJECT_CONFIG_RELATIVE:
2540
+ return candidate is None or (candidate.is_file() and not candidate.is_symlink())
2541
+ if any(rel.match(pattern) for pattern in PROJECT_FEEDBACK_PATTERNS):
2542
+ return candidate is None or (candidate.is_file() and not candidate.is_symlink())
2543
+ return any(rel == root or root in rel.parents for root in _PROJECT_ARTIFACT_ROOTS)
2544
+
2545
+
2546
+ def cmd_project_converge(args: argparse.Namespace) -> None:
2547
+ repo = Path(args.repo).resolve()
2548
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
2549
+ engineering = repo / "docs" / "ENGINEERING.md"
2550
+ config_plan = _project_config_convergence_plan(repo, template)
2551
+ output = config_plan["engineering_output"]
2552
+ current = config_plan["engineering_current"]
2553
+ changed = current != output
2554
+ actions: list[dict] = []
2555
+ version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
2556
+ managed_templates = templates_for("all")
2557
+ managed_plan = _managed_scaffold_convergence(repo, managed_templates, version, write=False)
2558
+
2559
+ def archive_previous(source_path: Path, content: str, label: str) -> None:
2560
+ archive = (
2561
+ Path(".agents") / "archive" / "auto-coding-skill" / version
2562
+ / source_path.relative_to(repo)
2563
+ )
2564
+ content_bytes = content.encode("utf-8")
2565
+ archive, archive_required = _select_project_archive_target(
2566
+ repo,
2567
+ archive,
2568
+ content_bytes,
2569
+ legacy_digest_payload=content_bytes,
2570
+ )
2571
+ if not archive_required:
2572
+ return
2573
+ actions.append({"action": "archive", "path": archive.as_posix(), "detail": label})
2574
+ if args.write:
2575
+ _safe_create_project_file(repo, archive, content_bytes)
2576
+
2577
+ def archive_extra(source_path: Path, label: str) -> None:
2578
+ source_rel = source_path.relative_to(repo)
2579
+ content = _safe_read_project_file(repo, source_rel)
2580
+ if content is None:
2581
+ raise APError(f"Project file disappeared during convergence: {source_rel.as_posix()}")
2582
+ archive, archive_required = _select_project_archive_target(
2583
+ repo,
2584
+ Path(".agents") / "archive" / "auto-coding-skill" / version / source_rel,
2585
+ content,
2586
+ legacy_digest_payload=content,
2587
+ )
2588
+ if archive_required:
2589
+ actions.append({"action": "archive", "path": archive.as_posix(), "detail": label})
2590
+ if args.write:
2591
+ _safe_create_project_file(repo, archive, content)
2592
+
2593
+ if changed and current:
2594
+ archive_header = (
2595
+ f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
2596
+ "Historical and non-authoritative. Do not use this file as workflow policy.\n\n---\n\n"
2597
+ )
2598
+ archive_previous(engineering, archive_header + current, "previous project configuration")
2599
+ if config_plan["overlay_output"] is not None:
2600
+ actions.append({
2601
+ "action": "create",
2602
+ "path": _PROJECT_CONFIG_RELATIVE.as_posix(),
2603
+ "detail": (
2604
+ "project-owned effective-config overlay; migrated "
2605
+ f"{len(config_plan['migrated_paths'])} value paths"
2606
+ ),
2607
+ })
2608
+ if args.write:
2609
+ _safe_create_project_file(
2610
+ repo,
2611
+ _PROJECT_CONFIG_RELATIVE,
2612
+ config_plan["overlay_output"],
2613
+ )
2614
+ if changed:
2615
+ actions.append({
2616
+ "action": "create" if not current else "replace",
2617
+ "path": "docs/ENGINEERING.md",
2618
+ })
2619
+ if args.write:
2620
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), output.encode("utf-8"))
2621
+
2622
+ for rel, canonical in sorted(templates_for("all").items()):
2623
+ if rel in MANAGED_FRAMEWORK_DOCS:
2624
+ continue
2625
+ target = repo / rel
2626
+ existing_payload = _safe_read_project_file(repo, rel)
2627
+ try:
2628
+ existing = existing_payload.decode("utf-8") if existing_payload is not None else ""
2629
+ except UnicodeDecodeError as exc:
2630
+ raise APError(f"Project documentation must be UTF-8: {rel}") from exc
2631
+ managed = rel in MANAGED_FRAMEWORK_DOCS
2632
+ if existing and (not managed or existing == canonical):
2633
+ continue
2634
+ if existing:
2635
+ archive_previous(target, existing, "previous managed documentation template")
2636
+ actions.append({"action": "create" if not existing else "replace", "path": rel})
2637
+ if args.write:
2638
+ _safe_write_project_file(repo, rel, canonical.encode("utf-8"))
2639
+
2640
+ actions.extend(
2641
+ _managed_scaffold_convergence(repo, managed_templates, version, write=True)
2642
+ if args.write
2643
+ else managed_plan
2644
+ )
2645
+
2646
+ allowed_docs = {
2647
+ Path("docs/ENGINEERING.md"),
2648
+ Path("docs/tools/autopipeline/ap.py"),
2649
+ _PROJECT_CONFIG_RELATIVE,
2650
+ *(Path(rel) for rel in templates_for("all")),
2651
+ }
2652
+ docs_root = repo / "docs"
2653
+ if docs_root.exists():
2654
+ for candidate in sorted(docs_root.rglob("*")):
2655
+ try:
2656
+ candidate_metadata = candidate.lstat()
2657
+ except OSError as exc:
2658
+ raise APError("Cannot inspect active project documentation safely") from exc
2659
+ if stat.S_ISDIR(candidate_metadata.st_mode) and not _is_windows_reparse_point(candidate_metadata):
2660
+ continue
2661
+ rel = candidate.relative_to(repo)
2662
+ if _is_windows_reparse_point(candidate_metadata) or not stat.S_ISREG(candidate_metadata.st_mode):
2663
+ raise APError(
2664
+ "Active project documentation must contain only real directories and "
2665
+ f"regular non-symlink files: {rel.as_posix()}"
2666
+ )
2667
+ if rel in allowed_docs or _is_allowed_project_doc(rel, candidate):
2668
+ continue
2669
+ archive_extra(candidate, "removed from the exact docs framework")
2670
+ actions.append({"action": "delete", "path": rel.as_posix()})
2671
+ if args.write:
2672
+ candidate.unlink()
2673
+ if args.write:
2674
+ for directory in sorted(
2675
+ (item for item in docs_root.rglob("*") if item.is_dir()),
2676
+ key=lambda item: len(item.parts),
2677
+ reverse=True,
2678
+ ):
2679
+ try:
2680
+ directory.rmdir()
2681
+ except OSError:
2682
+ pass
2683
+
2684
+ result = {"changed": bool(actions), "mode": "write" if args.write else "plan", "actions": actions}
2685
+ if args.json:
2686
+ print(json.dumps(result, ensure_ascii=False, indent=2))
2687
+ return
2688
+ for action in actions:
2689
+ print(f"[project-converge] {action['action']}: {action['path']}")
2690
+ if not actions:
2691
+ print("[project-converge] OK: already current")
2692
+
2693
+
2694
+ def cmd_scaffold(args: argparse.Namespace) -> None:
2695
+ repo = Path(args.repo).resolve()
2696
+ group = str(args.group or "").strip().lower()
2697
+ try:
2698
+ selected = templates_for(group)
2699
+ except KeyError as exc:
2700
+ choices = ", ".join(scaffold_groups() + ["all"])
2701
+ raise APError(f"Unknown scaffold group '{group}'. Choose one of: {choices}") from exc
2702
+
2703
+ write = bool(args.write)
2704
+ force = bool(args.force)
2705
+ actions: list[dict] = []
2706
+ for rel, content in sorted(selected.items()):
2707
+ current = _safe_read_project_file(repo, rel)
2708
+ if current is not None and not force:
2709
+ actions.append({"path": rel, "action": "exists"})
2710
+ continue
2711
+ action = "write" if write else "would-write"
2712
+ actions.append({"path": rel, "action": action})
2713
+ if write:
2714
+ _safe_write_project_file(repo, rel, content.encode("utf-8"))
2715
+
2716
+ result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
2717
+ if args.json:
2718
+ print(json.dumps(result, ensure_ascii=False, indent=2))
2719
+ return
2720
+ for item in actions:
2721
+ print(f"[scaffold] {item['action']}: {item['path']}")
2722
+ if not write:
2723
+ print("[scaffold] plan only; re-run with --write to create missing files")
2724
+
2725
+
2726
+ def cmd_managed_scaffold_converge(args: argparse.Namespace) -> None:
2727
+ repo = Path(args.repo).resolve()
2728
+ group = str(args.group or "").strip().lower()
2729
+ selected = templates_for(group)
2730
+ write = bool(args.write)
2731
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
2732
+ version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
2733
+ actions = _managed_scaffold_convergence(repo, selected, version, write=write)
2734
+ result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
2735
+ if args.json:
2736
+ print(json.dumps(result, ensure_ascii=False, indent=2))
2737
+ return
2738
+ for item in actions:
2739
+ print(f"[managed-scaffold-converge] {item['action']}: {item['path']}")
2740
+
2741
+
2742
+ _CONFIG_STATUS_FIELDS: tuple[tuple[str, tuple[str, ...], bool, bool], ...] = (
2743
+ ("workflow.skill_version", ("workflow", "skill_version"), False, True),
2744
+ ("workflow.mode", ("workflow", "mode"), False, True),
2745
+ ("workflow.profile", ("workflow", "profile"), False, True),
2746
+ ("workflow.completion", ("workflow", "completion"), False, True),
2747
+ ("project.name", ("project", "name"), False, True),
2748
+ ("concurrency.isolation", ("concurrency", "isolation"), False, True),
2749
+ ("concurrency.base_ref", ("concurrency", "base_ref"), False, True),
2750
+ ("concurrency.target_branch", ("concurrency", "target_branch"), False, True),
2751
+ ("concurrency.branch_prefix", ("concurrency", "branch_prefix"), False, True),
2752
+ ("concurrency.worktree_root", ("concurrency", "worktree_root"), False, True),
2753
+ ("concurrency.cleanup_merged", ("concurrency", "cleanup_merged"), False, True),
2754
+ ("concurrency.delete_remote_branch", ("concurrency", "delete_remote_branch"), False, True),
2755
+ ("concurrency.disposable_ignored", ("concurrency", "disposable_ignored"), True, False),
2756
+ ("validation.on_unmapped", ("validation", "on_unmapped"), False, True),
2757
+ ("validation.max_command_seconds", ("validation", "max_command_seconds"), False, True),
2758
+ ("validation.max_total_seconds", ("validation", "max_total_seconds"), False, True),
2759
+ ("validation.routes", ("validation", "routes"), True, False),
2760
+ ("risk.rules", ("risk", "rules"), True, False),
2761
+ ("docs.framework", ("docs", "framework"), False, True),
2762
+ ("access.project.frontend.url", ("access", "project", "frontend", "url"), False, False),
2763
+ ("access.project.frontend.username", ("access", "project", "frontend", "username"), False, False),
2764
+ ("access.project.frontend.password", ("access", "project", "frontend", "password"), False, False),
2765
+ ("access.project.backend.url", ("access", "project", "backend", "url"), False, False),
2766
+ ("access.project.backend.username", ("access", "project", "backend", "username"), False, False),
2767
+ ("access.project.backend.password", ("access", "project", "backend", "password"), False, False),
2768
+ ("access.jenkins.frontend.url", ("access", "jenkins", "frontend", "url"), False, False),
2769
+ ("access.jenkins.frontend.username", ("access", "jenkins", "frontend", "username"), False, False),
2770
+ ("access.jenkins.frontend.password", ("access", "jenkins", "frontend", "password"), False, False),
2771
+ ("access.jenkins.backend.url", ("access", "jenkins", "backend", "url"), False, False),
2772
+ ("access.jenkins.backend.username", ("access", "jenkins", "backend", "username"), False, False),
2773
+ ("access.jenkins.backend.password", ("access", "jenkins", "backend", "password"), False, False),
2774
+ ("access.gitlab.url", ("access", "gitlab", "url"), False, False),
2775
+ ("access.gitlab.username", ("access", "gitlab", "username"), False, False),
2776
+ ("access.gitlab.password", ("access", "gitlab", "password"), False, False),
2777
+ ("access.nexus.frontend.url", ("access", "nexus", "frontend", "url"), False, False),
2778
+ ("access.nexus.frontend.username", ("access", "nexus", "frontend", "username"), False, False),
2779
+ ("access.nexus.frontend.password", ("access", "nexus", "frontend", "password"), False, False),
2780
+ )
2781
+
2782
+
2783
+ def _config_value(cfg: dict, path: tuple[str, ...]) -> tuple[bool, object]:
2784
+ current: object = cfg
2785
+ for key in path:
2786
+ if not isinstance(current, dict) or key not in current:
2787
+ return False, ""
2788
+ current = current[key]
2789
+ return True, current
2790
+
2791
+
2792
+ def _config_status_report(repo: Path) -> dict:
2793
+ cfg = load_effective_config(repo)
2794
+ fields: dict[str, dict] = {}
2795
+ for label, path, sequence, expose_value in _CONFIG_STATUS_FIELDS:
2796
+ present, value = _config_value(cfg, path)
2797
+ if label.startswith("access.") or label in {"project.name", "docs.framework"}:
2798
+ configured = isinstance(value, str) and _is_explicit_fill(value)
2799
+ elif sequence:
2800
+ configured = isinstance(value, list) and bool(value)
2801
+ else:
2802
+ configured = bool(present and (
2803
+ len(value) > 0 if isinstance(value, (list, dict, str)) else value is not None
2804
+ ))
2805
+ state = {
2806
+ "present": present,
2807
+ "configured": bool(present and configured),
2808
+ }
2809
+ if sequence:
2810
+ state["item_count"] = len(value) if isinstance(value, list) else -1
2811
+ if expose_value and present and isinstance(value, (str, bool, int, float)):
2812
+ state["value"] = value
2813
+ fields[label] = state
2814
+ commands = _mapping(cfg.get("commands"))
2815
+ overlay_payload = _safe_read_project_file(
2816
+ repo,
2817
+ _PROJECT_CONFIG_RELATIVE,
2818
+ max_bytes=128 * 1024,
2819
+ )
2820
+ contract = cmd_doctor(
2821
+ argparse.Namespace(repo=str(repo), collect=True, quiet=True, record=False)
2822
+ )
2823
+ report = {
2824
+ "schema": "auto-coding-skill/effective-config-status/v1",
2825
+ "managed_version": _text(_mapping(cfg.get("workflow")).get("skill_version")),
2826
+ "project_overlay": {
2827
+ "path": _PROJECT_CONFIG_RELATIVE.as_posix(),
2828
+ "present": overlay_payload is not None,
2829
+ "schema": PROJECT_CONFIG_SCHEMA if overlay_payload is not None else "",
2830
+ },
2831
+ "project": {"name": _text(_mapping(cfg.get("project")).get("name"))},
2832
+ "fields": fields,
2833
+ "commands": {
2834
+ "configured_names": sorted(
2835
+ str(name)
2836
+ for name, value in commands.items()
2837
+ if isinstance(name, str) and isinstance(value, str) and value.strip()
2838
+ )
2839
+ },
2840
+ "risk_rule_count": len(_mapping(cfg.get("risk")).get("rules") or [])
2841
+ if isinstance(_mapping(cfg.get("risk")).get("rules") or [], list)
2842
+ else -1,
2843
+ "validation_route_count": len(_mapping(cfg.get("validation")).get("routes") or [])
2844
+ if isinstance(_mapping(cfg.get("validation")).get("routes") or [], list)
2845
+ else -1,
2846
+ "policy_issues": _workflow_policy_issues(repo, cfg),
2847
+ "contract_valid": not bool(contract["issues"]),
2848
+ "contract_issues": contract["issues"],
2849
+ "contract_advisories": contract["advisories"],
2850
+ }
2851
+ canonical = json.dumps(report, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
2852
+ report["redacted_sha256"] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
2853
+ return report
2854
+
2855
+
2856
+ def cmd_config_effective(args: argparse.Namespace) -> None:
2857
+ report = _config_status_report(Path(args.repo).resolve())
2858
+ if args.json:
2859
+ print(json.dumps(report, ensure_ascii=False, indent=2))
2860
+ return
2861
+ print(f"[config] managed_version={report['managed_version'] or '(missing)'}")
2862
+ print(
2863
+ "[config] project_overlay="
2864
+ + ("valid" if report["project_overlay"]["present"] else "missing")
2865
+ )
2866
+ print(f"[config] project={report['project']['name'] or '(missing)'}")
2867
+ print(f"[config] contract_valid={str(report['contract_valid']).lower()}")
2868
+ print(f"[config] redacted_sha256={report['redacted_sha256']}")
2869
+
2870
+
2871
+ def cmd_install(args: argparse.Namespace) -> None:
2872
+ repo = Path(args.repo).resolve()
2873
+ templates = _skill_root() / "data" / "templates"
2874
+ config_convergence = _project_config_convergence_plan(
2875
+ repo,
2876
+ templates / "ENGINEERING.md",
2877
+ )
2878
+
2879
+ planned_copies: list[tuple[Path, Path]] = []
2880
+ for rel in _CORE_DOC_TEMPLATES:
2881
+ planned_copies.append((templates / "docs" / rel, repo / "docs" / rel))
2882
+
2883
+ if args.bridges:
2884
+ planned_copies.append((templates / "bridges" / "AGENTS.md", repo / "AGENTS.md"))
2885
+
2886
+ tools_dir = repo / "docs" / "tools" / "autopipeline"
2887
+ planned_copies.append((templates / "tools" / "ap.py", tools_dir / "ap.py"))
2888
+
2889
+ engineering = repo / "docs" / "ENGINEERING.md"
2890
+ conflicts: list[Path] = [engineering] if config_convergence["engineering_current"] else []
2891
+ planned_files: list[tuple[Path, Path]] = []
2892
+ for src, dst in planned_copies:
2893
+ if src.is_file():
2894
+ planned_files.append((src, dst))
2895
+ continue
2896
+ for source_file in _iter_files(src):
2897
+ planned_files.append((source_file, dst / source_file.relative_to(src)))
2898
+ for _, dst in planned_files:
2899
+ if _safe_read_project_file(repo, dst.relative_to(repo)) is not None:
2900
+ conflicts.append(dst)
2901
+ if conflicts and not args.force:
2902
+ conflict_list = "\n".join(f"- {_repo_rel(repo, path)}" for path in conflicts[:20])
2903
+ extra = "" if len(conflicts) <= 20 else f"\n- ... and {len(conflicts) - 20} more"
2904
+ raise APError(
2905
+ "Install would overwrite existing files:\n"
2906
+ f"{conflict_list}{extra}\n"
2907
+ "For existing projects, run `autocoding init` or an explicit `autocoding sync`. "
2908
+ "Use `install --force` only when intentionally resetting generated docs/tooling."
2909
+ )
2910
+
2911
+ for src, dst in planned_files:
2912
+ _safe_write_project_file(repo, dst.relative_to(repo), src.read_bytes())
2913
+
2914
+ if config_convergence["overlay_output"] is not None:
2915
+ _safe_create_project_file(
2916
+ repo,
2917
+ _PROJECT_CONFIG_RELATIVE,
2918
+ config_convergence["overlay_output"],
2919
+ )
2920
+ _safe_write_project_file(
2921
+ repo,
2922
+ Path("docs/ENGINEERING.md"),
2923
+ config_convergence["engineering_output"].encode("utf-8"),
2924
+ )
2925
+ cmd_scaffold(
2926
+ argparse.Namespace(repo=str(repo), group="feedback", write=True, force=args.force, json=False)
2927
+ )
1398
2928
  if args.full:
1399
2929
  cmd_scaffold(
1400
2930
  argparse.Namespace(repo=str(repo), group="all", write=True, force=args.force, json=False)
@@ -1404,7 +2934,7 @@ def cmd_install(args: argparse.Namespace) -> None:
1404
2934
  print(f"[install] OK: {layout} scaffold installed into {repo}")
1405
2935
  print(
1406
2936
  "[install] Next: fill every access.* URL, username, and password in "
1407
- "docs/ENGINEERING.md, run doctor, and commit that file into Git."
2937
+ "docs/project/auto-coding-skill.yaml, run doctor, and commit that file into Git."
1408
2938
  )
1409
2939
 
1410
2940
 
@@ -1412,11 +2942,25 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1412
2942
  repo = Path(args.repo).resolve()
1413
2943
  ensure_git_repo(repo)
1414
2944
  write = bool(args.write) and not bool(args.dry_run)
2945
+ if write:
2946
+ raise APError(
2947
+ "Project-local `ap.py upgrade --write` was retired in favor of the "
2948
+ "transactional installer. Run `autocoding init` for one project or "
2949
+ "`autocoding sync --projects <path[,path...]>` for explicit projects. "
2950
+ "Use `ap.py upgrade --dry-run` only as a read-only legacy diagnostic."
2951
+ )
1415
2952
  source_root = _find_skill_asset_root(repo)
1416
2953
  templates = source_root / "data" / "templates"
1417
2954
  template_engineering = templates / "ENGINEERING.md"
1418
2955
  template_agents = templates / "bridges" / "AGENTS.md"
1419
2956
  actions: list[dict] = []
2957
+ managed_version = _text(
2958
+ _mapping(_read_frontmatter_markdown(template_engineering)[0].get("workflow")).get("skill_version")
2959
+ ) or "current"
2960
+ feedback_templates = templates_for("feedback")
2961
+ feedback_plan = _managed_scaffold_convergence(
2962
+ repo, feedback_templates, managed_version, write=False
2963
+ )
1420
2964
 
1421
2965
  registry = _task_state_root(repo) / "tasks"
1422
2966
  active_manifests = sorted(registry.glob("*.json")) if registry.exists() else []
@@ -1428,6 +2972,8 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1428
2972
  "workflow semantics must not change mid-task."
1429
2973
  )
1430
2974
 
2975
+ config_convergence = _project_config_convergence_plan(repo, template_engineering)
2976
+
1431
2977
  def add_action(kind: str, path: Path, action: str, detail: str = "") -> None:
1432
2978
  actions.append({
1433
2979
  "kind": kind,
@@ -1477,20 +3023,21 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1477
3023
  archive_header = (
1478
3024
  f"# Archived ENGINEERING.md before auto-coding-skill {version} docs convergence\n\n"
1479
3025
  "This file is historical and non-authoritative. Known duplicate workflow sections\n"
1480
- "were removed from docs/ENGINEERING.md. Move any still-current project facts into\n"
1481
- "docs/ENGINEERING.md project-fact sections or docs/project/.\n\n---\n\n"
3026
+ "were removed from docs/ENGINEERING.md. Move still-current configuration into\n"
3027
+ "docs/project/auto-coding-skill.yaml and durable facts into docs/project/.\n\n---\n\n"
1482
3028
  )
1483
3029
  archive_content = archive_header + engineering_plan["original"]
1484
- archive_dir = repo / "docs" / "archive" / "workflow"
1485
- archive = archive_dir / f"ENGINEERING.pre-{version}.md"
1486
- if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
1487
- digest = hashlib.sha256(engineering_plan["original"].encode("utf-8")).hexdigest()[:12]
1488
- archive = archive_dir / f"ENGINEERING.pre-{version}-{digest}.md"
1489
- if not archive.exists():
3030
+ archive_rel, archive_required = _select_project_archive_target(
3031
+ repo,
3032
+ Path("docs/archive/workflow") / f"ENGINEERING.pre-{version}.md",
3033
+ archive_content.encode("utf-8"),
3034
+ legacy_digest_payload=engineering_plan["original"].encode("utf-8"),
3035
+ )
3036
+ archive = repo / archive_rel
3037
+ if archive_required:
1490
3038
  add_action("policy", archive, "archive", "before duplicate workflow section cleanup")
1491
3039
  if write:
1492
- archive.parent.mkdir(parents=True, exist_ok=True)
1493
- archive.write_text(archive_content, encoding="utf-8")
3040
+ _safe_create_project_file(repo, archive_rel, archive_content.encode("utf-8"))
1494
3041
 
1495
3042
  tool_files = [
1496
3043
  (
@@ -1543,23 +3090,24 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1543
3090
  current_agents = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
1544
3091
  if canonical_agents and current_agents != canonical_agents:
1545
3092
  if current_agents:
1546
- archive_dir = repo / "docs" / "archive" / "workflow"
1547
3093
  archive_header = (
1548
- "# Archived AGENTS.md before auto-coding-skill 4.2.8\n\n"
3094
+ "# Archived AGENTS.md before auto-coding-skill 4.3.1\n\n"
1549
3095
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
1550
- "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
3096
+ "Move project configuration into docs/project/auto-coding-skill.yaml and facts into docs/project/,\n"
1551
3097
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
1552
3098
  )
1553
3099
  archive_content = archive_header + current_agents
1554
- archive = archive_dir / "AGENTS.pre-4.2.8.md"
1555
- if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
1556
- digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
1557
- archive = archive_dir / f"AGENTS.pre-4.2.8-{digest}.md"
1558
- if not archive.exists():
3100
+ archive_rel, archive_required = _select_project_archive_target(
3101
+ repo,
3102
+ Path("docs/archive/workflow/AGENTS.pre-4.3.1.md"),
3103
+ archive_content.encode("utf-8"),
3104
+ legacy_digest_payload=current_agents.encode("utf-8"),
3105
+ )
3106
+ archive = repo / archive_rel
3107
+ if archive_required:
1559
3108
  add_action("policy", archive, "archive", "historical and non-authoritative")
1560
3109
  if write:
1561
- archive.parent.mkdir(parents=True, exist_ok=True)
1562
- archive.write_text(archive_content, encoding="utf-8")
3110
+ _safe_create_project_file(repo, archive_rel, archive_content.encode("utf-8"))
1563
3111
  add_action("policy", agents_path, "replace", "fully managed canonical AGENTS.md")
1564
3112
  if write:
1565
3113
  agents_path.write_text(canonical_agents, encoding="utf-8")
@@ -1579,40 +3127,46 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1579
3127
  else:
1580
3128
  add_action("doc", dst, "ok")
1581
3129
 
3130
+ feedback_actions = (
3131
+ _managed_scaffold_convergence(repo, feedback_templates, managed_version, write=True)
3132
+ if write
3133
+ else feedback_plan
3134
+ )
3135
+ for item in feedback_actions:
3136
+ actions.append({
3137
+ "kind": "doc",
3138
+ "path": item["path"],
3139
+ "action": item["action"],
3140
+ "detail": "managed Skill feedback template",
3141
+ })
3142
+
1582
3143
  engineering = repo / "docs" / "ENGINEERING.md"
1583
- if engineering.exists() and template_engineering.exists():
1584
- planned_engineering = engineering_plan["output"] or engineering.read_text(encoding="utf-8")
1585
- planned_engineering = _sync_managed_workflow_text(
1586
- planned_engineering,
1587
- template_engineering.read_text(encoding="utf-8"),
3144
+ if config_convergence["overlay_output"] is not None:
3145
+ add_action(
3146
+ "config",
3147
+ repo / _PROJECT_CONFIG_RELATIVE,
3148
+ "create",
3149
+ f"migrate {len(config_convergence['migrated_paths'])} project-owned value paths",
3150
+ )
3151
+ if write:
3152
+ _safe_create_project_file(
3153
+ repo,
3154
+ _PROJECT_CONFIG_RELATIVE,
3155
+ config_convergence["overlay_output"],
3156
+ )
3157
+ engineering_output = config_convergence["engineering_output"]
3158
+ engineering_current = config_convergence["engineering_current"]
3159
+ if engineering_current != engineering_output:
3160
+ add_action(
3161
+ "config",
3162
+ engineering,
3163
+ "create" if not engineering_current else "replace",
3164
+ "managed default configuration",
1588
3165
  )
1589
- current_cfg, body = _parse_frontmatter_markdown_text(planned_engineering, engineering)
1590
- template_cfg, _ = _read_frontmatter_markdown(template_engineering)
1591
- merged_cfg = json.loads(json.dumps(current_cfg))
1592
- added_keys = _deep_merge_missing(merged_cfg, template_cfg)
1593
- migrated_keys = _migrate_fast_development_defaults(merged_cfg, repo)
1594
- body_migrated = planned_engineering != engineering_plan["original"]
1595
- if added_keys or migrated_keys or body_migrated:
1596
- detail_parts = []
1597
- if added_keys:
1598
- detail_parts.append("add " + ", ".join(added_keys))
1599
- if migrated_keys:
1600
- detail_parts.append("migrate " + ", ".join(migrated_keys))
1601
- if body_migrated:
1602
- detail_parts.append(
1603
- "remove known legacy workflow "
1604
- + ", ".join(item["id"] for item in engineering_plan["migrations"])
1605
- )
1606
- add_action("config", engineering, "merge", "; ".join(detail_parts))
1607
- if write:
1608
- _write_frontmatter_markdown(engineering, merged_cfg, body)
1609
- else:
1610
- add_action("config", engineering, "ok")
1611
- elif template_engineering.exists():
1612
- add_action("config", engineering, "create")
1613
3166
  if write:
1614
- copy_tree(template_engineering, engineering)
1615
- _initialize_engineering_defaults(engineering, repo)
3167
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), engineering_output.encode("utf-8"))
3168
+ else:
3169
+ add_action("config", engineering, "ok")
1616
3170
 
1617
3171
  result = {
1618
3172
  "source_root": str(source_root),
@@ -1794,8 +3348,58 @@ def cmd_check_matrix(args: argparse.Namespace) -> None:
1794
3348
 
1795
3349
 
1796
3350
  def _load_cfg(repo: Path) -> dict:
1797
- cfg_path = find_config(repo)
1798
- return load_yaml(cfg_path)
3351
+ _require_no_install_transaction(repo)
3352
+ return load_effective_config(repo)
3353
+
3354
+
3355
+ def _require_no_install_transaction(repo: Path, *, allow_installer: bool = False) -> None:
3356
+ transaction = repo / _INSTALL_TRANSACTION_RELATIVE
3357
+ if not os.path.lexists(transaction):
3358
+ return
3359
+ if allow_installer:
3360
+ _require_active_install_transaction(repo)
3361
+ return
3362
+ raise APError(
3363
+ "An interrupted auto-coding-skill install transaction requires recovery. "
3364
+ "Run autocoding init or a single-project autocoding sync before using or modifying the project runtime."
3365
+ )
3366
+
3367
+
3368
+ def _require_active_install_transaction(repo: Path) -> dict:
3369
+ transaction = repo / _INSTALL_TRANSACTION_RELATIVE
3370
+ if not os.path.lexists(transaction):
3371
+ raise APError("Internal project mutation requires an active install transaction.")
3372
+ token = os.environ.get("AUTOCODING_INSTALL_TRANSACTION_TOKEN", "")
3373
+ if not re.fullmatch(r"[0-9a-f]{64}", token):
3374
+ raise APError("Internal project mutation requires the active installer token.")
3375
+ owner_payload = _safe_read_project_file(
3376
+ repo,
3377
+ _INSTALL_TRANSACTION_RELATIVE / "owner.json",
3378
+ max_bytes=4096,
3379
+ )
3380
+ state_payload = _safe_read_project_file(
3381
+ repo,
3382
+ _INSTALL_TRANSACTION_RELATIVE / "state.json",
3383
+ max_bytes=64 * 1024,
3384
+ )
3385
+ if owner_payload is None or state_payload is None:
3386
+ raise APError("Internal project mutation requires a complete active install transaction.")
3387
+ try:
3388
+ owner = json.loads(owner_payload.decode("utf-8"))
3389
+ state = json.loads(state_payload.decode("utf-8"))
3390
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
3391
+ raise APError("Active install transaction metadata is invalid.") from exc
3392
+ actual = hashlib.sha256(token.encode("ascii")).hexdigest()
3393
+ owner_hash = _text(_mapping(owner).get("token_sha256"))
3394
+ state_owner_hash = _text(_mapping(state).get("owner_token_sha256"))
3395
+ internal_hash = _text(_mapping(state).get("internal_token_sha256"))
3396
+ if not all(
3397
+ re.fullmatch(r"[0-9a-f]{64}", value)
3398
+ and hmac.compare_digest(value, actual)
3399
+ for value in (owner_hash, state_owner_hash, internal_hash)
3400
+ ):
3401
+ raise APError("Internal project mutation token does not match the active transaction.")
3402
+ return _mapping(state)
1799
3403
 
1800
3404
 
1801
3405
  def _candidate_skill_roots(repo: Path) -> list[Path]:
@@ -2094,9 +3698,8 @@ def _workflow_document_plan(repo: Path, rel: str, policy: dict) -> dict:
2094
3698
  if not match or (_text(rule.get("id")), line) in seen_issues:
2095
3699
  continue
2096
3700
  seen_issues.add((_text(rule.get("id")), line))
2097
- snippet = " ".join(match.group(0).strip().split())[:180]
2098
3701
  message = _text(rule.get("message")) or "conflicts with the fast development workflow"
2099
- issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}: {snippet}")
3702
+ issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}")
2100
3703
 
2101
3704
  output = original
2102
3705
  for start, end, _, _, replacement, match_mode in sorted(known, reverse=True):
@@ -2158,11 +3761,11 @@ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
2158
3761
  issues: list[str] = []
2159
3762
  gate_cfg = cfg.get("gate") or {}
2160
3763
  if not isinstance(gate_cfg, dict):
2161
- return ["docs/ENGINEERING.md frontmatter gate must be a mapping"]
3764
+ return ["effective configuration gate must be a mapping"]
2162
3765
  if "full_on" in gate_cfg:
2163
- issues.append("docs/ENGINEERING.md frontmatter gate.full_on is legacy automatic full escalation; run ap.py upgrade")
3766
+ issues.append("effective configuration gate.full_on is legacy automatic full escalation; run autocoding init")
2164
3767
  if _bool_config(gate_cfg.get("full_on_unknown"), False):
2165
- issues.append("docs/ENGINEERING.md frontmatter gate.full_on_unknown=true is legacy automatic full escalation; run ap.py upgrade")
3768
+ issues.append("effective configuration gate.full_on_unknown=true is legacy automatic full escalation; run autocoding init")
2166
3769
  rules = gate_cfg.get("rules") or []
2167
3770
  if isinstance(rules, list):
2168
3771
  for index, rule in enumerate(rules):
@@ -2171,7 +3774,7 @@ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
2171
3774
  for key in ["scope", "commands"]:
2172
3775
  if key in rule:
2173
3776
  issues.append(
2174
- f"docs/ENGINEERING.md frontmatter gate.rules[{index}].{key} is legacy automatic gate escalation; run ap.py upgrade"
3777
+ f"effective configuration gate.rules[{index}].{key} is legacy automatic gate escalation; run autocoding init"
2175
3778
  )
2176
3779
  return issues
2177
3780
 
@@ -2183,7 +3786,7 @@ def _workflow_policy_issues(repo: Path, cfg: Optional[dict] = None) -> list[str]
2183
3786
  for migration in plan["migrations"]:
2184
3787
  issues.append(
2185
3788
  f"{plan['path']}:{migration['line']} [{migration['id']}] known legacy workflow rule; "
2186
- "run `ap.py upgrade --dry-run` then `ap.py upgrade --write`"
3789
+ "run `autocoding init` or an explicit `autocoding sync`"
2187
3790
  )
2188
3791
  issues.extend(_legacy_gate_config_issues(cfg if cfg is not None else _load_cfg(repo)))
2189
3792
  return issues
@@ -2250,13 +3853,620 @@ def _text(value: object) -> str:
2250
3853
  return str(value or "").strip()
2251
3854
 
2252
3855
 
3856
+ def _feedback_error(path: Path, message: str) -> APError:
3857
+ return APError(f"Invalid Skill feedback report {path}: {message}")
3858
+
3859
+
3860
+ def _feedback_scalar(data: dict, field: str, path: Path) -> str:
3861
+ value = data.get(field)
3862
+ if not isinstance(value, str) or not value.strip():
3863
+ raise _feedback_error(path, f"{field} must be a non-empty string")
3864
+ return value.strip()
3865
+
3866
+
3867
+ def _feedback_timestamp(value: object, path: Path, field: str) -> str:
3868
+ if isinstance(value, _dt.datetime):
3869
+ return value.isoformat()
3870
+ if isinstance(value, _dt.date):
3871
+ return value.isoformat()
3872
+ if not isinstance(value, str) or not value.strip():
3873
+ raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp")
3874
+ raw = value.strip()
3875
+ try:
3876
+ if "T" in raw or " " in raw:
3877
+ _dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
3878
+ else:
3879
+ _dt.date.fromisoformat(raw)
3880
+ except ValueError as exc:
3881
+ raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp") from exc
3882
+ return raw
3883
+
3884
+
3885
+ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3886
+ try:
3887
+ text = payload.decode("utf-8")
3888
+ except UnicodeDecodeError as exc:
3889
+ raise _feedback_error(path, "file must be UTF-8") from exc
3890
+ text = text.replace("\r\n", "\n").replace("\r", "\n")
3891
+ if "\x00" in text:
3892
+ raise _feedback_error(path, "file must be plain Markdown text")
3893
+ if any(pattern.search(text) for pattern in _FEEDBACK_SENSITIVE_PATTERNS):
3894
+ raise _feedback_error(path, "report contains sensitive or machine-specific evidence; redact it")
3895
+ match = re.match(r"^---[ \t]*\n(.*?)\n---[ \t]*(?:\n|$)(.*)$", text, flags=re.DOTALL)
3896
+ if not match:
3897
+ raise _feedback_error(path, "YAML frontmatter is required")
3898
+ try:
3899
+ data = require_yaml().safe_load(match.group(1))
3900
+ except Exception as exc:
3901
+ raise _feedback_error(path, "YAML frontmatter is not safe and valid") from exc
3902
+ if not isinstance(data, dict):
3903
+ raise _feedback_error(path, "YAML frontmatter must be a flat mapping")
3904
+ if any(not isinstance(key, str) for key in data):
3905
+ raise _feedback_error(path, "frontmatter field names must be strings")
3906
+ schema_value = _feedback_scalar(data, "schema", path)
3907
+ if schema_value not in _FEEDBACK_SCHEMAS:
3908
+ raise _feedback_error(path, "schema must be auto-coding-skill-feedback/v1 or /v2")
3909
+ expected_fields = _FEEDBACK_V2_FIELDS if schema_value.endswith("/v2") else _FEEDBACK_V1_FIELDS
3910
+ unknown = sorted(set(data) - set(expected_fields))
3911
+ missing = [field for field in expected_fields if field not in data]
3912
+ if unknown:
3913
+ raise _feedback_error(path, "unknown frontmatter fields are not allowed")
3914
+ if missing:
3915
+ raise _feedback_error(path, f"missing frontmatter fields: {', '.join(missing)}")
3916
+ if any(isinstance(value, (dict, list, tuple, set)) for value in data.values()):
3917
+ raise _feedback_error(path, "frontmatter values must be scalars")
3918
+
3919
+ metadata: dict[str, str] = {}
3920
+ metadata["schema"] = schema_value
3921
+ report_id = _feedback_scalar(data, "report_id", path)
3922
+ if not _FEEDBACK_SAFE_ID_RE.fullmatch(report_id):
3923
+ raise _feedback_error(path, "report_id must be a safe identifier")
3924
+ metadata["report_id"] = report_id
3925
+ status_value = _feedback_scalar(data, "status", path)
3926
+ if status_value not in _FEEDBACK_STATUSES:
3927
+ raise _feedback_error(path, "status is not supported")
3928
+ metadata["status"] = status_value
3929
+ metadata["created_at"] = _feedback_timestamp(data.get("created_at"), path, "created_at")
3930
+ metadata["updated_at"] = (
3931
+ _feedback_timestamp(data.get("updated_at"), path, "updated_at")
3932
+ if schema_value.endswith("/v2")
3933
+ else metadata["created_at"]
3934
+ )
3935
+ project_value = _feedback_scalar(data, "project", path)
3936
+ if not _FEEDBACK_SAFE_ID_RE.fullmatch(project_value):
3937
+ raise _feedback_error(path, "project must be a safe identifier")
3938
+ metadata["project"] = project_value
3939
+ version = _feedback_scalar(data, "observed_skill_version", path)
3940
+ if not _FEEDBACK_SEMVER_RE.fullmatch(version):
3941
+ raise _feedback_error(path, "observed_skill_version must be valid SemVer")
3942
+ metadata["observed_skill_version"] = version
3943
+ if schema_value.endswith("/v2"):
3944
+ last_verified = _feedback_scalar(data, "last_verified_skill_version", path)
3945
+ if not _FEEDBACK_SEMVER_RE.fullmatch(last_verified):
3946
+ raise _feedback_error(path, "last_verified_skill_version must be valid SemVer")
3947
+ else:
3948
+ last_verified = version
3949
+ metadata["last_verified_skill_version"] = last_verified
3950
+ component = _feedback_scalar(data, "component", path)
3951
+ if not _FEEDBACK_SLUG_RE.fullmatch(component):
3952
+ raise _feedback_error(path, "component must be a lowercase kebab-case slug")
3953
+ metadata["component"] = component
3954
+ kind = _feedback_scalar(data, "kind", path)
3955
+ if kind not in _FEEDBACK_KINDS:
3956
+ raise _feedback_error(path, "kind is not supported")
3957
+ metadata["kind"] = kind
3958
+ impact = _feedback_scalar(data, "impact", path)
3959
+ if impact not in _FEEDBACK_IMPACTS:
3960
+ raise _feedback_error(path, "impact is not supported")
3961
+ metadata["impact"] = impact
3962
+ origin_surface = _feedback_scalar(data, "origin_surface", path)
3963
+ if origin_surface not in _FEEDBACK_ORIGIN_SURFACES:
3964
+ raise _feedback_error(path, "origin_surface is not supported")
3965
+ metadata["origin_surface"] = origin_surface
3966
+ suspected_scope = _feedback_scalar(data, "suspected_scope", path)
3967
+ if suspected_scope != "shared":
3968
+ raise _feedback_error(path, "suspected_scope must be shared")
3969
+ metadata["suspected_scope"] = suspected_scope
3970
+ signature = _feedback_scalar(data, "signature", path)
3971
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
3972
+ raise _feedback_error(path, "signature must be sha256 followed by 64 lowercase hex characters")
3973
+ metadata["signature"] = signature
3974
+ if schema_value.endswith("/v2"):
3975
+ resolution = _feedback_scalar(data, "resolution", path)
3976
+ if resolution not in _FEEDBACK_RESOLUTIONS:
3977
+ raise _feedback_error(path, "resolution is not supported")
3978
+ if status_value in _FEEDBACK_ACTIVE_STATUSES and resolution != "pending":
3979
+ raise _feedback_error(path, "active status requires resolution=pending")
3980
+ if status_value == "resolved" and resolution != "fixed":
3981
+ raise _feedback_error(path, "status=resolved requires resolution=fixed")
3982
+ if status_value == "duplicate" and resolution != "duplicate":
3983
+ raise _feedback_error(path, "status=duplicate requires resolution=duplicate")
3984
+ if status_value == "rejected" and resolution not in {
3985
+ "project-config",
3986
+ "environment",
3987
+ "not-shared",
3988
+ "not-reproducible",
3989
+ "wont-fix",
3990
+ }:
3991
+ raise _feedback_error(path, "status=rejected requires a supported rejected resolution")
3992
+ elif status_value in _FEEDBACK_ACTIVE_STATUSES:
3993
+ resolution = "pending"
3994
+ elif status_value == "resolved":
3995
+ resolution = "fixed"
3996
+ elif status_value == "duplicate":
3997
+ resolution = "duplicate"
3998
+ else:
3999
+ resolution = "not-shared"
4000
+ metadata["resolution"] = resolution
4001
+ export_value = _feedback_scalar(data, "export", path)
4002
+ if export_value != "metadata-only":
4003
+ raise _feedback_error(path, "export must be metadata-only")
4004
+ metadata["export"] = export_value
4005
+
4006
+ body_lines = match.group(2).splitlines()
4007
+ titles = [line[2:].strip() for line in body_lines if line.startswith("# ")]
4008
+ if len(titles) != 1 or not titles[0]:
4009
+ raise _feedback_error(path, "body must contain exactly one non-empty level-one title")
4010
+ for heading in _FEEDBACK_HEADINGS:
4011
+ if body_lines.count(f"## {heading}") != 1:
4012
+ raise _feedback_error(path, f"body must contain exactly one '## {heading}' heading")
4013
+ heading_positions = [body_lines.index(f"## {heading}") for heading in _FEEDBACK_HEADINGS]
4014
+ if heading_positions != sorted(heading_positions):
4015
+ raise _feedback_error(path, "body headings must use the canonical order")
4016
+ for index, heading in enumerate(_FEEDBACK_HEADINGS):
4017
+ start = heading_positions[index] + 1
4018
+ end = heading_positions[index + 1] if index + 1 < len(heading_positions) else len(body_lines)
4019
+ if not any(line.strip() for line in body_lines[start:end]):
4020
+ raise _feedback_error(path, f"body section '{heading}' must not be empty")
4021
+ return metadata
4022
+
4023
+
4024
+ def _read_feedback_report(
4025
+ directory_fd: int | Path,
4026
+ name: str,
4027
+ display_path: Path,
4028
+ ) -> tuple[bytes, int, tuple[int, int]]:
4029
+ flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
4030
+ descriptor = -1
4031
+ target = directory_fd / name if isinstance(directory_fd, Path) else None
4032
+ target_identity: tuple[int, int] | None = None
4033
+ try:
4034
+ if target is not None:
4035
+ checked = target.lstat()
4036
+ if _is_windows_reparse_point(checked) or not stat.S_ISREG(checked.st_mode):
4037
+ raise _feedback_error(display_path, "report must be a regular non-symlink file")
4038
+ target_identity = _project_path_identity(checked)
4039
+ descriptor = (
4040
+ os.open(target, flags)
4041
+ if isinstance(directory_fd, Path)
4042
+ else os.open(name, flags, dir_fd=directory_fd)
4043
+ )
4044
+ metadata = os.fstat(descriptor)
4045
+ if (
4046
+ not stat.S_ISREG(metadata.st_mode)
4047
+ or (target_identity is not None and _project_path_identity(metadata) != target_identity)
4048
+ ):
4049
+ raise _feedback_error(display_path, "report must be a regular non-symlink file")
4050
+ if target is not None:
4051
+ checked = target.lstat()
4052
+ if (
4053
+ _is_windows_reparse_point(checked)
4054
+ or not stat.S_ISREG(checked.st_mode)
4055
+ or _project_path_identity(checked) != target_identity
4056
+ ):
4057
+ raise _feedback_error(display_path, "report changed during its safety check")
4058
+ if metadata.st_size > _FEEDBACK_REPORT_MAX_BYTES:
4059
+ raise _feedback_error(display_path, f"report exceeds {_FEEDBACK_REPORT_MAX_BYTES} bytes")
4060
+ with os.fdopen(descriptor, "rb") as handle:
4061
+ descriptor = -1
4062
+ payload = handle.read(_FEEDBACK_REPORT_MAX_BYTES + 1)
4063
+ if target is not None:
4064
+ checked = target.lstat()
4065
+ if (
4066
+ _is_windows_reparse_point(checked)
4067
+ or not stat.S_ISREG(checked.st_mode)
4068
+ or _project_path_identity(checked) != target_identity
4069
+ ):
4070
+ raise _feedback_error(display_path, "report changed while it was read")
4071
+ except APError:
4072
+ raise
4073
+ except OSError as exc:
4074
+ raise _feedback_error(display_path, "report could not be read safely") from exc
4075
+ finally:
4076
+ if descriptor >= 0:
4077
+ os.close(descriptor)
4078
+ if len(payload) > _FEEDBACK_REPORT_MAX_BYTES:
4079
+ raise _feedback_error(display_path, f"report exceeds {_FEEDBACK_REPORT_MAX_BYTES} bytes")
4080
+ return payload, len(payload), (int(metadata.st_dev), int(metadata.st_ino))
4081
+
4082
+
4083
+ def _feedback_project_root(raw: str) -> Path:
4084
+ try:
4085
+ root = Path(raw).expanduser().resolve(strict=True)
4086
+ except OSError as exc:
4087
+ raise APError(f"Skill feedback project does not exist: {raw}") from exc
4088
+ if not root.is_dir():
4089
+ raise APError(f"Skill feedback project is not a directory: {raw}")
4090
+ return root
4091
+
4092
+
4093
+ def _feedback_configured_project(root: Path) -> tuple[str, str]:
4094
+ config = load_effective_config(root)
4095
+ name = _text(_mapping(config.get("project")).get("name"))
4096
+ if not _FEEDBACK_SAFE_ID_RE.fullmatch(name):
4097
+ raise APError("Effective project.name must be a safe non-empty identifier for feedback")
4098
+ version = _text(_mapping(config.get("workflow")).get("skill_version"))
4099
+ if not _FEEDBACK_SEMVER_RE.fullmatch(version):
4100
+ raise APError("Effective workflow.skill_version must be valid SemVer for feedback")
4101
+ return name, version
4102
+
4103
+
4104
+ def _feedback_release_at_least(current: str, required: str) -> bool:
4105
+ def parts(value: str) -> tuple[tuple[int, int, int], bool]:
4106
+ match = re.fullmatch(r"([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([^+]+))?(?:\+.+)?", value)
4107
+ if not match:
4108
+ raise APError("Skill feedback version comparison requires valid SemVer")
4109
+ return tuple(int(match.group(index)) for index in range(1, 4)), bool(match.group(4))
4110
+
4111
+ current_core, current_prerelease = parts(current)
4112
+ required_core, required_prerelease = parts(required)
4113
+ if current_core != required_core:
4114
+ return current_core > required_core
4115
+ if current_prerelease != required_prerelease:
4116
+ return not current_prerelease
4117
+ return current == required or (not current_prerelease and not required_prerelease)
4118
+
4119
+
4120
+ def _load_feedback_resolution_catalog() -> dict[str, dict[str, str]]:
4121
+ path = _skill_root() / _FEEDBACK_RESOLUTION_POLICY
4122
+ try:
4123
+ metadata = path.lstat()
4124
+ except OSError as exc:
4125
+ raise APError("Managed Skill feedback resolution catalog is missing") from exc
4126
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
4127
+ raise APError("Managed Skill feedback resolution catalog must be a regular non-symlink file")
4128
+ if metadata.st_size > _FEEDBACK_RESOLUTION_MAX_BYTES:
4129
+ raise APError("Managed Skill feedback resolution catalog exceeds its size limit")
4130
+ try:
4131
+ payload = path.read_bytes()
4132
+ value = json.loads(payload)
4133
+ except (OSError, json.JSONDecodeError) as exc:
4134
+ raise APError("Managed Skill feedback resolution catalog is invalid") from exc
4135
+ if not isinstance(value, dict) or set(value) != {"schema", "entries"}:
4136
+ raise APError("Managed Skill feedback resolution catalog has an invalid top-level contract")
4137
+ if value.get("schema") != _FEEDBACK_RESOLUTION_SCHEMA or not isinstance(value.get("entries"), list):
4138
+ raise APError("Managed Skill feedback resolution catalog schema is invalid")
4139
+ catalog: dict[str, dict[str, str]] = {}
4140
+ ordered_signatures: list[str] = []
4141
+ for index, raw in enumerate(value["entries"]):
4142
+ if not isinstance(raw, dict):
4143
+ raise APError(f"Managed Skill feedback resolution entry {index} must be an object")
4144
+ allowed = {"signature", "disposition", "effective_skill_version", "canonical_signature"}
4145
+ if set(raw) - allowed or not {"signature", "disposition", "effective_skill_version"}.issubset(raw):
4146
+ raise APError(f"Managed Skill feedback resolution entry {index} has invalid fields")
4147
+ if any(not isinstance(item, str) or not item.strip() for item in raw.values()):
4148
+ raise APError(f"Managed Skill feedback resolution entry {index} values must be non-empty strings")
4149
+ signature = raw["signature"].strip()
4150
+ disposition = raw["disposition"].strip()
4151
+ effective = raw["effective_skill_version"].strip()
4152
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
4153
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid signature")
4154
+ if disposition not in _FEEDBACK_CATALOG_DISPOSITIONS:
4155
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid disposition")
4156
+ if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", effective):
4157
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid release version")
4158
+ canonical = _text(raw.get("canonical_signature"))
4159
+ if disposition == "duplicate":
4160
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(canonical) or canonical == signature:
4161
+ raise APError(f"Managed Skill feedback resolution entry {index} needs a distinct canonical signature")
4162
+ elif canonical:
4163
+ raise APError(f"Managed Skill feedback resolution entry {index} cannot set canonical_signature")
4164
+ if signature in catalog:
4165
+ raise APError("Managed Skill feedback resolution catalog contains duplicate signatures")
4166
+ entry = {
4167
+ "signature": signature,
4168
+ "disposition": disposition,
4169
+ "effective_skill_version": effective,
4170
+ }
4171
+ if canonical:
4172
+ entry["canonical_signature"] = canonical
4173
+ catalog[signature] = entry
4174
+ ordered_signatures.append(signature)
4175
+ if ordered_signatures != sorted(ordered_signatures):
4176
+ raise APError("Managed Skill feedback resolution entries must be sorted by signature")
4177
+ return catalog
4178
+
4179
+
4180
+ def _collect_project_feedback(
4181
+ root: Path,
4182
+ ) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str, str]:
4183
+ reports_relative = Path("docs/skill-feedback/reports")
4184
+ configured_project, installed_skill_version = _feedback_configured_project(root)
4185
+ with _open_project_directory(root, reports_relative) as directory_fd:
4186
+ if directory_fd is None:
4187
+ return [], 0, None, set(), configured_project, installed_skill_version
4188
+ directory_metadata = (
4189
+ directory_fd.stat() if isinstance(directory_fd, Path) else os.fstat(directory_fd)
4190
+ )
4191
+ directory_identity = (int(directory_metadata.st_dev), int(directory_metadata.st_ino))
4192
+ try:
4193
+ entries = os.listdir(directory_fd)
4194
+ except OSError as exc:
4195
+ raise APError("Cannot list Skill feedback reports safely") from exc
4196
+ if len(entries) > _FEEDBACK_PROJECT_MAX_ENTRIES:
4197
+ raise APError(
4198
+ f"Skill feedback directory exceeds {_FEEDBACK_PROJECT_MAX_ENTRIES} entries"
4199
+ )
4200
+ candidates: list[str] = []
4201
+ for name in entries:
4202
+ if not name.endswith(".md"):
4203
+ continue
4204
+ if not _FEEDBACK_FILENAME_RE.fullmatch(name):
4205
+ raise APError("Skill feedback directory contains an invalid Markdown filename")
4206
+ try:
4207
+ metadata = (
4208
+ (directory_fd / name).stat(follow_symlinks=False)
4209
+ if isinstance(directory_fd, Path)
4210
+ else os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
4211
+ )
4212
+ except OSError as exc:
4213
+ raise APError("Cannot inspect Skill feedback report safely") from exc
4214
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
4215
+ raise APError(f"Skill feedback report must be a regular non-symlink file: {name}")
4216
+ candidates.append(name)
4217
+ candidates.sort()
4218
+ if len(candidates) > _FEEDBACK_PROJECT_MAX_REPORTS:
4219
+ raise APError(
4220
+ f"Skill feedback project exceeds {_FEEDBACK_PROJECT_MAX_REPORTS} reports"
4221
+ )
4222
+
4223
+ reports: list[dict] = []
4224
+ total_bytes = 0
4225
+ file_identities: set[tuple[int, int]] = set()
4226
+ for name in candidates:
4227
+ display_path = reports_relative / name
4228
+ payload, size, file_identity = _read_feedback_report(directory_fd, name, display_path)
4229
+ if file_identity in file_identities:
4230
+ raise APError("Skill feedback project contains duplicate physical report files")
4231
+ file_identities.add(file_identity)
4232
+ report = _parse_feedback_report(payload, display_path)
4233
+ if report["project"] != configured_project:
4234
+ raise _feedback_error(
4235
+ display_path,
4236
+ "project must equal effective project.name",
4237
+ )
4238
+ report["source_path"] = display_path.as_posix()
4239
+ report["size_bytes"] = size
4240
+ reports.append(report)
4241
+ total_bytes += size
4242
+ return (
4243
+ reports,
4244
+ total_bytes,
4245
+ directory_identity,
4246
+ file_identities,
4247
+ configured_project,
4248
+ installed_skill_version,
4249
+ )
4250
+
4251
+
4252
+ def _feedback_lifecycle(
4253
+ report: dict,
4254
+ installed_skill_version: str,
4255
+ catalog: dict[str, dict[str, str]],
4256
+ ) -> tuple[str, str, dict[str, str] | None]:
4257
+ if report["status"] not in _FEEDBACK_ACTIVE_STATUSES:
4258
+ return "closed", "none", catalog.get(report["signature"])
4259
+ catalog_entry = catalog.get(report["signature"])
4260
+ if catalog_entry:
4261
+ effective = catalog_entry["effective_skill_version"]
4262
+ if not _feedback_release_at_least(installed_skill_version, effective):
4263
+ return "upgrade-due", "upgrade-project-then-verify", catalog_entry
4264
+ disposition = catalog_entry["disposition"]
4265
+ if disposition == "fixed":
4266
+ if report["last_verified_skill_version"] == installed_skill_version:
4267
+ return "regression-current", "none", catalog_entry
4268
+ if _feedback_release_at_least(report["last_verified_skill_version"], effective):
4269
+ return (
4270
+ "recheck-due",
4271
+ "reproduce-on-installed-version-and-update-or-close",
4272
+ catalog_entry,
4273
+ )
4274
+ return "verification-due", "verify-fix-then-resolve-or-delete", catalog_entry
4275
+ if disposition == "project-config":
4276
+ return (
4277
+ "reroute-due",
4278
+ "move-to-docs/project/auto-coding-skill.yaml-then-reject-or-delete",
4279
+ catalog_entry,
4280
+ )
4281
+ return "closure-due", "update-closed-status-or-delete", catalog_entry
4282
+ if report["last_verified_skill_version"] != installed_skill_version:
4283
+ return "recheck-due", "reproduce-on-installed-version-and-update-or-close", None
4284
+ return "active-current", "none", None
4285
+
4286
+
4287
+ def _feedback_groups(reports: list[dict]) -> list[dict]:
4288
+ grouped: dict[str, list[dict]] = {}
4289
+ for report in reports:
4290
+ grouped.setdefault(report["signature"], []).append(report)
4291
+ groups: list[dict] = []
4292
+ for signature, items in sorted(grouped.items()):
4293
+ projects = sorted({item["project"] for item in items})
4294
+ group_source_projects = sorted({item["source_project"] for item in items})
4295
+ groups.append(
4296
+ {
4297
+ "signature": signature,
4298
+ "report_count": len(items),
4299
+ "project_count": len(group_source_projects),
4300
+ "projects": projects,
4301
+ "source_projects": group_source_projects,
4302
+ "report_ids": [item["report_id"] for item in items],
4303
+ "cross_project": len(group_source_projects) > 1,
4304
+ }
4305
+ )
4306
+ return groups
4307
+
4308
+
4309
+ def _feedback_collection_result(raw_projects: list[str]) -> dict:
4310
+ if not raw_projects:
4311
+ raise APError("feedback-collect requires at least one explicit --project")
4312
+ catalog = _load_feedback_resolution_catalog()
4313
+ roots: list[Path] = []
4314
+ seen_roots: set[str] = set()
4315
+ for raw in raw_projects:
4316
+ root = _feedback_project_root(raw)
4317
+ key = str(root)
4318
+ if key not in seen_roots:
4319
+ seen_roots.add(key)
4320
+ roots.append(root)
4321
+ if len(roots) > _FEEDBACK_COLLECTION_MAX_PROJECTS:
4322
+ raise APError(
4323
+ f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_PROJECTS} projects"
4324
+ )
4325
+
4326
+ reports: list[dict] = []
4327
+ total_bytes = 0
4328
+ source_projects: list[dict[str, str]] = []
4329
+ seen_report_directories: set[tuple[int, int]] = set()
4330
+ seen_report_files: set[tuple[int, int]] = set()
4331
+ seen_configured_projects: set[str] = set()
4332
+ for index, root in enumerate(roots, start=1):
4333
+ source_id = f"project-{index}"
4334
+ (
4335
+ project_reports,
4336
+ project_bytes,
4337
+ directory_identity,
4338
+ file_identities,
4339
+ configured_project,
4340
+ installed_skill_version,
4341
+ ) = _collect_project_feedback(root)
4342
+ if directory_identity is not None:
4343
+ if directory_identity in seen_report_directories:
4344
+ raise APError("Explicit projects resolve to the same Skill feedback report directory")
4345
+ seen_report_directories.add(directory_identity)
4346
+ if seen_report_files.intersection(file_identities):
4347
+ raise APError("Explicit projects contain the same physical Skill feedback report file")
4348
+ seen_report_files.update(file_identities)
4349
+ if configured_project in seen_configured_projects:
4350
+ raise APError("Explicit projects must have distinct effective project.name values")
4351
+ seen_configured_projects.add(configured_project)
4352
+ source_descriptor = {
4353
+ "source_project": source_id,
4354
+ "project": configured_project,
4355
+ "skill_version": installed_skill_version,
4356
+ }
4357
+ source_projects.append(source_descriptor)
4358
+ total_bytes += project_bytes
4359
+ if total_bytes > _FEEDBACK_COLLECTION_MAX_BYTES:
4360
+ raise APError(
4361
+ f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_BYTES} bytes"
4362
+ )
4363
+ if len(reports) + len(project_reports) > _FEEDBACK_COLLECTION_MAX_REPORTS:
4364
+ raise APError(
4365
+ f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_REPORTS} reports"
4366
+ )
4367
+ for report in project_reports:
4368
+ report["source_project"] = source_id
4369
+ report["installed_skill_version"] = installed_skill_version
4370
+ lifecycle, recommended_action, catalog_entry = _feedback_lifecycle(
4371
+ report,
4372
+ installed_skill_version,
4373
+ catalog,
4374
+ )
4375
+ report["lifecycle"] = lifecycle
4376
+ report["recommended_action"] = recommended_action
4377
+ if catalog_entry:
4378
+ report["catalog_disposition"] = catalog_entry["disposition"]
4379
+ report["catalog_effective_skill_version"] = catalog_entry["effective_skill_version"]
4380
+ if catalog_entry.get("canonical_signature"):
4381
+ report["catalog_canonical_signature"] = catalog_entry["canonical_signature"]
4382
+ reports.extend(project_reports)
4383
+
4384
+ reports.sort(key=lambda item: (item["signature"], item["project"], item["report_id"], item["source_path"]))
4385
+ triage_reports = [
4386
+ report
4387
+ for report in reports
4388
+ if report["lifecycle"] in {"active-current", "regression-current"}
4389
+ ]
4390
+ groups = _feedback_groups(triage_reports)
4391
+ cross_project = [group for group in groups if group["cross_project"]]
4392
+ lifecycle_counts = {
4393
+ lifecycle: sum(1 for report in reports if report["lifecycle"] == lifecycle)
4394
+ for lifecycle in sorted({report["lifecycle"] for report in reports})
4395
+ }
4396
+ action_required = [
4397
+ {
4398
+ key: report[key]
4399
+ for key in (
4400
+ "source_project",
4401
+ "project",
4402
+ "report_id",
4403
+ "source_path",
4404
+ "signature",
4405
+ "installed_skill_version",
4406
+ "last_verified_skill_version",
4407
+ "lifecycle",
4408
+ "recommended_action",
4409
+ "catalog_disposition",
4410
+ "catalog_effective_skill_version",
4411
+ "catalog_canonical_signature",
4412
+ )
4413
+ if key in report
4414
+ }
4415
+ for report in reports
4416
+ if report["recommended_action"] != "none"
4417
+ ]
4418
+ return {
4419
+ "schema": _FEEDBACK_COLLECTION_SCHEMA,
4420
+ "projects": source_projects,
4421
+ "report_count": len(reports),
4422
+ "active_report_count": len(triage_reports),
4423
+ "closed_report_count": lifecycle_counts.get("closed", 0),
4424
+ "action_required_count": len(action_required),
4425
+ "total_bytes": total_bytes,
4426
+ "lifecycle_counts": lifecycle_counts,
4427
+ "action_required": action_required,
4428
+ "metadata": reports,
4429
+ "groups": groups,
4430
+ "cross_project": cross_project,
4431
+ }
4432
+
4433
+
4434
+ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4435
+ raw_projects = list(args.project or [])
4436
+ result = _feedback_collection_result(raw_projects)
4437
+ if args.json:
4438
+ print(json.dumps(result, ensure_ascii=False, indent=2))
4439
+ return
4440
+ print(
4441
+ f"[feedback-collect] projects={len(result['projects'])} reports={result['report_count']} "
4442
+ f"active={result['active_report_count']} closed={result['closed_report_count']} "
4443
+ f"actions={result['action_required_count']} groups={len(result['groups'])} "
4444
+ f"cross_project={len(result['cross_project'])} bytes={result['total_bytes']}"
4445
+ )
4446
+ for item in result["action_required"]:
4447
+ print(
4448
+ f"[feedback-collect] action={item['recommended_action']} "
4449
+ f"project={item['project']} report={item['report_id']} lifecycle={item['lifecycle']}"
4450
+ )
4451
+ for group in result["groups"]:
4452
+ print(
4453
+ f"[feedback-collect] signature={group['signature']} "
4454
+ f"cross_project={str(group['cross_project']).lower()} "
4455
+ f"projects={','.join(group['projects'])} reports={','.join(group['report_ids'])}"
4456
+ )
4457
+
4458
+
2253
4459
  _TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
2254
4460
  _DIRECT_CLAIM_ID_RE = re.compile(r"^[0-9a-f]{32}$")
2255
4461
 
2256
4462
 
2257
4463
  def _concurrency_cfg(cfg: dict) -> dict:
2258
- value = cfg.get("concurrency") or {}
2259
- return value if isinstance(value, dict) else {}
4464
+ value = cfg.get("concurrency")
4465
+ if value is None:
4466
+ return {}
4467
+ if not isinstance(value, dict):
4468
+ raise APError("concurrency must be a mapping")
4469
+ return value
2260
4470
 
2261
4471
 
2262
4472
  def _task_isolation(cfg: dict) -> str:
@@ -3948,6 +6158,7 @@ _DEFAULT_FULL_PATH_PATTERNS = [
3948
6158
  "compose*.yml",
3949
6159
  "compose*.yaml",
3950
6160
  "docs/ENGINEERING.md",
6161
+ _PROJECT_CONFIG_RELATIVE.as_posix(),
3951
6162
  "docs/tools/autopipeline/**",
3952
6163
  "package.json",
3953
6164
  "**/package.json",
@@ -3967,18 +6178,30 @@ _DEFAULT_FULL_PATH_PATTERNS = [
3967
6178
 
3968
6179
 
3969
6180
  def _gate_cfg(cfg: dict) -> dict:
3970
- gate_cfg = cfg.get("gate") or {}
3971
- return gate_cfg if isinstance(gate_cfg, dict) else {}
6181
+ gate_cfg = cfg.get("gate")
6182
+ if gate_cfg is None:
6183
+ return {}
6184
+ if not isinstance(gate_cfg, dict):
6185
+ raise APError("gate must be a mapping")
6186
+ return gate_cfg
3972
6187
 
3973
6188
 
3974
6189
  def _risk_cfg(cfg: dict) -> dict:
3975
- value = cfg.get("risk") or {}
3976
- return value if isinstance(value, dict) else {}
6190
+ value = cfg.get("risk")
6191
+ if value is None:
6192
+ return {}
6193
+ if not isinstance(value, dict):
6194
+ raise APError("risk must be a mapping")
6195
+ return value
3977
6196
 
3978
6197
 
3979
6198
  def _validation_cfg(cfg: dict) -> dict:
3980
- value = cfg.get("validation") or {}
3981
- return value if isinstance(value, dict) else {}
6199
+ value = cfg.get("validation")
6200
+ if value is None:
6201
+ return {}
6202
+ if not isinstance(value, dict):
6203
+ raise APError("validation must be a mapping")
6204
+ return value
3982
6205
 
3983
6206
 
3984
6207
  def _positive_seconds(value: object, default: float, label: str) -> float:
@@ -4185,7 +6408,11 @@ def _cleanup_generated_noise(repo: Path, protected_paths: Optional[set[str]] = N
4185
6408
 
4186
6409
 
4187
6410
  def _docs_only(paths: list[str]) -> bool:
4188
- return bool(paths) and all(_path_matches(path, _DOC_PATH_PATTERNS) for path in paths)
6411
+ return bool(paths) and all(
6412
+ path not in _EFFECTIVE_CONFIG_PATHS
6413
+ and _path_matches(path, _DOC_PATH_PATTERNS)
6414
+ for path in paths
6415
+ )
4189
6416
 
4190
6417
 
4191
6418
  def _tests_only(paths: list[str]) -> bool:
@@ -4199,13 +6426,46 @@ def _tests_only(paths: list[str]) -> bool:
4199
6426
 
4200
6427
 
4201
6428
  def _gate_rules(gate_cfg: dict) -> list[dict]:
4202
- rules = gate_cfg.get("rules") or []
4203
- return [rule for rule in rules if isinstance(rule, dict)]
6429
+ rules = gate_cfg.get("rules", [])
6430
+ if not isinstance(rules, list):
6431
+ raise APError("gate.rules must be a list")
6432
+ validated: list[dict] = []
6433
+ for index, rule in enumerate(rules):
6434
+ if not isinstance(rule, dict):
6435
+ raise APError(f"gate.rules[{index}] must be a mapping")
6436
+ profile = _text(rule.get("profile")).lower()
6437
+ if profile and profile not in _WORKFLOW_PROFILES - {"auto"}:
6438
+ raise APError(
6439
+ f"gate.rules[{index}].profile must be micro, standard, or high-risk"
6440
+ )
6441
+ if "scope" in rule:
6442
+ raise APError(
6443
+ f"gate.rules[{index}].scope is legacy automatic gate escalation; run autocoding init"
6444
+ )
6445
+ if "commands" in rule:
6446
+ raise APError(
6447
+ f"gate.rules[{index}].commands is legacy automatic gate escalation; run autocoding init"
6448
+ )
6449
+ validated.append(rule)
6450
+ return validated
4204
6451
 
4205
6452
 
4206
6453
  def _risk_rules(cfg: dict) -> list[dict]:
4207
- rules = _risk_cfg(cfg).get("rules") or []
4208
- current = [rule for rule in rules if isinstance(rule, dict)]
6454
+ rules = _risk_cfg(cfg).get("rules", [])
6455
+ if not isinstance(rules, list):
6456
+ raise APError("risk.rules must be a list")
6457
+ current: list[dict] = []
6458
+ for index, rule in enumerate(rules):
6459
+ if not isinstance(rule, dict):
6460
+ raise APError(f"risk.rules[{index}] must be a mapping")
6461
+ if not _as_list(rule.get("paths")):
6462
+ raise APError(f"risk.rules[{index}].paths must not be empty")
6463
+ profile = _text(rule.get("profile")).lower()
6464
+ if profile and profile not in _WORKFLOW_PROFILES - {"auto"}:
6465
+ raise APError(
6466
+ f"risk.rules[{index}].profile must be micro, standard, or high-risk"
6467
+ )
6468
+ current.append(rule)
4209
6469
  # Keep reading 3.x gate.rules while projects migrate. They remain planning
4210
6470
  # metadata only and never execute validation commands.
4211
6471
  return current or _gate_rules(_gate_cfg(cfg))
@@ -4230,8 +6490,19 @@ def _matching_risk_rules(paths: list[str], cfg: dict) -> list[dict]:
4230
6490
 
4231
6491
 
4232
6492
  def _validation_routes(cfg: dict) -> list[dict]:
4233
- routes = _validation_cfg(cfg).get("routes") or []
4234
- return [route for route in routes if isinstance(route, dict)]
6493
+ routes = _validation_cfg(cfg).get("routes", [])
6494
+ if not isinstance(routes, list):
6495
+ raise APError("validation.routes must be a list")
6496
+ validated: list[dict] = []
6497
+ for index, route in enumerate(routes):
6498
+ if not isinstance(route, dict):
6499
+ raise APError(f"validation.routes[{index}] must be a mapping")
6500
+ if not _as_list(route.get("paths")):
6501
+ raise APError(f"validation.routes[{index}].paths must not be empty")
6502
+ if not [_command_name(item) for item in _as_list(route.get("commands"))]:
6503
+ raise APError(f"validation.routes[{index}].commands must not be empty")
6504
+ validated.append(route)
6505
+ return validated
4235
6506
 
4236
6507
 
4237
6508
  def _validation_route_matches(path: str, route: dict) -> bool:
@@ -4253,11 +6524,19 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
4253
6524
  command_names: list[str] = []
4254
6525
  command_timeouts: dict[str, float] = {}
4255
6526
  matched_routes: list[str] = []
6527
+ builtins: list[str] = []
4256
6528
  coverage: dict[str, list[str]] = {}
4257
6529
  unmapped: list[str] = []
4258
6530
 
4259
6531
  for path in normalized:
4260
6532
  names: list[str] = []
6533
+ if path in _EFFECTIVE_CONFIG_PATHS:
6534
+ builtin_name = "effective-config"
6535
+ names.append(builtin_name)
6536
+ if builtin_name not in builtins:
6537
+ builtins.append(builtin_name)
6538
+ if builtin_name not in matched_routes:
6539
+ matched_routes.append(builtin_name)
4261
6540
  for index, route in enumerate(routes):
4262
6541
  if not _validation_route_matches(path, route):
4263
6542
  continue
@@ -4289,7 +6568,13 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
4289
6568
 
4290
6569
  validation_cfg = _validation_cfg(cfg)
4291
6570
  compatibility_command = ""
4292
- if not routes:
6571
+ project_validation_paths = [
6572
+ path
6573
+ for path in normalized
6574
+ if path not in _EFFECTIVE_CONFIG_PATHS
6575
+ and not _path_matches(path, _DOC_PATH_PATTERNS)
6576
+ ]
6577
+ if not routes and project_validation_paths:
4293
6578
  compatibility_command = _command_name(validation_cfg.get("fallback_command"))
4294
6579
  if not compatibility_command and _configured_command(cfg, "gate_changed"):
4295
6580
  compatibility_command = "gate_changed"
@@ -4313,6 +6598,7 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
4313
6598
  "commands": command_names,
4314
6599
  "command_timeouts": command_timeouts,
4315
6600
  "matched_routes": matched_routes,
6601
+ "builtins": builtins,
4316
6602
  "coverage": coverage,
4317
6603
  "unmapped": unmapped,
4318
6604
  "docs_only": _docs_only(normalized),
@@ -4328,9 +6614,9 @@ def _validate_validation_plan(cfg: dict, plan: dict) -> None:
4328
6614
  raise APError(
4329
6615
  "Changed code paths have no validation route:\n- "
4330
6616
  + "\n- ".join(plan["unmapped"])
4331
- + "\nAdd validation.routes entries in docs/ENGINEERING.md."
6617
+ + "\nAdd validation.routes entries in docs/project/auto-coding-skill.yaml."
4332
6618
  )
4333
- if plan["paths"] and not plan["docs_only"] and not plan["commands"]:
6619
+ if plan["paths"] and not plan["docs_only"] and not plan["commands"] and not plan["builtins"]:
4334
6620
  raise APError(
4335
6621
  "Changed code has no fast validation command. Add validation.routes with project-native commands."
4336
6622
  )
@@ -4448,6 +6734,14 @@ def _run_changed_gate(
4448
6734
  deadline: Optional[float] = None,
4449
6735
  command_timeout_s: Optional[float] = None,
4450
6736
  ) -> list[str]:
6737
+ contract = cmd_doctor(
6738
+ argparse.Namespace(repo=str(repo), collect=True, quiet=True, record=False)
6739
+ )
6740
+ if contract["issues"]:
6741
+ raise APError(
6742
+ "Effective project configuration contract is invalid:\n- "
6743
+ + "\n- ".join(contract["issues"])
6744
+ )
4451
6745
  plan = _validation_plan(cfg, paths)
4452
6746
  _validate_validation_plan(cfg, plan)
4453
6747
  if not paths:
@@ -4461,14 +6755,17 @@ def _run_changed_gate(
4461
6755
  "[validation] WARN: using 3.x compatibility fallback; migrate to validation.routes",
4462
6756
  file=sys.stderr,
4463
6757
  )
4464
- executed = _run_configured_command_list(
6758
+ executed = list(plan["builtins"])
6759
+ if plan["builtins"]:
6760
+ print("[validation] effective project configuration contract is valid")
6761
+ executed.extend(_run_configured_command_list(
4465
6762
  repo,
4466
6763
  cfg,
4467
6764
  plan["commands"],
4468
6765
  deadline=deadline,
4469
6766
  command_timeout_s=command_timeout_s,
4470
6767
  command_timeouts=plan["command_timeouts"],
4471
- )
6768
+ ))
4472
6769
  print(
4473
6770
  "[validation] routes="
4474
6771
  + (", ".join(plan["matched_routes"]) or "(none)")
@@ -4495,6 +6792,7 @@ def cmd_validation_map_check(args: argparse.Namespace) -> None:
4495
6792
  "commands": plan["commands"],
4496
6793
  "command_timeouts": plan["command_timeouts"],
4497
6794
  "matched_routes": plan["matched_routes"],
6795
+ "builtins": plan["builtins"],
4498
6796
  "coverage": plan["coverage"],
4499
6797
  "docs_only": plan["docs_only"],
4500
6798
  }
@@ -4711,18 +7009,30 @@ _DEFAULT_LAYER_RULES = {
4711
7009
 
4712
7010
 
4713
7011
  def _structure_cfg(cfg: dict) -> dict:
4714
- value = cfg.get("structure") or {}
4715
- return value if isinstance(value, dict) else {}
7012
+ value = cfg.get("structure")
7013
+ if value is None:
7014
+ return {}
7015
+ if not isinstance(value, dict):
7016
+ raise APError("structure must be a mapping")
7017
+ return value
4716
7018
 
4717
7019
 
4718
7020
  def _optimization_cfg(cfg: dict) -> dict:
4719
- value = cfg.get("optimization") or {}
4720
- return value if isinstance(value, dict) else {}
7021
+ value = cfg.get("optimization")
7022
+ if value is None:
7023
+ return {}
7024
+ if not isinstance(value, dict):
7025
+ raise APError("optimization must be a mapping")
7026
+ return value
4721
7027
 
4722
7028
 
4723
7029
  def _verification_cfg(cfg: dict) -> dict:
4724
- value = cfg.get("verification") or {}
4725
- return value if isinstance(value, dict) else {}
7030
+ value = cfg.get("verification")
7031
+ if value is None:
7032
+ return {}
7033
+ if not isinstance(value, dict):
7034
+ raise APError("verification must be a mapping")
7035
+ return value
4726
7036
 
4727
7037
 
4728
7038
  def _bool_config(value: object, default: bool = False) -> bool:
@@ -6582,14 +8892,24 @@ def _render_optimization_backlog(inventory: dict) -> str:
6582
8892
  def _update_accepted_debt_paths(repo: Path, cfg: dict, paths: list[str]) -> list[str]:
6583
8893
  if not paths:
6584
8894
  return []
6585
- engineering = find_config(repo)
6586
- current_cfg, body = _read_frontmatter_markdown(engineering)
6587
- structure_cfg = current_cfg.setdefault("structure", {})
6588
- existing = [str(item) for item in _as_list(structure_cfg.get("accepted_debt_paths")) if str(item).strip()]
8895
+ overrides = json.loads(json.dumps(load_project_overrides(repo)))
8896
+ effective_structure = _mapping(cfg.get("structure"))
8897
+ existing = [
8898
+ str(item)
8899
+ for item in _as_list(effective_structure.get("accepted_debt_paths"))
8900
+ if str(item).strip()
8901
+ ]
6589
8902
  added = [path for path in paths if path not in existing]
6590
8903
  if added:
8904
+ structure_cfg = overrides.setdefault("structure", {})
8905
+ if not isinstance(structure_cfg, dict):
8906
+ raise APError("Project structure override must be a mapping")
6591
8907
  structure_cfg["accepted_debt_paths"] = existing + added
6592
- _write_frontmatter_markdown(engineering, current_cfg, body)
8908
+ overlay_payload = _render_project_overlay(overrides)
8909
+ if _safe_read_project_file(repo, _PROJECT_CONFIG_RELATIVE) is None:
8910
+ _safe_create_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay_payload)
8911
+ else:
8912
+ _safe_write_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay_payload)
6593
8913
  return added
6594
8914
 
6595
8915
 
@@ -6624,7 +8944,7 @@ def cmd_baseline_init(args: argparse.Namespace) -> None:
6624
8944
  accepted_added = _update_accepted_debt_paths(repo, cfg, accepted_paths)
6625
8945
  if accepted_added:
6626
8946
  actions.append({
6627
- "path": "docs/ENGINEERING.md",
8947
+ "path": _PROJECT_CONFIG_RELATIVE.as_posix(),
6628
8948
  "action": "merge",
6629
8949
  "kind": "accepted_debt_paths",
6630
8950
  "detail": ", ".join(accepted_added),
@@ -8627,7 +10947,7 @@ def cmd_agent_result_template(args: argparse.Namespace) -> None:
8627
10947
  def cmd_run(args: argparse.Namespace) -> None:
8628
10948
  """
8629
10949
  Run any configured gate command by name.
8630
- Commands are read from docs/ENGINEERING.md frontmatter.
10950
+ Commands are read from the effective managed-default plus project-overlay configuration.
8631
10951
  """
8632
10952
  repo = Path(args.repo).resolve()
8633
10953
  cfg = _load_cfg(repo)
@@ -8636,12 +10956,12 @@ def cmd_run(args: argparse.Namespace) -> None:
8636
10956
  if name not in commands:
8637
10957
  raise APError(
8638
10958
  f"Command not configured: commands.{name}. "
8639
- "Edit docs/ENGINEERING.md frontmatter. "
10959
+ "Edit docs/project/auto-coding-skill.yaml. "
8640
10960
  f"Available: {', '.join(commands.keys()) or '(none)'}"
8641
10961
  )
8642
10962
  cmd = str(commands.get(name) or "").strip()
8643
10963
  if not cmd:
8644
- raise APError(f"Command is blank: commands.{name}. Edit docs/ENGINEERING.md frontmatter.")
10964
+ raise APError(f"Command is blank: commands.{name}. Edit docs/project/auto-coding-skill.yaml.")
8645
10965
  print(f"[run] {name}: {cmd}")
8646
10966
  run_shell(cmd, cwd=repo)
8647
10967
  print(f"[run] OK: {name}")
@@ -8961,9 +11281,12 @@ def cmd_verify_jenkins(args: argparse.Namespace) -> None:
8961
11281
  print(f"[verify-jenkins] OK: {jenkinsfile}")
8962
11282
 
8963
11283
 
8964
- def cmd_doctor(args: argparse.Namespace) -> None:
11284
+ def cmd_doctor(args: argparse.Namespace) -> dict | None:
8965
11285
  repo = Path(args.repo).resolve()
8966
11286
  cfg = _load_cfg(repo)
11287
+ collect = bool(getattr(args, "collect", False))
11288
+ quiet = bool(getattr(args, "quiet", False))
11289
+ record = bool(getattr(args, "record", True))
8967
11290
  workflow_cfg = (cfg.get("workflow") or {})
8968
11291
  project_cfg = (cfg.get("project") or {})
8969
11292
  docs_cfg = (cfg.get("docs") or {})
@@ -8976,9 +11299,18 @@ def cmd_doctor(args: argparse.Namespace) -> None:
8976
11299
  advisories: List[str] = []
8977
11300
  validation_errors.extend(_workflow_policy_issues(repo, cfg))
8978
11301
 
8979
- mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
8980
- profile = str(workflow_cfg.get("profile") or "auto").strip().lower()
8981
- completion = str(workflow_cfg.get("completion") or "").strip().lower()
11302
+ raw_mode = workflow_cfg.get("mode", "dev")
11303
+ raw_profile = workflow_cfg.get("profile", "auto")
11304
+ raw_completion = workflow_cfg.get("completion", "")
11305
+ if not isinstance(raw_mode, str):
11306
+ validation_errors.append("workflow.mode must be a string")
11307
+ if not isinstance(raw_profile, str):
11308
+ validation_errors.append("workflow.profile must be a string")
11309
+ if not isinstance(raw_completion, str):
11310
+ validation_errors.append("workflow.completion must be a string")
11311
+ mode = raw_mode.strip().lower() if isinstance(raw_mode, str) else ""
11312
+ profile = raw_profile.strip().lower() if isinstance(raw_profile, str) else ""
11313
+ completion = raw_completion.strip().lower() if isinstance(raw_completion, str) else ""
8982
11314
  skill_version = _text(workflow_cfg.get("skill_version"))
8983
11315
  if mode != "dev":
8984
11316
  missing.append("workflow.mode (must be dev; external verification is owner-managed)")
@@ -8988,24 +11320,42 @@ def cmd_doctor(args: argparse.Namespace) -> None:
8988
11320
  missing.append("workflow.completion (must be push)")
8989
11321
  if skill_version.startswith("4.1") and _text(docs_cfg.get("framework")) != "engineering-centered":
8990
11322
  missing.append("docs.framework (must be engineering-centered for auto-coding-skill 4.1)")
8991
- isolation = _text(concurrency_cfg.get("isolation")).lower() or "adaptive"
8992
- if isolation not in {"adaptive", "worktree"}:
11323
+ raw_isolation = concurrency_cfg.get("isolation", "adaptive")
11324
+ if not isinstance(raw_isolation, str):
11325
+ validation_errors.append("concurrency.isolation must be a string")
11326
+ isolation = ""
11327
+ else:
11328
+ isolation = raw_isolation.strip().lower() or "adaptive"
11329
+ if isolation and isolation not in {"adaptive", "worktree"}:
8993
11330
  validation_errors.append(
8994
11331
  "concurrency.isolation must be adaptive or worktree; legacy shared-checkout mode is unsupported"
8995
11332
  )
8996
- branch_prefix = _text(concurrency_cfg.get("branch_prefix")) or "codex/"
8997
- if not branch_prefix.endswith("/"):
11333
+ raw_branch_prefix = concurrency_cfg.get("branch_prefix", "codex/")
11334
+ if not isinstance(raw_branch_prefix, str):
11335
+ validation_errors.append("concurrency.branch_prefix must be a string")
11336
+ branch_prefix = ""
11337
+ else:
11338
+ branch_prefix = raw_branch_prefix.strip() or "codex/"
11339
+ if branch_prefix and not branch_prefix.endswith("/"):
8998
11340
  validation_errors.append("concurrency.branch_prefix must end with '/'")
8999
- elif run(
11341
+ elif branch_prefix and run(
9000
11342
  ["git", "check-ref-format", "--branch", f"{branch_prefix}TASK"],
9001
11343
  cwd=repo,
9002
11344
  check=False,
9003
11345
  ).returncode != 0:
9004
11346
  validation_errors.append("concurrency.branch_prefix does not form a valid Git branch")
9005
- if not str(project_cfg.get("name") or "").strip():
11347
+ raw_project_name = project_cfg.get("name")
11348
+ if raw_project_name is not None and not isinstance(raw_project_name, str):
11349
+ validation_errors.append("project.name must be a string")
11350
+ if not isinstance(raw_project_name, str) or not raw_project_name.strip():
9006
11351
  missing.append("project.name")
9007
11352
  missing.extend(_access_config_issues(cfg))
9008
- enforcement = _text(structure_cfg.get("enforcement")).lower()
11353
+ raw_enforcement = structure_cfg.get("enforcement")
11354
+ if raw_enforcement is not None and not isinstance(raw_enforcement, str):
11355
+ validation_errors.append("structure.enforcement must be a string")
11356
+ enforcement = ""
11357
+ else:
11358
+ enforcement = raw_enforcement.strip().lower() if isinstance(raw_enforcement, str) else ""
9009
11359
  if enforcement and enforcement not in {"advisory", "blocking"}:
9010
11360
  validation_errors.append("structure.enforcement must be advisory or blocking")
9011
11361
  raw_block_warnings = structure_cfg.get("block_warnings")
@@ -9017,7 +11367,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9017
11367
  )
9018
11368
  gate_cfg = _gate_cfg(cfg)
9019
11369
  if "full_on" in gate_cfg:
9020
- validation_errors.append("gate.full_on is legacy automatic full escalation; run ap.py upgrade")
11370
+ validation_errors.append("gate.full_on is legacy automatic full escalation; run autocoding init")
9021
11371
  raw_rules = gate_cfg.get("rules") or []
9022
11372
  rules_valid = isinstance(raw_rules, list)
9023
11373
  if not rules_valid:
@@ -9038,12 +11388,12 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9038
11388
  if "scope" in rule:
9039
11389
  rules_valid = False
9040
11390
  validation_errors.append(
9041
- f"gate.rules[{index}].scope is legacy automatic gate escalation; run ap.py upgrade"
11391
+ f"gate.rules[{index}].scope is legacy automatic gate escalation; run autocoding init"
9042
11392
  )
9043
11393
  if "commands" in rule:
9044
11394
  rules_valid = False
9045
11395
  validation_errors.append(
9046
- f"gate.rules[{index}].commands is legacy automatic gate escalation; run ap.py upgrade"
11396
+ f"gate.rules[{index}].commands is legacy automatic gate escalation; run autocoding init"
9047
11397
  )
9048
11398
 
9049
11399
  risk_rules = _risk_cfg(cfg).get("rules") or []
@@ -9063,8 +11413,13 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9063
11413
  )
9064
11414
 
9065
11415
  validation_cfg = _validation_cfg(cfg)
9066
- on_unmapped = _text(validation_cfg.get("on_unmapped")).lower() or "error"
9067
- if on_unmapped not in {"error", "fallback"}:
11416
+ raw_on_unmapped = validation_cfg.get("on_unmapped", "error")
11417
+ if not isinstance(raw_on_unmapped, str):
11418
+ validation_errors.append("validation.on_unmapped must be a string")
11419
+ on_unmapped = ""
11420
+ else:
11421
+ on_unmapped = raw_on_unmapped.strip().lower() or "error"
11422
+ if on_unmapped and on_unmapped not in {"error", "fallback"}:
9068
11423
  validation_errors.append("validation.on_unmapped must be error or fallback")
9069
11424
  try:
9070
11425
  final_budget = _final_gate_budget(cfg)
@@ -9185,22 +11540,51 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9185
11540
  f"install integrity: {issue}" for issue in integrity["errors"]
9186
11541
  )
9187
11542
 
11543
+ if (
11544
+ isinstance(raw_project_name, str)
11545
+ and _FEEDBACK_SAFE_ID_RE.fullmatch(raw_project_name.strip())
11546
+ and _FEEDBACK_SEMVER_RE.fullmatch(skill_version)
11547
+ and (repo / "docs" / "skill-feedback" / "reports").exists()
11548
+ ):
11549
+ try:
11550
+ feedback = _feedback_collection_result([str(repo)])
11551
+ except APError:
11552
+ advisories.append(
11553
+ "Skill feedback metadata needs maintenance; run "
11554
+ "autocoding feedback --projects . --json for the bounded diagnostic"
11555
+ )
11556
+ else:
11557
+ if feedback["action_required_count"]:
11558
+ advisories.append(
11559
+ f"{feedback['action_required_count']} Skill feedback report(s) need recheck, "
11560
+ "closure, upgrade, or project-overlay routing; run "
11561
+ "autocoding feedback --projects . --json"
11562
+ )
11563
+
9188
11564
  missing.extend(validation_errors)
9189
11565
 
9190
11566
  if missing:
9191
- _record_evidence(repo, cfg, "doctor", "fail", {"issues": missing})
11567
+ if record:
11568
+ _record_evidence(repo, cfg, "doctor", "fail", {"issues": missing})
11569
+ if collect:
11570
+ return {"issues": missing, "advisories": advisories}
9192
11571
  raise APError("Doctor found blocking config issues:\n- " + "\n- ".join(missing))
9193
11572
 
9194
- _record_evidence(
9195
- repo,
9196
- cfg,
9197
- "doctor",
9198
- "pass",
9199
- {"mode": mode, "completion": completion, "access_fields": len(_REQUIRED_ACCESS_FIELDS)},
9200
- )
9201
- for advisory in advisories:
9202
- print(f"[doctor] WARN: {advisory}")
9203
- print("[doctor] OK")
11573
+ if record:
11574
+ _record_evidence(
11575
+ repo,
11576
+ cfg,
11577
+ "doctor",
11578
+ "pass",
11579
+ {"mode": mode, "completion": completion, "access_fields": len(_REQUIRED_ACCESS_FIELDS)},
11580
+ )
11581
+ if collect:
11582
+ return {"issues": [], "advisories": advisories}
11583
+ if not quiet:
11584
+ for advisory in advisories:
11585
+ print(f"[doctor] WARN: {advisory}")
11586
+ print("[doctor] OK")
11587
+ return None
9204
11588
 
9205
11589
 
9206
11590
  def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
@@ -10456,6 +12840,9 @@ def cmd_task_start(args: argparse.Namespace) -> None:
10456
12840
  or getattr(args, "force_lifecycle", False)
10457
12841
  or continue_direct
10458
12842
  )
12843
+ # Validate legacy workflow policy before planning reads gate/risk rules so
12844
+ # task-start reports the complete migration set and remains zero-write.
12845
+ _require_workflow_policy_clean(repo, cfg)
10459
12846
  preflight_plan = _resolve_execution_plan(
10460
12847
  cfg,
10461
12848
  repo,
@@ -10478,12 +12865,11 @@ def cmd_task_start(args: argparse.Namespace) -> None:
10478
12865
  "only when classify requires isolation/review or the user explicitly requests it."
10479
12866
  )
10480
12867
 
10481
- _require_workflow_policy_clean(repo, cfg)
10482
12868
  configured_isolation = _task_isolation(cfg)
10483
12869
  access_issues = _access_config_issues(cfg)
10484
12870
  if access_issues:
10485
12871
  raise APError(
10486
- "Project initialization is incomplete; fill docs/ENGINEERING.md before starting work:\n- "
12872
+ "Project initialization is incomplete; fill docs/project/auto-coding-skill.yaml before starting work:\n- "
10487
12873
  + "\n- ".join(access_issues)
10488
12874
  )
10489
12875
  remote, target_branch, base_ref = _task_remote_and_target(cfg, args)
@@ -13746,6 +16132,12 @@ def main(argv: Optional[List[str]] = None) -> int:
13746
16132
  s.add_argument("--json", action="store_true")
13747
16133
  s.set_defaults(func=cmd_scaffold)
13748
16134
 
16135
+ s = sp.add_parser("managed-scaffold-converge", help=argparse.SUPPRESS)
16136
+ s.add_argument("group", choices=scaffold_groups())
16137
+ s.add_argument("--write", action="store_true")
16138
+ s.add_argument("--json", action="store_true")
16139
+ s.set_defaults(func=cmd_managed_scaffold_converge)
16140
+
13749
16141
  s = sp.add_parser("upgrade")
13750
16142
  s.add_argument("--dry-run", action="store_true")
13751
16143
  s.add_argument("--write", action="store_true")
@@ -13757,6 +16149,49 @@ def main(argv: Optional[List[str]] = None) -> int:
13757
16149
  s.add_argument("--json", action="store_true")
13758
16150
  s.set_defaults(func=cmd_project_converge)
13759
16151
 
16152
+ s = sp.add_parser("project-config-prepare", help=argparse.SUPPRESS)
16153
+ s.add_argument("--write", action="store_true")
16154
+ s.add_argument("--json", action="store_true")
16155
+ s.set_defaults(func=cmd_project_config_prepare)
16156
+
16157
+ s = sp.add_parser("project-config-finalize", help=argparse.SUPPRESS)
16158
+ s.add_argument("--write", action="store_true")
16159
+ s.add_argument("--json", action="store_true")
16160
+ s.add_argument("--engineering-sha256", required=True)
16161
+ s.add_argument("--overlay-sha256", required=True)
16162
+ s.add_argument("--template-sha256", required=True)
16163
+ s.set_defaults(func=cmd_project_config_finalize)
16164
+
16165
+ s = sp.add_parser("project-file-safe", help=argparse.SUPPRESS)
16166
+ s.add_argument("operation", choices=["write", "create", "chmod", "chmod-batch"])
16167
+ s.add_argument("--path", default="")
16168
+ s.add_argument("--mode", default="")
16169
+ s.add_argument("--json", action="store_true")
16170
+ s.set_defaults(func=cmd_project_file_safe)
16171
+
16172
+ s = sp.add_parser("install-io", help=argparse.SUPPRESS)
16173
+ s.add_argument("operation", choices=["switch", "recover", "complete"])
16174
+ s.add_argument("--old-skill-present", action="store_true")
16175
+ s.add_argument("--old-manifest-present", action="store_true")
16176
+ s.add_argument("--old-engineering-present", action="store_true")
16177
+ s.add_argument("--json", action="store_true")
16178
+ s.set_defaults(func=cmd_install_io)
16179
+
16180
+ s = sp.add_parser(
16181
+ "config-effective",
16182
+ help="Show a redacted summary of managed defaults plus project overrides",
16183
+ )
16184
+ s.add_argument("--json", action="store_true")
16185
+ s.set_defaults(func=cmd_config_effective)
16186
+
16187
+ s = sp.add_parser(
16188
+ "feedback-collect",
16189
+ help="Read bounded metadata-only Skill feedback reports from explicit projects",
16190
+ )
16191
+ s.add_argument("--project", action="append", required=True)
16192
+ s.add_argument("--json", action="store_true")
16193
+ s.set_defaults(func=cmd_feedback_collect)
16194
+
13760
16195
  s = sp.add_parser("baseline")
13761
16196
  baseline_sp = s.add_subparsers(dest="baseline_cmd", required=True)
13762
16197
  b = baseline_sp.add_parser("init")
@@ -14060,6 +16495,24 @@ def main(argv: Optional[List[str]] = None) -> int:
14060
16495
 
14061
16496
  try:
14062
16497
  args = p.parse_args(argv)
16498
+ repo = Path(args.repo).resolve()
16499
+ tokenized_write = (
16500
+ args.cmd == "project-file-safe"
16501
+ or (
16502
+ args.cmd in {
16503
+ "managed-scaffold-converge",
16504
+ "project-config-finalize",
16505
+ "project-converge",
16506
+ }
16507
+ and bool(getattr(args, "write", False))
16508
+ )
16509
+ )
16510
+ if args.cmd == "install-io":
16511
+ pass
16512
+ elif tokenized_write:
16513
+ _require_active_install_transaction(repo)
16514
+ elif args.cmd != "config-effective":
16515
+ _require_no_install_transaction(repo)
14063
16516
  args.func(args)
14064
16517
  return 0
14065
16518
  except APError as e: