@elvis1513/auto-coding-skill 4.2.8 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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,30 @@ 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
+ scaffold_groups,
61
+ templates_for,
62
+ )
41
63
 
42
64
 
43
65
  _JENKINS_CRUMB_CACHE: dict[tuple[str, str], dict[str, str]] = {}
@@ -78,6 +100,72 @@ _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
78
100
  _REVIEW_DIFF_ARTIFACT_FORMAT = "git-binary-patch-v1"
79
101
  _REVIEW_DIFF_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024
80
102
  _REVIEW_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
103
+ _FEEDBACK_SCHEMA = "auto-coding-skill-feedback/v1"
104
+ _FEEDBACK_COLLECTION_SCHEMA = "auto-coding-skill-feedback-collection/v1"
105
+ _FEEDBACK_REPORT_MAX_BYTES = 16 * 1024
106
+ _FEEDBACK_PROJECT_MAX_REPORTS = 100
107
+ _FEEDBACK_PROJECT_MAX_ENTRIES = 200
108
+ _FEEDBACK_COLLECTION_MAX_BYTES = 1024 * 1024
109
+ _FEEDBACK_COLLECTION_MAX_REPORTS = 500
110
+ _FEEDBACK_COLLECTION_MAX_PROJECTS = 100
111
+ _PROJECT_CONFIG_RELATIVE = PROJECT_CONFIG_PATH
112
+ _INSTALL_TRANSACTION_RELATIVE = Path(".agents/.auto-coding-skill-install-transaction")
113
+ _EFFECTIVE_CONFIG_PATHS = {
114
+ "docs/ENGINEERING.md",
115
+ _PROJECT_CONFIG_RELATIVE.as_posix(),
116
+ }
117
+ _FEEDBACK_FIELDS = (
118
+ "schema",
119
+ "report_id",
120
+ "status",
121
+ "created_at",
122
+ "project",
123
+ "observed_skill_version",
124
+ "component",
125
+ "kind",
126
+ "impact",
127
+ "origin_surface",
128
+ "suspected_scope",
129
+ "signature",
130
+ "export",
131
+ )
132
+ _FEEDBACK_STATUSES = {"open", "needs-evidence", "accepted", "duplicate", "resolved", "rejected"}
133
+ _FEEDBACK_KINDS = {"defect", "gap"}
134
+ _FEEDBACK_IMPACTS = {"blocking", "degraded", "minor"}
135
+ _FEEDBACK_ORIGIN_SURFACES = {
136
+ "managed-template",
137
+ "managed-script",
138
+ "managed-agent",
139
+ "cli",
140
+ "installer",
141
+ }
142
+ _FEEDBACK_HEADINGS = (
143
+ "Symptom",
144
+ "Expected",
145
+ "Minimal reproduction",
146
+ "Evidence",
147
+ "Workaround",
148
+ "Why shared",
149
+ )
150
+ _FEEDBACK_SAFE_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
151
+ _FEEDBACK_SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
152
+ _FEEDBACK_SIGNATURE_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
153
+ _FEEDBACK_FILENAME_RE = re.compile(
154
+ r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}\.md$"
155
+ )
156
+ _FEEDBACK_SENSITIVE_PATTERNS = (
157
+ re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----", re.IGNORECASE),
158
+ re.compile(r"\bAuthorization\s*:\s*Bearer\s+\S+", re.IGNORECASE),
159
+ re.compile(r"https?://[^\s/:@]+:[^\s/@]+@", re.IGNORECASE),
160
+ re.compile(r"(?:^|[\s`])/(?:Users|home)/[^/\s]+/"),
161
+ re.compile(r"\b[A-Za-z]:\\Users\\[^\\\s]+\\", re.IGNORECASE),
162
+ )
163
+ _FEEDBACK_SEMVER_RE = re.compile(
164
+ r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
165
+ r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)"
166
+ r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?"
167
+ r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
168
+ )
81
169
  _DEEP_REVIEW_CATEGORIES = {
82
170
  "api",
83
171
  "auth",
@@ -168,7 +256,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
168
256
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
169
257
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
170
258
  "schema_version": 1,
171
- "managed_versions": {"agents": "4.2.8", "engineering": "4.2.8"},
259
+ "managed_versions": {"agents": "4.3.0", "engineering": "4.3.0"},
172
260
  "known_official_engineering_body_sha256": [
173
261
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
174
262
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -263,7 +351,7 @@ def _join_url(base: str, path: str) -> str:
263
351
  base = str(base or "").strip().rstrip("/")
264
352
  path = str(path or "").strip()
265
353
  if not base or not path:
266
- raise APError("Health URL config incomplete. Fill base url and path in docs/ENGINEERING.md.")
354
+ raise APError("Health URL config incomplete. Fill the project configuration overlay.")
267
355
  if not path.startswith("/"):
268
356
  path = "/" + path
269
357
  return base + path
@@ -391,7 +479,7 @@ def _require_http_url(field: str, value: object) -> str:
391
479
  raw = _text(value).rstrip("/")
392
480
  parsed = urllib.parse.urlparse(raw)
393
481
  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.")
482
+ raise APError(f"Missing or invalid {field}; fill an http/https URL in the project configuration overlay.")
395
483
  return raw
396
484
 
397
485
 
@@ -619,7 +707,7 @@ def _jenkins_api_get_json(
619
707
  f"Jenkins API request failed: {url}\n"
620
708
  f"HTTP 403\n{body or '(empty response body)'}\n"
621
709
  "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
622
- "Fill jenkins.base_url in docs/ENGINEERING.md if needed."
710
+ "Fill jenkins.base_url in the project configuration overlay if needed."
623
711
  ) from exc
624
712
  else:
625
713
  raise APError(
@@ -727,7 +815,7 @@ def _resolve_jenkins_job_url(
727
815
  return _jenkins_job_url_from_name(base_url, requested_name)
728
816
  raise APError(
729
817
  f"Cannot resolve Jenkins job URL for job '{requested_name}'. "
730
- "Pass --job-url, or fill the selected Jenkins endpoint in docs/ENGINEERING.md."
818
+ "Pass --job-url, or fill the selected Jenkins endpoint in the project configuration overlay."
731
819
  )
732
820
  if configured_url:
733
821
  return configured_url.rstrip("/")
@@ -842,257 +930,476 @@ def _inferred_gate_commands(repo: Path) -> dict[str, str]:
842
930
  return {}
843
931
 
844
932
 
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
933
  def _mapping(value: object) -> dict:
869
934
  return value if isinstance(value, dict) else {}
870
935
 
871
936
 
872
- def _string_list(value: object) -> list[str]:
873
- if not isinstance(value, list):
937
+ _NO_CONFIG_DIFF = object()
938
+
939
+
940
+ def _config_values_equal(left: object, right: object) -> bool:
941
+ """Compare parsed configuration without Python's bool/number coercions."""
942
+ if type(left) is not type(right):
943
+ return False
944
+ if isinstance(left, dict):
945
+ return left.keys() == right.keys() and all(
946
+ _config_values_equal(left[key], right[key]) for key in left
947
+ )
948
+ if isinstance(left, list):
949
+ return len(left) == len(right) and all(
950
+ _config_values_equal(left_item, right_item)
951
+ for left_item, right_item in zip(left, right)
952
+ )
953
+ return left == right
954
+
955
+
956
+ def _config_semantic_diff(current: object, base: object, path: tuple[str, ...] = ()) -> object:
957
+ """Return only project-owned values, excluding the managed release identity."""
958
+ if path == ("workflow", "skill_version"):
959
+ return _NO_CONFIG_DIFF
960
+ if isinstance(current, dict) and isinstance(base, dict):
961
+ result: dict = {}
962
+ for key, value in current.items():
963
+ field_path = (*path, str(key))
964
+ if key not in base:
965
+ if field_path != ("workflow", "skill_version"):
966
+ result[key] = json.loads(json.dumps(value))
967
+ continue
968
+ difference = _config_semantic_diff(value, base[key], field_path)
969
+ if difference is not _NO_CONFIG_DIFF:
970
+ result[key] = difference
971
+ return result if result else _NO_CONFIG_DIFF
972
+ if not _config_values_equal(current, base):
973
+ return json.loads(json.dumps(current))
974
+ return _NO_CONFIG_DIFF
975
+
976
+
977
+ def _config_difference_conflicts(
978
+ difference: object,
979
+ current: object,
980
+ effective: object,
981
+ path: tuple[str, ...] = (),
982
+ ) -> list[str]:
983
+ """Find legacy project values not preserved exactly by an existing overlay."""
984
+ if difference is _NO_CONFIG_DIFF:
874
985
  return []
875
- return [item.strip() for item in value if isinstance(item, str) and item.strip()]
986
+ if isinstance(difference, dict):
987
+ if not isinstance(current, dict) or not isinstance(effective, dict):
988
+ return [".".join(path) or "(root)"]
989
+ conflicts: list[str] = []
990
+ for key, value in difference.items():
991
+ field_path = (*path, str(key))
992
+ if key not in current or key not in effective:
993
+ conflicts.append(".".join(field_path))
994
+ continue
995
+ conflicts.extend(
996
+ _config_difference_conflicts(
997
+ value,
998
+ current[key],
999
+ effective[key],
1000
+ field_path,
1001
+ )
1002
+ )
1003
+ return conflicts
1004
+ return [] if _config_values_equal(current, effective) else [".".join(path) or "(root)"]
876
1005
 
877
1006
 
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
1007
+ _INSTALLED_ENGINEERING_TEMPLATE = Path(
1008
+ ".agents/skills/auto-coding-skill/data/templates/ENGINEERING.md"
1009
+ )
1010
+ _INSTALLED_MANIFEST = Path(".agents/managed-install.json")
974
1011
 
975
1012
 
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",
1013
+ def _installed_template_config(repo: Path) -> dict | None:
1014
+ relative = _INSTALLED_ENGINEERING_TEMPLATE
1015
+ payload = _safe_read_project_file(repo, relative, max_bytes=1024 * 1024)
1016
+ if payload is None:
1017
+ return None
1018
+ manifest_payload = _safe_read_project_file(repo, _INSTALLED_MANIFEST, max_bytes=4 * 1024 * 1024)
1019
+ if manifest_payload is None:
1020
+ raise APError(
1021
+ "Cannot trust the installed default template without .agents/managed-install.json; "
1022
+ "no files were written."
1023
+ )
1024
+
1025
+ def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
1026
+ result: dict = {}
1027
+ for key, value in pairs:
1028
+ if not isinstance(key, str) or key in result:
1029
+ raise ValueError("invalid manifest mapping")
1030
+ result[key] = value
1031
+ return result
1032
+
1033
+ try:
1034
+ manifest = json.loads(
1035
+ manifest_payload.decode("utf-8"),
1036
+ object_pairs_hook=reject_duplicate_keys,
1037
+ )
1038
+ except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
1039
+ raise APError("Installed managed manifest is invalid; no files were written.") from exc
1040
+ if (
1041
+ not isinstance(manifest, dict)
1042
+ or manifest.get("schema_version") != 1
1043
+ or manifest.get("manifest_path") != _INSTALLED_MANIFEST.as_posix()
1044
+ or not isinstance(manifest.get("entries"), list)
1072
1045
  ):
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",
1046
+ raise APError("Installed managed manifest is invalid; no files were written.")
1047
+ if len(manifest["entries"]) > 10000:
1048
+ raise APError("Installed managed manifest has too many entries; no files were written.")
1049
+ matches = [
1050
+ entry
1051
+ for entry in manifest["entries"]
1052
+ if isinstance(entry, dict) and entry.get("path") == relative.as_posix()
1053
+ ]
1054
+ manifest_version = _text(manifest.get("skill_version"))
1055
+ if not re.fullmatch(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", manifest_version):
1056
+ raise APError("Installed managed manifest has an invalid Skill version; no files were written.")
1057
+ if len(matches) != 1:
1058
+ raise APError("Installed default template is not bound by the managed manifest; no files were written.")
1059
+ entry = matches[0]
1060
+ expected_hash = _text(entry.get("sha256"))
1061
+ if (
1062
+ entry.get("ownership") != "exact"
1063
+ or entry.get("source") != "skill/data/templates/ENGINEERING.md"
1064
+ or entry.get("version") != manifest_version
1065
+ or not re.fullmatch(r"[0-9a-f]{64}", expected_hash)
1066
+ or hashlib.sha256(payload).hexdigest() != expected_hash
1080
1067
  ):
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")
1068
+ raise APError("Installed default template failed its managed manifest identity check; no files were written.")
1069
+ config = parse_managed_config_payload(payload)
1070
+ config_version = _text(_mapping(config.get("workflow")).get("skill_version"))
1071
+ if config_version != manifest_version:
1072
+ raise APError("Installed default template version is not bound to its manifest; no files were written.")
1073
+ return config
1074
+
1075
+
1076
+ def _render_project_overlay(overrides: dict) -> bytes:
1077
+ document = {"schema": PROJECT_CONFIG_SCHEMA, "overrides": overrides}
1078
+ dumped = require_yaml().safe_dump(document, allow_unicode=True, sort_keys=False)
1079
+ payload = dumped.encode("utf-8")
1080
+ # The installer must never create an overlay that its own runtime rejects.
1081
+ parse_project_overrides_payload(payload)
1082
+ return payload
1083
+
1084
+
1085
+ def _project_config_convergence_plan(repo: Path, template: Path) -> dict:
1086
+ template_payload = template.read_bytes()
1087
+ template_cfg = parse_managed_config_payload(template_payload)
1088
+ try:
1089
+ template_text = template_payload.decode("utf-8")
1090
+ except UnicodeDecodeError as exc:
1091
+ raise APError("Managed Skill template must be UTF-8.") from exc
1092
+ current_payload = _safe_read_project_file(
1093
+ repo,
1094
+ Path("docs/ENGINEERING.md"),
1095
+ max_bytes=1024 * 1024,
1096
+ )
1097
+ current_cfg: dict | None = None
1098
+ current_text = ""
1099
+ if current_payload is not None:
1100
+ try:
1101
+ current_text = current_payload.decode("utf-8")
1102
+ except UnicodeDecodeError as exc:
1103
+ raise APError("Managed project configuration must be UTF-8.") from exc
1104
+ current_cfg = parse_managed_config_payload(current_payload)
1105
+
1106
+ # Always validate an existing overlay before any installer write. Its bytes
1107
+ # are project-owned and are never normalized by ordinary convergence.
1108
+ overlay_payload = _safe_read_project_file(
1109
+ repo,
1110
+ _PROJECT_CONFIG_RELATIVE,
1111
+ max_bytes=128 * 1024,
1112
+ )
1113
+ overrides = (
1114
+ parse_project_overrides_payload(overlay_payload)
1115
+ if overlay_payload is not None
1116
+ else {}
1117
+ )
1118
+ old_base = None
1119
+ if current_cfg is not None:
1120
+ # A completed target document is self-identical to the trusted source
1121
+ # template, so retry does not depend on the previous install manifest.
1122
+ # Legacy/custom documents still require a manifest-bound old base.
1123
+ old_base = (
1124
+ template_cfg
1125
+ if current_payload == template_payload
1126
+ else _installed_template_config(repo)
1127
+ )
1128
+ overlay_output: bytes | None = None
1129
+ migrated_paths: list[str] = []
1130
+
1131
+ if overlay_payload is None:
1132
+ if current_cfg is not None and old_base is None:
1133
+ current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
1134
+ template_version = _text(_mapping(template_cfg.get("workflow")).get("skill_version"))
1135
+ if current_version != template_version:
1136
+ raise APError(
1137
+ "Cannot migrate project configuration without its installed default template; "
1138
+ "no files were written. Restore the current .agents Skill copy or create the "
1139
+ "project overlay explicitly."
1140
+ )
1141
+ old_base = template_cfg
1142
+ difference = (
1143
+ _config_semantic_diff(current_cfg, old_base or template_cfg)
1144
+ if current_cfg is not None
1145
+ else _NO_CONFIG_DIFF
1146
+ )
1147
+ overrides = difference if isinstance(difference, dict) else {}
1148
+ if current_cfg is not None:
1149
+ semantic_base = old_base or template_cfg
1150
+ current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
1151
+ base_version = _text(_mapping(semantic_base.get("workflow")).get("skill_version"))
1152
+ if current_version != base_version:
1153
+ raise APError(
1154
+ "Installed default template version does not match docs/ENGINEERING.md; "
1155
+ "no files were written."
1156
+ )
1157
+ if not _config_values_equal(
1158
+ merge_project_config(semantic_base, overrides),
1159
+ current_cfg,
1160
+ ):
1161
+ raise APError(
1162
+ "Project configuration migration could not prove semantic equivalence; "
1163
+ "no files were written."
1164
+ )
1165
+ project_cfg = overrides.setdefault("project", {})
1166
+ if not isinstance(project_cfg, dict):
1167
+ raise APError("Legacy project.project must be a mapping before configuration migration.")
1168
+ if not _text(project_cfg.get("name")):
1169
+ project_cfg["name"] = repo.name
1170
+ if current_cfg is None:
1171
+ inferred = _inferred_gate_commands(repo)
1172
+ if inferred:
1173
+ overrides.setdefault("commands", {}).update(inferred)
1174
+ # Validate protected fields and merge behavior before writing the new file.
1175
+ merge_project_config(template_cfg, overrides)
1176
+ overlay_output = _render_project_overlay(overrides)
1177
+ migrated_paths = sorted(_flatten_config_paths(overrides))
1178
+ elif current_cfg is not None:
1179
+ if old_base is None:
1180
+ raise APError(
1181
+ "Cannot verify an existing project overlay without the installed default template; "
1182
+ "no files were written."
1183
+ )
1184
+ current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
1185
+ base_version = _text(_mapping(old_base.get("workflow")).get("skill_version"))
1186
+ if current_version != base_version:
1187
+ raise APError(
1188
+ "Installed default template version does not match docs/ENGINEERING.md; "
1189
+ "no files were written."
1190
+ )
1191
+ legacy_difference = _config_semantic_diff(current_cfg, old_base)
1192
+ legacy_overrides = legacy_difference if isinstance(legacy_difference, dict) else {}
1193
+ if not _config_values_equal(
1194
+ merge_project_config(old_base, legacy_overrides),
1195
+ current_cfg,
1196
+ ):
1197
+ raise APError(
1198
+ "Legacy project configuration cannot be represented as additive overrides; "
1199
+ "no files were written. Restore the deleted default field or create an explicit "
1200
+ "project overlay after reconciling the intended value."
1201
+ )
1202
+ legacy_effective = merge_project_config(old_base, overrides)
1203
+ conflicts = _config_difference_conflicts(
1204
+ legacy_difference,
1205
+ current_cfg,
1206
+ legacy_effective,
1207
+ )
1208
+ if conflicts:
1209
+ raise APError(
1210
+ "Existing project overlay conflicts with legacy project configuration; "
1211
+ "no files were written. Preserve these paths exactly in "
1212
+ "docs/project/auto-coding-skill.yaml: "
1213
+ + ", ".join(sorted(conflicts))
1214
+ )
1215
+ merge_project_config(template_cfg, overrides)
1216
+
1217
+ return {
1218
+ "engineering_output": template_text,
1219
+ "engineering_current": current_text,
1220
+ "overlay_current": overlay_payload,
1221
+ "overlay_output": overlay_output,
1222
+ "migrated_paths": migrated_paths,
1223
+ }
1224
+
1225
+
1226
+ def _flatten_config_paths(value: object, prefix: tuple[str, ...] = ()) -> list[str]:
1227
+ if not isinstance(value, dict) or not value:
1228
+ return [".".join(prefix)] if prefix else []
1229
+ result: list[str] = []
1230
+ for key, nested in value.items():
1231
+ result.extend(_flatten_config_paths(nested, (*prefix, str(key))))
1232
+ return result
1233
+
1234
+
1235
+ def _sha256_payload(payload: bytes) -> str:
1236
+ return hashlib.sha256(payload).hexdigest()
1237
+
1238
+
1239
+ _ARCHIVE_TARGET_ATTEMPTS = 64
1240
+
1241
+
1242
+ def _select_project_archive_target(
1243
+ repo: Path,
1244
+ preferred: str | Path,
1245
+ payload: bytes,
1246
+ *,
1247
+ legacy_digest_payload: bytes | None = None,
1248
+ ) -> tuple[Path, bool]:
1249
+ """Select an archive path without ever treating different bytes as archived."""
1250
+ preferred_rel = _safe_project_relative_path(preferred)
1251
+ payload_digest = hashlib.sha256(payload).hexdigest()
1252
+ legacy_digest = hashlib.sha256(
1253
+ payload if legacy_digest_payload is None else legacy_digest_payload
1254
+ ).hexdigest()[:12]
1255
+ preferred_suffix = preferred_rel.suffix
1256
+ legacy_candidate = preferred_rel.with_name(
1257
+ f"{preferred_rel.stem}-{legacy_digest}{preferred_suffix}"
1258
+ )
1259
+ path_digest = hashlib.sha256(preferred_rel.as_posix().encode("utf-8")).hexdigest()[:12]
1260
+ compact_stem = f".autocoding-archive-{path_digest}-{payload_digest}"
1261
+
1262
+ candidates = [preferred_rel]
1263
+ try:
1264
+ if len(os.fsencode(legacy_candidate.name)) <= 240:
1265
+ candidates.append(legacy_candidate)
1266
+ except UnicodeEncodeError:
1267
+ pass
1268
+ candidates.append(preferred_rel.with_name(f"{compact_stem}{preferred_suffix}"))
1269
+ candidates.extend(
1270
+ preferred_rel.with_name(f"{compact_stem}-{attempt}{preferred_suffix}")
1271
+ for attempt in range(2, _ARCHIVE_TARGET_ATTEMPTS + 1)
1086
1272
  )
1087
- current_layers = _mapping(current_structure.get("layer_rules"))
1088
- converged["structure"]["layer_rules"]["rules"] = _normalize_layer_rules(
1089
- current_layers.get("rules")
1273
+
1274
+ seen: set[str] = set()
1275
+ for candidate in candidates:
1276
+ key = candidate.as_posix()
1277
+ if key in seen:
1278
+ continue
1279
+ seen.add(key)
1280
+ archived = _safe_read_project_file(repo, candidate)
1281
+ if archived is None:
1282
+ return candidate, True
1283
+ if archived == payload:
1284
+ return candidate, False
1285
+ raise APError(
1286
+ "Cannot allocate a collision-free project archive target without overwriting "
1287
+ f"different content: {preferred_rel.as_posix()}"
1090
1288
  )
1091
1289
 
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()}"
1290
+
1291
+ def cmd_project_config_prepare(args: argparse.Namespace) -> None:
1292
+ repo = Path(args.repo).resolve()
1293
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
1294
+ plan = _project_config_convergence_plan(repo, template)
1295
+ write = bool(args.write)
1296
+ current = plan["engineering_current"].encode("utf-8")
1297
+ engineering_output = plan["engineering_output"].encode("utf-8")
1298
+ overlay = plan["overlay_output"] or plan["overlay_current"]
1299
+ if overlay is None:
1300
+ raise APError("Project configuration prepare did not produce an overlay; no files were written.")
1301
+ finalize_required = bool(current and current != engineering_output)
1302
+ if finalize_required:
1303
+ template_cfg = parse_managed_config_payload(engineering_output)
1304
+ version = _text(_mapping(template_cfg.get("workflow")).get("skill_version")) or "current"
1305
+ archive_payload = (
1306
+ f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
1307
+ "Historical and non-authoritative. Project configuration was migrated to "
1308
+ "docs/project/auto-coding-skill.yaml.\n\n---\n\n"
1309
+ ).encode("utf-8") + current
1310
+ _select_project_archive_target(
1311
+ repo,
1312
+ Path(".agents/archive/auto-coding-skill") / version / "docs/ENGINEERING.md",
1313
+ archive_payload,
1314
+ legacy_digest_payload=current,
1315
+ )
1316
+ actions: list[dict] = []
1317
+ if plan["overlay_output"] is not None:
1318
+ actions.append({"action": "create", "path": _PROJECT_CONFIG_RELATIVE.as_posix()})
1319
+ if write:
1320
+ _safe_create_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay)
1321
+ if not current:
1322
+ actions.append({"action": "create", "path": "docs/ENGINEERING.md"})
1323
+ if write:
1324
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), engineering_output)
1325
+ elif finalize_required:
1326
+ actions.append({
1327
+ "action": "defer-replace",
1328
+ "path": "docs/ENGINEERING.md",
1329
+ "detail": "replace only after the effective-config runtime is installed",
1330
+ })
1331
+ result = {
1332
+ "mode": "write" if write else "plan",
1333
+ "actions": actions,
1334
+ "finalize_required": finalize_required,
1335
+ "engineering_before_sha256": _sha256_payload(current),
1336
+ "overlay_sha256": _sha256_payload(overlay),
1337
+ "template_sha256": _sha256_payload(engineering_output),
1338
+ }
1339
+ if args.json:
1340
+ print(json.dumps(result, ensure_ascii=False, indent=2))
1341
+ return
1342
+ for item in actions:
1343
+ print(f"[project-config-prepare] {item['action']}: {item['path']}")
1344
+
1345
+
1346
+ def cmd_project_config_finalize(args: argparse.Namespace) -> None:
1347
+ repo = Path(args.repo).resolve()
1348
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
1349
+ template_payload = template.read_bytes()
1350
+ current = _safe_read_project_file(repo, Path("docs/ENGINEERING.md"), max_bytes=1024 * 1024)
1351
+ overlay = _safe_read_project_file(repo, _PROJECT_CONFIG_RELATIVE, max_bytes=128 * 1024)
1352
+ expected = {
1353
+ "engineering": _text(args.engineering_sha256),
1354
+ "overlay": _text(args.overlay_sha256),
1355
+ "template": _text(args.template_sha256),
1356
+ }
1357
+ if any(not re.fullmatch(r"[0-9a-f]{64}", value) for value in expected.values()):
1358
+ raise APError("Project configuration finalize requires valid SHA-256 bindings.")
1359
+ if current is None or overlay is None:
1360
+ raise APError("Prepared project configuration inputs are missing; no files were written.")
1361
+ actual = {
1362
+ "engineering": _sha256_payload(current),
1363
+ "overlay": _sha256_payload(overlay),
1364
+ "template": _sha256_payload(template_payload),
1365
+ }
1366
+ mismatched = [name for name in expected if expected[name] != actual[name]]
1367
+ if mismatched:
1368
+ raise APError(
1369
+ "Prepared project configuration changed before finalize; no files were written: "
1370
+ + ", ".join(mismatched)
1371
+ )
1372
+ # Validate the final layers before replacing the legacy managed document.
1373
+ template_cfg = parse_managed_config_payload(template_payload)
1374
+ overrides = parse_project_overrides_payload(overlay)
1375
+ merge_project_config(template_cfg, overrides)
1376
+ version = _text(_mapping(template_cfg.get("workflow")).get("skill_version")) or "current"
1377
+ archive_payload = (
1378
+ f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
1379
+ "Historical and non-authoritative. Project configuration was migrated to "
1380
+ "docs/project/auto-coding-skill.yaml.\n\n---\n\n"
1381
+ ).encode("utf-8") + current
1382
+ archive, archive_required = _select_project_archive_target(
1383
+ repo,
1384
+ Path(".agents/archive/auto-coding-skill") / version / "docs/ENGINEERING.md",
1385
+ archive_payload,
1386
+ legacy_digest_payload=current,
1387
+ )
1388
+ actions: list[dict] = []
1389
+ if archive_required:
1390
+ actions.append({"action": "archive", "path": archive.as_posix()})
1391
+ if args.write:
1392
+ _safe_create_project_file(repo, archive, archive_payload)
1393
+ if current != template_payload:
1394
+ actions.append({"action": "replace", "path": "docs/ENGINEERING.md"})
1395
+ if args.write:
1396
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), template_payload)
1397
+ result = {"mode": "write" if args.write else "plan", "actions": actions}
1398
+ if args.json:
1399
+ print(json.dumps(result, ensure_ascii=False, indent=2))
1400
+ return
1401
+ for item in actions:
1402
+ print(f"[project-config-finalize] {item['action']}: {item['path']}")
1096
1403
 
1097
1404
 
1098
1405
  _PROJECT_ARTIFACT_PATTERNS = (
@@ -1101,11 +1408,1117 @@ _PROJECT_ARTIFACT_PATTERNS = (
1101
1408
  "docs/deployment/deploy-records/*.md",
1102
1409
  "docs/design/*.md",
1103
1410
  "docs/interfaces/*.md",
1411
+ "docs/project/*.md",
1412
+ _PROJECT_CONFIG_RELATIVE.as_posix(),
1104
1413
  "docs/reviews/*.md",
1414
+ *PROJECT_FEEDBACK_PATTERNS,
1105
1415
  )
1106
1416
 
1107
1417
 
1108
- def _is_allowed_project_doc(rel: Path) -> bool:
1418
+ def _safe_project_relative_path(rel: str | Path) -> Path:
1419
+ value = Path(rel)
1420
+ if value.is_absolute() or not value.parts or any(part in {"", ".", ".."} for part in value.parts):
1421
+ raise APError(f"Unsafe project-relative path: {rel}")
1422
+ return value
1423
+
1424
+
1425
+ def _is_windows_reparse_point(metadata: os.stat_result) -> bool:
1426
+ attributes = int(getattr(metadata, "st_file_attributes", 0) or 0)
1427
+ reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))
1428
+ return stat.S_ISLNK(metadata.st_mode) or bool(attributes & reparse_flag)
1429
+
1430
+
1431
+ def _project_path_identity(metadata: os.stat_result) -> tuple[int, int]:
1432
+ return int(metadata.st_dev), int(metadata.st_ino)
1433
+
1434
+
1435
+ def _validate_windows_project_directories(
1436
+ relative: Path,
1437
+ directories: list[tuple[Path, tuple[int, int]]],
1438
+ ) -> None:
1439
+ for directory, identity in directories:
1440
+ metadata = directory.lstat()
1441
+ if (
1442
+ _is_windows_reparse_point(metadata)
1443
+ or not stat.S_ISDIR(metadata.st_mode)
1444
+ or _project_path_identity(metadata) != identity
1445
+ ):
1446
+ raise APError(f"Project path parent changed during its safety check: {relative}")
1447
+
1448
+
1449
+ def _windows_project_path_snapshot(
1450
+ repo: Path,
1451
+ relative: Path,
1452
+ *,
1453
+ create_parents: bool,
1454
+ ) -> tuple[Path, list[tuple[Path, tuple[int, int]]], bool]:
1455
+ repo = Path(repo)
1456
+ repo_metadata = repo.lstat()
1457
+ if _is_windows_reparse_point(repo_metadata) or not stat.S_ISDIR(repo_metadata.st_mode):
1458
+ raise APError(f"Project repository root must be a real directory: {relative}")
1459
+
1460
+ directories = [(repo, _project_path_identity(repo_metadata))]
1461
+ current = repo
1462
+ for index, part in enumerate(relative.parts[:-1]):
1463
+ current = current / part
1464
+ if not os.path.lexists(current):
1465
+ if not create_parents:
1466
+ _validate_windows_project_directories(relative, directories)
1467
+ remaining = Path(*relative.parts[index + 1 :])
1468
+ return current / remaining, directories, False
1469
+ _validate_windows_project_directories(relative, directories)
1470
+ try:
1471
+ current.mkdir()
1472
+ except FileExistsError:
1473
+ # A concurrent creator is acceptable only when the result is
1474
+ # still a real directory and all previously checked parents
1475
+ # retain their identities.
1476
+ pass
1477
+ _validate_windows_project_directories(relative, directories)
1478
+ metadata = current.lstat()
1479
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
1480
+ raise APError(f"Project path component must be a real directory: {relative}")
1481
+ directories.append((current, _project_path_identity(metadata)))
1482
+
1483
+ _validate_windows_project_directories(relative, directories)
1484
+ return current / relative.parts[-1], directories, True
1485
+
1486
+
1487
+ def _fallback_safe_project_path(
1488
+ repo: Path,
1489
+ rel: str | Path,
1490
+ *,
1491
+ create_parents: bool = False,
1492
+ ) -> Path:
1493
+ relative = _safe_project_relative_path(rel)
1494
+ try:
1495
+ target, _, _ = _windows_project_path_snapshot(
1496
+ Path(repo),
1497
+ relative,
1498
+ create_parents=create_parents,
1499
+ )
1500
+ return target
1501
+ except APError:
1502
+ raise
1503
+ except OSError as exc:
1504
+ raise APError(f"Cannot access project path safely: {relative}") from exc
1505
+
1506
+
1507
+ def _inject_project_file_parent_swap(repo: Path, relative: Path) -> None:
1508
+ if os.environ.get("AUTOCODING_TEST_MODE") != "1":
1509
+ return
1510
+ if os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_PATH") != relative.as_posix():
1511
+ return
1512
+ if relative.parent == Path("."):
1513
+ raise APError("Project file parent-swap test requires a nested project path.")
1514
+ external = Path(os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_EXTERNAL", ""))
1515
+ backup = Path(os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_BACKUP", ""))
1516
+ target = Path(repo) / relative.parent
1517
+ if (
1518
+ not external.is_absolute()
1519
+ or not backup.is_absolute()
1520
+ or not external.is_dir()
1521
+ or external.is_symlink()
1522
+ or os.path.lexists(backup)
1523
+ ):
1524
+ raise APError("Invalid project file parent-swap test fixture.")
1525
+ target.rename(backup)
1526
+ target.symlink_to(external, target_is_directory=True)
1527
+
1528
+
1529
+ @contextlib.contextmanager
1530
+ def _open_project_parent(repo: Path, rel: str | Path, *, create: bool = False):
1531
+ relative = _safe_project_relative_path(rel)
1532
+ directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
1533
+ descriptors: list[int] = []
1534
+ bindings: list[tuple[int, str, tuple[int, int]]] = []
1535
+ root_identity: tuple[int, int] | None = None
1536
+
1537
+ def validate_bindings() -> None:
1538
+ assert root_identity is not None
1539
+ root_metadata = Path(repo).lstat()
1540
+ if (
1541
+ _is_windows_reparse_point(root_metadata)
1542
+ or not stat.S_ISDIR(root_metadata.st_mode)
1543
+ or _project_path_identity(root_metadata) != root_identity
1544
+ ):
1545
+ raise APError(f"Project repository root changed during its safety check: {relative}")
1546
+ for parent_fd, name, identity in bindings:
1547
+ metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
1548
+ if (
1549
+ stat.S_ISLNK(metadata.st_mode)
1550
+ or not stat.S_ISDIR(metadata.st_mode)
1551
+ or _project_path_identity(metadata) != identity
1552
+ ):
1553
+ raise APError(f"Project path parent changed during its safety check: {relative}")
1554
+
1555
+ try:
1556
+ current = os.open(repo, directory_flags)
1557
+ descriptors.append(current)
1558
+ root_metadata = os.fstat(current)
1559
+ if not stat.S_ISDIR(root_metadata.st_mode):
1560
+ raise APError(f"Project repository root must be a real directory: {relative}")
1561
+ root_identity = _project_path_identity(root_metadata)
1562
+ missing = False
1563
+ for part in relative.parts[:-1]:
1564
+ try:
1565
+ metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
1566
+ except FileNotFoundError:
1567
+ if not create:
1568
+ missing = True
1569
+ break
1570
+ os.mkdir(part, 0o755, dir_fd=current)
1571
+ metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
1572
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
1573
+ raise APError(f"Project path component must be a real directory: {relative}")
1574
+ next_descriptor = os.open(part, directory_flags, dir_fd=current)
1575
+ opened = os.fstat(next_descriptor)
1576
+ identity = _project_path_identity(opened)
1577
+ if not stat.S_ISDIR(opened.st_mode) or identity != _project_path_identity(metadata):
1578
+ os.close(next_descriptor)
1579
+ raise APError(f"Project path parent changed during its safety check: {relative}")
1580
+ bindings.append((current, part, identity))
1581
+ descriptors.append(next_descriptor)
1582
+ current = next_descriptor
1583
+ _inject_project_file_parent_swap(Path(repo), relative)
1584
+ validate_bindings()
1585
+ yield (None if missing else current), relative.parts[-1]
1586
+ validate_bindings()
1587
+ except OSError as exc:
1588
+ raise APError(f"Cannot access project path safely: {relative}") from exc
1589
+ finally:
1590
+ for descriptor in reversed(descriptors):
1591
+ with contextlib.suppress(OSError):
1592
+ os.close(descriptor)
1593
+
1594
+
1595
+ def _safe_read_project_file(
1596
+ repo: Path,
1597
+ rel: str | Path,
1598
+ *,
1599
+ max_bytes: int | None = None,
1600
+ ) -> bytes | None:
1601
+ relative = _safe_project_relative_path(rel)
1602
+ if max_bytes is not None and max_bytes <= 0:
1603
+ raise APError("max_bytes must be positive")
1604
+ if os.name == "nt":
1605
+ try:
1606
+ target, directories, parents_exist = _windows_project_path_snapshot(
1607
+ Path(repo),
1608
+ relative,
1609
+ create_parents=False,
1610
+ )
1611
+ if not parents_exist or not os.path.lexists(target):
1612
+ _validate_windows_project_directories(relative, directories)
1613
+ return None
1614
+ metadata = target.lstat()
1615
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
1616
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1617
+ identity = _project_path_identity(metadata)
1618
+ if max_bytes is not None and metadata.st_size > max_bytes:
1619
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1620
+ with target.open("rb") as handle:
1621
+ opened = os.fstat(handle.fileno())
1622
+ checked = target.lstat()
1623
+ if (
1624
+ not stat.S_ISREG(opened.st_mode)
1625
+ or _project_path_identity(opened) != identity
1626
+ or _is_windows_reparse_point(checked)
1627
+ or not stat.S_ISREG(checked.st_mode)
1628
+ or _project_path_identity(checked) != identity
1629
+ ):
1630
+ raise APError(f"Project file changed during its safety check: {relative}")
1631
+ _validate_windows_project_directories(relative, directories)
1632
+ payload = handle.read() if max_bytes is None else handle.read(max_bytes + 1)
1633
+ opened_after = os.fstat(handle.fileno())
1634
+ checked_after = target.lstat()
1635
+ if (
1636
+ not stat.S_ISREG(opened_after.st_mode)
1637
+ or _project_path_identity(opened_after) != identity
1638
+ or _is_windows_reparse_point(checked_after)
1639
+ or not stat.S_ISREG(checked_after.st_mode)
1640
+ or _project_path_identity(checked_after) != identity
1641
+ ):
1642
+ raise APError(f"Project file changed while it was read: {relative}")
1643
+ _validate_windows_project_directories(relative, directories)
1644
+ if max_bytes is not None and len(payload) > max_bytes:
1645
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1646
+ return payload
1647
+ except APError:
1648
+ raise
1649
+ except OSError as exc:
1650
+ raise APError(f"Cannot read project file safely: {relative}") from exc
1651
+ with _open_project_parent(repo, relative) as (parent_fd, leaf):
1652
+ if parent_fd is None:
1653
+ return None
1654
+ descriptor = -1
1655
+ try:
1656
+ descriptor = os.open(leaf, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0), dir_fd=parent_fd)
1657
+ except FileNotFoundError:
1658
+ return None
1659
+ except OSError as exc:
1660
+ raise APError(f"Project file must be a regular non-symlink file: {relative}") from exc
1661
+ try:
1662
+ metadata = os.fstat(descriptor)
1663
+ if not stat.S_ISREG(metadata.st_mode):
1664
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1665
+ if max_bytes is not None and metadata.st_size > max_bytes:
1666
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1667
+ with os.fdopen(descriptor, "rb") as handle:
1668
+ descriptor = -1
1669
+ payload = handle.read() if max_bytes is None else handle.read(max_bytes + 1)
1670
+ if max_bytes is not None and len(payload) > max_bytes:
1671
+ raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
1672
+ return payload
1673
+ finally:
1674
+ if descriptor >= 0:
1675
+ os.close(descriptor)
1676
+
1677
+
1678
+ @contextlib.contextmanager
1679
+ def _open_project_directory(repo: Path, rel: str | Path):
1680
+ relative = _safe_project_relative_path(rel)
1681
+ if os.name == "nt":
1682
+ try:
1683
+ target, directories, complete = _windows_project_path_snapshot(
1684
+ Path(repo),
1685
+ relative,
1686
+ create_parents=False,
1687
+ )
1688
+ except OSError as exc:
1689
+ raise APError(f"Cannot access project directory safely: {relative}") from exc
1690
+ if not complete or not os.path.lexists(target):
1691
+ yield None
1692
+ return
1693
+ metadata = target.lstat()
1694
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
1695
+ raise APError(f"Project directory must be a real directory: {relative}")
1696
+ identity = _project_path_identity(metadata)
1697
+ _validate_windows_project_directories(relative, directories)
1698
+ try:
1699
+ yield target
1700
+ finally:
1701
+ try:
1702
+ checked = target.lstat()
1703
+ _validate_windows_project_directories(relative, directories)
1704
+ except OSError as exc:
1705
+ raise APError(f"Project directory changed during its safety check: {relative}") from exc
1706
+ if (
1707
+ _is_windows_reparse_point(checked)
1708
+ or not stat.S_ISDIR(checked.st_mode)
1709
+ or _project_path_identity(checked) != identity
1710
+ ):
1711
+ raise APError(f"Project directory changed during its safety check: {relative}")
1712
+ return
1713
+ with _open_project_parent(repo, relative) as (parent_fd, leaf):
1714
+ if parent_fd is None:
1715
+ yield None
1716
+ return
1717
+ descriptor = -1
1718
+ try:
1719
+ descriptor = os.open(
1720
+ leaf,
1721
+ os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
1722
+ dir_fd=parent_fd,
1723
+ )
1724
+ except FileNotFoundError:
1725
+ yield None
1726
+ return
1727
+ except OSError as exc:
1728
+ raise APError(f"Project directory must be a real directory: {relative}") from exc
1729
+ try:
1730
+ metadata = os.fstat(descriptor)
1731
+ if not stat.S_ISDIR(metadata.st_mode):
1732
+ raise APError(f"Project directory must be a real directory: {relative}")
1733
+ yield descriptor
1734
+ finally:
1735
+ if descriptor >= 0:
1736
+ os.close(descriptor)
1737
+
1738
+
1739
+ def _safe_write_project_file(repo: Path, rel: str | Path, payload: bytes) -> None:
1740
+ relative = _safe_project_relative_path(rel)
1741
+ if os.name == "nt":
1742
+ temporary: Path | None = None
1743
+ try:
1744
+ target, directories, _ = _windows_project_path_snapshot(
1745
+ Path(repo),
1746
+ relative,
1747
+ create_parents=True,
1748
+ )
1749
+ _inject_project_file_parent_swap(Path(repo), relative)
1750
+ target_identity: tuple[int, int] | None = None
1751
+ if os.path.lexists(target):
1752
+ metadata = target.lstat()
1753
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
1754
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1755
+ target_identity = _project_path_identity(metadata)
1756
+ _validate_windows_project_directories(relative, directories)
1757
+
1758
+ temporary = target.with_name(f".{target.name}.autocoding-{uuid.uuid4().hex}")
1759
+ with temporary.open("xb") as handle:
1760
+ opened = os.fstat(handle.fileno())
1761
+ checked = temporary.lstat()
1762
+ temporary_identity = _project_path_identity(opened)
1763
+ if (
1764
+ not stat.S_ISREG(opened.st_mode)
1765
+ or _is_windows_reparse_point(checked)
1766
+ or not stat.S_ISREG(checked.st_mode)
1767
+ or _project_path_identity(checked) != temporary_identity
1768
+ ):
1769
+ raise APError(f"Temporary project file is unsafe: {relative}")
1770
+ _validate_windows_project_directories(relative, directories)
1771
+ handle.write(payload)
1772
+ handle.flush()
1773
+ os.fsync(handle.fileno())
1774
+ opened_after = os.fstat(handle.fileno())
1775
+ checked_after = temporary.lstat()
1776
+ if (
1777
+ not stat.S_ISREG(opened_after.st_mode)
1778
+ or _project_path_identity(opened_after) != temporary_identity
1779
+ or _is_windows_reparse_point(checked_after)
1780
+ or not stat.S_ISREG(checked_after.st_mode)
1781
+ or _project_path_identity(checked_after) != temporary_identity
1782
+ ):
1783
+ raise APError(f"Temporary project file changed while writing: {relative}")
1784
+ _validate_windows_project_directories(relative, directories)
1785
+
1786
+ if target_identity is None:
1787
+ if os.path.lexists(target):
1788
+ raise APError(f"Project file appeared while writing: {relative}")
1789
+ else:
1790
+ checked_target = target.lstat()
1791
+ if (
1792
+ _is_windows_reparse_point(checked_target)
1793
+ or not stat.S_ISREG(checked_target.st_mode)
1794
+ or _project_path_identity(checked_target) != target_identity
1795
+ ):
1796
+ raise APError(f"Project file changed while writing: {relative}")
1797
+ _validate_windows_project_directories(relative, directories)
1798
+ os.replace(temporary, target)
1799
+ replaced = target.lstat()
1800
+ if (
1801
+ _is_windows_reparse_point(replaced)
1802
+ or not stat.S_ISREG(replaced.st_mode)
1803
+ or _project_path_identity(replaced) != temporary_identity
1804
+ ):
1805
+ raise APError(f"Project file changed after replacement: {relative}")
1806
+ _validate_windows_project_directories(relative, directories)
1807
+ except APError:
1808
+ if temporary is not None:
1809
+ with contextlib.suppress(OSError):
1810
+ temporary.unlink()
1811
+ raise
1812
+ except OSError as exc:
1813
+ if temporary is not None:
1814
+ with contextlib.suppress(OSError):
1815
+ temporary.unlink()
1816
+ raise APError(f"Cannot write project file safely: {relative}") from exc
1817
+ return
1818
+ with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
1819
+ assert parent_fd is not None
1820
+ temporary = f".{leaf}.autocoding-{uuid.uuid4().hex}"
1821
+ descriptor = -1
1822
+ try:
1823
+ descriptor = os.open(
1824
+ temporary,
1825
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
1826
+ 0o644,
1827
+ dir_fd=parent_fd,
1828
+ )
1829
+ with os.fdopen(descriptor, "wb") as handle:
1830
+ descriptor = -1
1831
+ handle.write(payload)
1832
+ handle.flush()
1833
+ os.fsync(handle.fileno())
1834
+ os.replace(temporary, leaf, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
1835
+ except OSError as exc:
1836
+ with contextlib.suppress(OSError):
1837
+ os.unlink(temporary, dir_fd=parent_fd)
1838
+ raise APError(f"Cannot write project file safely: {relative}") from exc
1839
+ finally:
1840
+ if descriptor >= 0:
1841
+ os.close(descriptor)
1842
+
1843
+
1844
+ def _safe_create_project_file(repo: Path, rel: str | Path, payload: bytes) -> None:
1845
+ """Atomically publish a new project file without replacing a concurrent creator."""
1846
+ relative = _safe_project_relative_path(rel)
1847
+ if os.name == "nt":
1848
+ temporary: Path | None = None
1849
+ try:
1850
+ target, directories, _ = _windows_project_path_snapshot(
1851
+ Path(repo),
1852
+ relative,
1853
+ create_parents=True,
1854
+ )
1855
+ _inject_project_file_parent_swap(Path(repo), relative)
1856
+ _validate_windows_project_directories(relative, directories)
1857
+ temporary = target.with_name(f".{target.name}.autocoding-{uuid.uuid4().hex}")
1858
+ with temporary.open("xb") as handle:
1859
+ handle.write(payload)
1860
+ handle.flush()
1861
+ os.fsync(handle.fileno())
1862
+ temporary_metadata = os.fstat(handle.fileno())
1863
+ checked_temporary = temporary.lstat()
1864
+ temporary_identity = _project_path_identity(temporary_metadata)
1865
+ if (
1866
+ not stat.S_ISREG(temporary_metadata.st_mode)
1867
+ or _is_windows_reparse_point(checked_temporary)
1868
+ or not stat.S_ISREG(checked_temporary.st_mode)
1869
+ or _project_path_identity(checked_temporary) != temporary_identity
1870
+ ):
1871
+ raise APError(f"Temporary project file is unsafe: {relative}")
1872
+ _validate_windows_project_directories(relative, directories)
1873
+ try:
1874
+ os.link(temporary, target, follow_symlinks=False)
1875
+ except FileExistsError as exc:
1876
+ raise APError(f"Project file appeared before create-only publish: {relative}") from exc
1877
+ checked_target = target.lstat()
1878
+ if (
1879
+ _is_windows_reparse_point(checked_target)
1880
+ or not stat.S_ISREG(checked_target.st_mode)
1881
+ or _project_path_identity(checked_target) != temporary_identity
1882
+ ):
1883
+ raise APError(f"Project file changed during create-only publish: {relative}")
1884
+ _validate_windows_project_directories(relative, directories)
1885
+ except APError:
1886
+ raise
1887
+ except OSError as exc:
1888
+ raise APError(f"Cannot create project file safely: {relative}") from exc
1889
+ finally:
1890
+ if temporary is not None:
1891
+ with contextlib.suppress(OSError):
1892
+ temporary.unlink()
1893
+ return
1894
+
1895
+ with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
1896
+ assert parent_fd is not None
1897
+ temporary = f".{leaf}.autocoding-{uuid.uuid4().hex}"
1898
+ descriptor = -1
1899
+ try:
1900
+ descriptor = os.open(
1901
+ temporary,
1902
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
1903
+ 0o644,
1904
+ dir_fd=parent_fd,
1905
+ )
1906
+ with os.fdopen(descriptor, "wb") as handle:
1907
+ descriptor = -1
1908
+ handle.write(payload)
1909
+ handle.flush()
1910
+ os.fsync(handle.fileno())
1911
+ temporary_metadata = os.stat(
1912
+ temporary,
1913
+ dir_fd=parent_fd,
1914
+ follow_symlinks=False,
1915
+ )
1916
+ if stat.S_ISLNK(temporary_metadata.st_mode) or not stat.S_ISREG(
1917
+ temporary_metadata.st_mode
1918
+ ):
1919
+ raise APError(f"Temporary project file is unsafe: {relative}")
1920
+ temporary_identity = _project_path_identity(temporary_metadata)
1921
+ try:
1922
+ os.link(
1923
+ temporary,
1924
+ leaf,
1925
+ src_dir_fd=parent_fd,
1926
+ dst_dir_fd=parent_fd,
1927
+ follow_symlinks=False,
1928
+ )
1929
+ except FileExistsError as exc:
1930
+ raise APError(f"Project file appeared before create-only publish: {relative}") from exc
1931
+ published = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
1932
+ if (
1933
+ stat.S_ISLNK(published.st_mode)
1934
+ or not stat.S_ISREG(published.st_mode)
1935
+ or _project_path_identity(published) != temporary_identity
1936
+ ):
1937
+ raise APError(f"Project file changed during create-only publish: {relative}")
1938
+ except APError:
1939
+ raise
1940
+ except OSError as exc:
1941
+ raise APError(f"Cannot create project file safely: {relative}") from exc
1942
+ finally:
1943
+ if descriptor >= 0:
1944
+ os.close(descriptor)
1945
+ with contextlib.suppress(OSError):
1946
+ os.unlink(temporary, dir_fd=parent_fd)
1947
+
1948
+
1949
+ def _safe_chmod_project_file(repo: Path, rel: str | Path, mode: int) -> None:
1950
+ relative = _safe_project_relative_path(rel)
1951
+ if mode < 0 or mode > 0o777:
1952
+ raise APError(f"Project file mode must be between 000 and 777: {relative}")
1953
+ if os.name == "nt":
1954
+ try:
1955
+ target, directories, complete = _windows_project_path_snapshot(
1956
+ Path(repo),
1957
+ relative,
1958
+ create_parents=False,
1959
+ )
1960
+ _inject_project_file_parent_swap(Path(repo), relative)
1961
+ if not complete or not os.path.lexists(target):
1962
+ raise APError(f"Project file is missing: {relative}")
1963
+ metadata = target.lstat()
1964
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
1965
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1966
+ identity = _project_path_identity(metadata)
1967
+ _validate_windows_project_directories(relative, directories)
1968
+ os.chmod(target, mode, follow_symlinks=False)
1969
+ checked = target.lstat()
1970
+ _validate_windows_project_directories(relative, directories)
1971
+ if (
1972
+ _is_windows_reparse_point(checked)
1973
+ or not stat.S_ISREG(checked.st_mode)
1974
+ or _project_path_identity(checked) != identity
1975
+ ):
1976
+ raise APError(f"Project file changed while setting its mode: {relative}")
1977
+ except APError:
1978
+ raise
1979
+ except OSError as exc:
1980
+ raise APError(f"Cannot set project file mode safely: {relative}") from exc
1981
+ return
1982
+
1983
+ with _open_project_parent(repo, relative) as (parent_fd, leaf):
1984
+ if parent_fd is None:
1985
+ raise APError(f"Project file is missing: {relative}")
1986
+ descriptor = -1
1987
+ try:
1988
+ descriptor = os.open(
1989
+ leaf,
1990
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
1991
+ dir_fd=parent_fd,
1992
+ )
1993
+ metadata = os.fstat(descriptor)
1994
+ if not stat.S_ISREG(metadata.st_mode):
1995
+ raise APError(f"Project file must be a regular non-symlink file: {relative}")
1996
+ os.fchmod(descriptor, mode)
1997
+ checked = os.fstat(descriptor)
1998
+ if _project_path_identity(checked) != _project_path_identity(metadata):
1999
+ raise APError(f"Project file changed while setting its mode: {relative}")
2000
+ except APError:
2001
+ raise
2002
+ except OSError as exc:
2003
+ raise APError(f"Cannot set project file mode safely: {relative}") from exc
2004
+ finally:
2005
+ if descriptor >= 0:
2006
+ os.close(descriptor)
2007
+
2008
+
2009
+ _INTERNAL_PROJECT_FILE_MAX_BYTES = 32 * 1024 * 1024
2010
+ _INTERNAL_PROJECT_CHMOD_MAX_BYTES = 1024 * 1024
2011
+ _INTERNAL_PROJECT_CHMOD_MAX_ENTRIES = 4096
2012
+
2013
+
2014
+ def cmd_project_file_safe(args: argparse.Namespace) -> None:
2015
+ repo = Path(args.repo).resolve()
2016
+ operation = _text(args.operation).lower()
2017
+ relative: Path | None = None
2018
+ if operation != "chmod-batch":
2019
+ relative = _safe_project_relative_path(args.path)
2020
+ if operation in {"write", "create"}:
2021
+ assert relative is not None
2022
+ payload = sys.stdin.buffer.read(_INTERNAL_PROJECT_FILE_MAX_BYTES + 1)
2023
+ if len(payload) > _INTERNAL_PROJECT_FILE_MAX_BYTES:
2024
+ raise APError(
2025
+ f"Internal project file payload exceeds {_INTERNAL_PROJECT_FILE_MAX_BYTES} bytes: {relative}"
2026
+ )
2027
+ if operation == "create":
2028
+ _safe_create_project_file(repo, relative, payload)
2029
+ else:
2030
+ _safe_write_project_file(repo, relative, payload)
2031
+ if _text(args.mode):
2032
+ try:
2033
+ mode = int(_text(args.mode), 8)
2034
+ except ValueError as exc:
2035
+ raise APError("Internal project write requires an octal --mode") from exc
2036
+ _safe_chmod_project_file(repo, relative, mode)
2037
+ elif operation == "chmod":
2038
+ assert relative is not None
2039
+ try:
2040
+ mode = int(_text(args.mode), 8)
2041
+ except ValueError as exc:
2042
+ raise APError("Internal project chmod requires an octal --mode") from exc
2043
+ _safe_chmod_project_file(repo, relative, mode)
2044
+ elif operation == "chmod-batch":
2045
+ payload = sys.stdin.buffer.read(_INTERNAL_PROJECT_CHMOD_MAX_BYTES + 1)
2046
+ if len(payload) > _INTERNAL_PROJECT_CHMOD_MAX_BYTES:
2047
+ raise APError("Internal project chmod batch exceeds its size limit")
2048
+ try:
2049
+ entries = json.loads(payload.decode("utf-8"))
2050
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
2051
+ raise APError("Internal project chmod batch must be valid UTF-8 JSON") from exc
2052
+ if not isinstance(entries, list) or len(entries) > _INTERNAL_PROJECT_CHMOD_MAX_ENTRIES:
2053
+ raise APError("Internal project chmod batch has an invalid entry count")
2054
+ mutations: list[tuple[Path, int]] = []
2055
+ for index, entry in enumerate(entries):
2056
+ if not isinstance(entry, dict) or set(entry) != {"path", "mode"}:
2057
+ raise APError(f"Internal project chmod batch entry {index} is invalid")
2058
+ mode_text = entry.get("mode")
2059
+ path_text = entry.get("path")
2060
+ if not isinstance(mode_text, str) or not re.fullmatch(r"[0-7]{3}", mode_text):
2061
+ raise APError(f"Internal project chmod batch entry {index} has an invalid mode")
2062
+ if not isinstance(path_text, str) or not path_text:
2063
+ raise APError(f"Internal project chmod batch entry {index} has an invalid path")
2064
+ mutations.append(
2065
+ (_safe_project_relative_path(path_text), int(mode_text, 8))
2066
+ )
2067
+ for mutation_path, mutation_mode in mutations:
2068
+ _safe_chmod_project_file(repo, mutation_path, mutation_mode)
2069
+ else:
2070
+ raise APError(f"Unsupported internal project file operation: {operation}")
2071
+ if args.json:
2072
+ result = {"operation": operation, "ok": True}
2073
+ if relative is not None:
2074
+ result["path"] = relative.as_posix()
2075
+ else:
2076
+ result["entry_count"] = len(mutations)
2077
+ print(json.dumps(result))
2078
+
2079
+
2080
+ def _directory_handle_identity(handle: int | Path) -> tuple[int, int]:
2081
+ metadata = os.fstat(handle) if isinstance(handle, int) else handle.lstat()
2082
+ if (
2083
+ not stat.S_ISDIR(metadata.st_mode)
2084
+ or (not isinstance(handle, int) and _is_windows_reparse_point(metadata))
2085
+ ):
2086
+ raise APError("Install I/O requires real project directories.")
2087
+ return _project_path_identity(metadata)
2088
+
2089
+
2090
+ def _safe_ensure_project_directory(repo: Path, rel: str | Path) -> None:
2091
+ relative = _safe_project_relative_path(rel)
2092
+ if os.name == "nt":
2093
+ try:
2094
+ target, directories, _ = _windows_project_path_snapshot(
2095
+ Path(repo),
2096
+ relative,
2097
+ create_parents=True,
2098
+ )
2099
+ _validate_windows_project_directories(relative, directories)
2100
+ try:
2101
+ target.mkdir()
2102
+ except FileExistsError:
2103
+ pass
2104
+ metadata = target.lstat()
2105
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
2106
+ raise APError(f"Project directory must be a real directory: {relative}")
2107
+ _validate_windows_project_directories(relative, directories)
2108
+ except APError:
2109
+ raise
2110
+ except OSError as exc:
2111
+ raise APError(f"Cannot create project directory safely: {relative}") from exc
2112
+ return
2113
+ with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
2114
+ assert parent_fd is not None
2115
+ try:
2116
+ os.mkdir(leaf, 0o755, dir_fd=parent_fd)
2117
+ except FileExistsError:
2118
+ pass
2119
+ metadata = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
2120
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
2121
+ raise APError(f"Project directory must be a real directory: {relative}")
2122
+
2123
+
2124
+ def _require_bound_project_directory(
2125
+ repo: Path,
2126
+ relative: Path,
2127
+ handle: int | Path,
2128
+ identity: tuple[int, int],
2129
+ ) -> None:
2130
+ opened = os.fstat(handle) if isinstance(handle, int) else handle.lstat()
2131
+ if not stat.S_ISDIR(opened.st_mode) or _project_path_identity(opened) != identity:
2132
+ raise APError(f"Install I/O directory handle changed: {relative}")
2133
+ target = repo / relative
2134
+ try:
2135
+ current = target.lstat()
2136
+ except OSError as exc:
2137
+ raise APError(f"Install I/O project parent changed: {relative}") from exc
2138
+ if (
2139
+ _is_windows_reparse_point(current)
2140
+ or not stat.S_ISDIR(current.st_mode)
2141
+ or _project_path_identity(current) != identity
2142
+ ):
2143
+ raise APError(f"Install I/O project parent changed: {relative}")
2144
+
2145
+
2146
+ def _inject_install_io_parent_swap(repo: Path, phase: str) -> None:
2147
+ if os.environ.get("AUTOCODING_TEST_MODE") != "1":
2148
+ return
2149
+ if os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_PHASE") != phase:
2150
+ return
2151
+ relative_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_PARENT", "")
2152
+ external_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_EXTERNAL", "")
2153
+ backup_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_BACKUP", "")
2154
+ relative = _safe_project_relative_path(relative_text)
2155
+ target = repo / relative
2156
+ external = Path(external_text)
2157
+ backup = Path(backup_text)
2158
+ if (
2159
+ not external.is_absolute()
2160
+ or not backup.is_absolute()
2161
+ or not external.is_dir()
2162
+ or external.is_symlink()
2163
+ or os.path.lexists(backup)
2164
+ ):
2165
+ raise APError("Invalid install I/O parent-swap test fixture.")
2166
+ target.rename(backup)
2167
+ target.symlink_to(external, target_is_directory=True)
2168
+
2169
+
2170
+ def _open_directory_at(parent_fd: int, name: str) -> int:
2171
+ descriptor = os.open(
2172
+ name,
2173
+ os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
2174
+ dir_fd=parent_fd,
2175
+ )
2176
+ metadata = os.fstat(descriptor)
2177
+ if not stat.S_ISDIR(metadata.st_mode):
2178
+ os.close(descriptor)
2179
+ raise APError(f"Install I/O path must be a real directory: {name}")
2180
+ return descriptor
2181
+
2182
+
2183
+ def _remove_tree_at(parent_fd: int, name: str, *, missing_ok: bool = False) -> None:
2184
+ try:
2185
+ metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
2186
+ except FileNotFoundError:
2187
+ if missing_ok:
2188
+ return
2189
+ raise
2190
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
2191
+ raise APError(f"Install I/O refuses a symlink or non-directory tree: {name}")
2192
+ if not getattr(shutil.rmtree, "avoids_symlink_attacks", False):
2193
+ raise APError("This Python runtime cannot remove project trees without symlink attacks.")
2194
+ shutil.rmtree(name, dir_fd=parent_fd)
2195
+
2196
+
2197
+ def _copy_file_between_fds(
2198
+ source_parent_fd: int,
2199
+ source_name: str,
2200
+ destination_parent_fd: int,
2201
+ destination_name: str,
2202
+ ) -> None:
2203
+ source_fd = -1
2204
+ destination_fd = -1
2205
+ temporary = f".{destination_name}.autocoding-{uuid.uuid4().hex}"
2206
+ try:
2207
+ source_fd = os.open(
2208
+ source_name,
2209
+ os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
2210
+ dir_fd=source_parent_fd,
2211
+ )
2212
+ source_metadata = os.fstat(source_fd)
2213
+ if not stat.S_ISREG(source_metadata.st_mode):
2214
+ raise APError(f"Install I/O source must be a regular file: {source_name}")
2215
+ destination_fd = os.open(
2216
+ temporary,
2217
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
2218
+ stat.S_IMODE(source_metadata.st_mode),
2219
+ dir_fd=destination_parent_fd,
2220
+ )
2221
+ while True:
2222
+ block = os.read(source_fd, 1024 * 1024)
2223
+ if not block:
2224
+ break
2225
+ view = memoryview(block)
2226
+ while view:
2227
+ written = os.write(destination_fd, view)
2228
+ view = view[written:]
2229
+ os.fsync(destination_fd)
2230
+ os.close(destination_fd)
2231
+ destination_fd = -1
2232
+ os.replace(
2233
+ temporary,
2234
+ destination_name,
2235
+ src_dir_fd=destination_parent_fd,
2236
+ dst_dir_fd=destination_parent_fd,
2237
+ )
2238
+ except APError:
2239
+ raise
2240
+ except OSError as exc:
2241
+ raise APError(f"Cannot copy install transaction file safely: {destination_name}") from exc
2242
+ finally:
2243
+ if source_fd >= 0:
2244
+ os.close(source_fd)
2245
+ if destination_fd >= 0:
2246
+ os.close(destination_fd)
2247
+ with contextlib.suppress(OSError):
2248
+ os.unlink(temporary, dir_fd=destination_parent_fd)
2249
+
2250
+
2251
+ def _copy_directory_contents_fd(source_fd: int, destination_fd: int) -> None:
2252
+ for name in sorted(os.listdir(source_fd)):
2253
+ metadata = os.stat(name, dir_fd=source_fd, follow_symlinks=False)
2254
+ if stat.S_ISDIR(metadata.st_mode) and not stat.S_ISLNK(metadata.st_mode):
2255
+ os.mkdir(name, stat.S_IMODE(metadata.st_mode), dir_fd=destination_fd)
2256
+ source_child = _open_directory_at(source_fd, name)
2257
+ destination_child = _open_directory_at(destination_fd, name)
2258
+ try:
2259
+ _copy_directory_contents_fd(source_child, destination_child)
2260
+ finally:
2261
+ os.close(destination_child)
2262
+ os.close(source_child)
2263
+ elif stat.S_ISREG(metadata.st_mode):
2264
+ _copy_file_between_fds(source_fd, name, destination_fd, name)
2265
+ else:
2266
+ raise APError(f"Install I/O refuses a non-regular tree entry: {name}")
2267
+
2268
+
2269
+ def _copy_directory_at(
2270
+ source_parent_fd: int,
2271
+ source_name: str,
2272
+ destination_parent_fd: int,
2273
+ destination_name: str,
2274
+ ) -> None:
2275
+ source_fd = _open_directory_at(source_parent_fd, source_name)
2276
+ destination_fd = -1
2277
+ try:
2278
+ source_metadata = os.fstat(source_fd)
2279
+ os.mkdir(destination_name, stat.S_IMODE(source_metadata.st_mode), dir_fd=destination_parent_fd)
2280
+ destination_fd = _open_directory_at(destination_parent_fd, destination_name)
2281
+ try:
2282
+ _copy_directory_contents_fd(source_fd, destination_fd)
2283
+ except BaseException:
2284
+ os.close(destination_fd)
2285
+ destination_fd = -1
2286
+ with contextlib.suppress(OSError, APError):
2287
+ _remove_tree_at(destination_parent_fd, destination_name, missing_ok=True)
2288
+ raise
2289
+ finally:
2290
+ if destination_fd >= 0:
2291
+ os.close(destination_fd)
2292
+ finally:
2293
+ os.close(source_fd)
2294
+
2295
+
2296
+ def _unlink_file_at(parent_fd: int, name: str, *, missing_ok: bool = False) -> None:
2297
+ try:
2298
+ metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
2299
+ except FileNotFoundError:
2300
+ if missing_ok:
2301
+ return
2302
+ raise
2303
+ if stat.S_ISDIR(metadata.st_mode):
2304
+ raise APError(f"Install I/O refuses to unlink a directory as a file: {name}")
2305
+ os.unlink(name, dir_fd=parent_fd)
2306
+
2307
+
2308
+ def _install_io_owner(repo: Path) -> dict:
2309
+ payload = _safe_read_project_file(
2310
+ repo,
2311
+ _INSTALL_TRANSACTION_RELATIVE / "owner.json",
2312
+ max_bytes=4096,
2313
+ )
2314
+ if payload is None:
2315
+ raise APError("Install I/O requires a valid transaction owner.")
2316
+ try:
2317
+ owner = json.loads(payload.decode("utf-8"))
2318
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
2319
+ raise APError("Install I/O transaction owner is invalid.") from exc
2320
+ return _mapping(owner)
2321
+
2322
+
2323
+ def _require_install_io_access(repo: Path, operation: str) -> None:
2324
+ owner = _install_io_owner(repo)
2325
+ token = os.environ.get("AUTOCODING_INSTALL_TRANSACTION_TOKEN", "")
2326
+ expected = _text(owner.get("token_sha256"))
2327
+ if re.fullmatch(r"[0-9a-f]{64}", token) and re.fullmatch(r"[0-9a-f]{64}", expected):
2328
+ actual = hashlib.sha256(token.encode("ascii")).hexdigest()
2329
+ if hmac.compare_digest(actual, expected):
2330
+ return
2331
+ if operation in {"recover", "complete"}:
2332
+ try:
2333
+ pid = int(owner.get("pid"))
2334
+ os.kill(pid, 0)
2335
+ except ProcessLookupError:
2336
+ return
2337
+ except PermissionError as exc:
2338
+ raise APError("Install I/O recovery owner is still active.") from exc
2339
+ except (TypeError, ValueError, OSError) as exc:
2340
+ raise APError("Install I/O recovery owner cannot be verified.") from exc
2341
+ raise APError("Install I/O recovery owner is still active.")
2342
+ raise APError("Install I/O requires the active installer token.")
2343
+
2344
+
2345
+ def _cmd_install_io_posix(args: argparse.Namespace, repo: Path) -> None:
2346
+ operation = _text(args.operation).lower()
2347
+ if operation in {"switch", "recover"}:
2348
+ _safe_ensure_project_directory(repo, Path(".agents/skills"))
2349
+ if operation == "recover":
2350
+ _safe_ensure_project_directory(repo, Path("docs"))
2351
+ with contextlib.ExitStack() as stack:
2352
+ agents = stack.enter_context(_open_project_directory(repo, Path(".agents")))
2353
+ transaction = stack.enter_context(
2354
+ _open_project_directory(repo, _INSTALL_TRANSACTION_RELATIVE)
2355
+ )
2356
+ if not isinstance(agents, int) or not isinstance(transaction, int):
2357
+ raise APError("Install I/O project directories are missing.")
2358
+ bindings: list[tuple[Path, int, tuple[int, int]]] = [
2359
+ (Path(".agents"), agents, _directory_handle_identity(agents)),
2360
+ (_INSTALL_TRANSACTION_RELATIVE, transaction, _directory_handle_identity(transaction)),
2361
+ ]
2362
+ skills: int | None = None
2363
+ docs: int | None = None
2364
+ if operation in {"switch", "recover"}:
2365
+ skills = stack.enter_context(_open_project_directory(repo, Path(".agents/skills")))
2366
+ if not isinstance(skills, int):
2367
+ raise APError("Install I/O skills directory is missing.")
2368
+ bindings.append((Path(".agents/skills"), skills, _directory_handle_identity(skills)))
2369
+ if operation == "recover":
2370
+ docs = stack.enter_context(_open_project_directory(repo, Path("docs")))
2371
+ if not isinstance(docs, int):
2372
+ raise APError("Install I/O docs directory is missing.")
2373
+ bindings.append((Path("docs"), docs, _directory_handle_identity(docs)))
2374
+
2375
+ _inject_install_io_parent_swap(repo, operation)
2376
+ for relative, handle, identity in bindings:
2377
+ _require_bound_project_directory(repo, relative, handle, identity)
2378
+
2379
+ if operation == "switch":
2380
+ assert skills is not None
2381
+ _remove_tree_at(skills, "auto-coding-skill", missing_ok=True)
2382
+ os.rename(
2383
+ "new-skill",
2384
+ "auto-coding-skill",
2385
+ src_dir_fd=transaction,
2386
+ dst_dir_fd=skills,
2387
+ )
2388
+ _copy_file_between_fds(transaction, "new-manifest.json", agents, "managed-install.json")
2389
+ elif operation == "recover":
2390
+ assert skills is not None and docs is not None
2391
+ _remove_tree_at(skills, "auto-coding-skill", missing_ok=True)
2392
+ if args.old_skill_present:
2393
+ _copy_directory_at(transaction, "old-skill", skills, "auto-coding-skill")
2394
+ if args.old_manifest_present:
2395
+ _copy_file_between_fds(transaction, "old-manifest.json", agents, "managed-install.json")
2396
+ else:
2397
+ _unlink_file_at(agents, "managed-install.json", missing_ok=True)
2398
+ if args.old_engineering_present:
2399
+ _copy_file_between_fds(transaction, "old-ENGINEERING.md", docs, "ENGINEERING.md")
2400
+ else:
2401
+ _unlink_file_at(docs, "ENGINEERING.md", missing_ok=True)
2402
+ elif operation == "complete":
2403
+ completed = f".auto-coding-skill-install-completed-{os.getpid()}-{uuid.uuid4().hex}"
2404
+ os.rename(
2405
+ _INSTALL_TRANSACTION_RELATIVE.name,
2406
+ completed,
2407
+ src_dir_fd=agents,
2408
+ dst_dir_fd=agents,
2409
+ )
2410
+ _remove_tree_at(agents, completed)
2411
+ else:
2412
+ raise APError(f"Unsupported install I/O operation: {operation}")
2413
+
2414
+
2415
+ def _cmd_install_io_windows(args: argparse.Namespace, repo: Path) -> None:
2416
+ operation = _text(args.operation).lower()
2417
+ if operation in {"switch", "recover"}:
2418
+ _safe_ensure_project_directory(repo, Path(".agents/skills"))
2419
+ if operation == "recover":
2420
+ _safe_ensure_project_directory(repo, Path("docs"))
2421
+ transaction = repo / _INSTALL_TRANSACTION_RELATIVE
2422
+ skills = repo / ".agents" / "skills"
2423
+ agents = repo / ".agents"
2424
+ docs = repo / "docs"
2425
+ snapshots: list[tuple[Path, tuple[int, int]]] = []
2426
+ for directory in [agents, transaction, *([skills] if operation in {"switch", "recover"} else []), *([docs] if operation == "recover" else [])]:
2427
+ metadata = directory.lstat()
2428
+ if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
2429
+ raise APError(f"Install I/O project directory is unsafe: {directory.relative_to(repo)}")
2430
+ snapshots.append((directory, _project_path_identity(metadata)))
2431
+ _inject_install_io_parent_swap(repo, operation)
2432
+
2433
+ def validate() -> None:
2434
+ for directory, identity in snapshots:
2435
+ metadata = directory.lstat()
2436
+ if (
2437
+ _is_windows_reparse_point(metadata)
2438
+ or not stat.S_ISDIR(metadata.st_mode)
2439
+ or _project_path_identity(metadata) != identity
2440
+ ):
2441
+ raise APError(f"Install I/O project parent changed: {directory.relative_to(repo)}")
2442
+
2443
+ validate()
2444
+ if operation == "switch":
2445
+ target = skills / "auto-coding-skill"
2446
+ if os.path.lexists(target):
2447
+ shutil.rmtree(target)
2448
+ os.replace(transaction / "new-skill", target)
2449
+ _safe_write_project_file(repo, Path(".agents/managed-install.json"), (transaction / "new-manifest.json").read_bytes())
2450
+ elif operation == "recover":
2451
+ target = skills / "auto-coding-skill"
2452
+ if os.path.lexists(target):
2453
+ shutil.rmtree(target)
2454
+ if args.old_skill_present:
2455
+ shutil.copytree(transaction / "old-skill", target, symlinks=True)
2456
+ if args.old_manifest_present:
2457
+ _safe_write_project_file(repo, Path(".agents/managed-install.json"), (transaction / "old-manifest.json").read_bytes())
2458
+ elif os.path.lexists(agents / "managed-install.json"):
2459
+ (agents / "managed-install.json").unlink()
2460
+ if args.old_engineering_present:
2461
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), (transaction / "old-ENGINEERING.md").read_bytes())
2462
+ elif os.path.lexists(docs / "ENGINEERING.md"):
2463
+ (docs / "ENGINEERING.md").unlink()
2464
+ elif operation == "complete":
2465
+ completed = agents / f".auto-coding-skill-install-completed-{os.getpid()}-{uuid.uuid4().hex}"
2466
+ os.replace(transaction, completed)
2467
+ shutil.rmtree(completed)
2468
+ else:
2469
+ raise APError(f"Unsupported install I/O operation: {operation}")
2470
+ validate()
2471
+
2472
+
2473
+ def cmd_install_io(args: argparse.Namespace) -> None:
2474
+ repo = Path(args.repo).resolve()
2475
+ operation = _text(args.operation).lower()
2476
+ _require_install_io_access(repo, operation)
2477
+ if os.name == "nt":
2478
+ _cmd_install_io_windows(args, repo)
2479
+ else:
2480
+ _cmd_install_io_posix(args, repo)
2481
+ if args.json:
2482
+ print(json.dumps({"operation": operation, "ok": True}))
2483
+
2484
+
2485
+ def _managed_scaffold_convergence(
2486
+ repo: Path,
2487
+ selected: dict[str, str],
2488
+ version: str,
2489
+ *,
2490
+ write: bool,
2491
+ ) -> list[dict]:
2492
+ actions: list[dict] = []
2493
+ for rel, canonical in sorted(selected.items()):
2494
+ if rel not in MANAGED_FRAMEWORK_DOCS:
2495
+ continue
2496
+ current = _safe_read_project_file(repo, rel)
2497
+ expected = canonical.encode("utf-8")
2498
+ if current == expected:
2499
+ continue
2500
+ if current is not None:
2501
+ archive_rel, archive_required = _select_project_archive_target(
2502
+ repo,
2503
+ Path(".agents") / "archive" / "auto-coding-skill" / version / rel,
2504
+ current,
2505
+ legacy_digest_payload=current,
2506
+ )
2507
+ if archive_required:
2508
+ actions.append({"action": "archive", "path": archive_rel.as_posix()})
2509
+ if write:
2510
+ _safe_create_project_file(repo, archive_rel, current)
2511
+ actions.append({"action": "create" if current is None else "replace", "path": rel})
2512
+ if write:
2513
+ _safe_write_project_file(repo, rel, expected)
2514
+ return actions
2515
+
2516
+
2517
+ def _is_allowed_project_doc(rel: Path, candidate: Path | None = None) -> bool:
2518
+ if rel == _PROJECT_CONFIG_RELATIVE:
2519
+ return candidate is None or (candidate.is_file() and not candidate.is_symlink())
2520
+ if any(rel.match(pattern) for pattern in PROJECT_FEEDBACK_PATTERNS):
2521
+ return candidate is None or (candidate.is_file() and not candidate.is_symlink())
1109
2522
  return any(rel.match(pattern) for pattern in _PROJECT_ARTIFACT_PATTERNS)
1110
2523
 
1111
2524
 
@@ -1113,44 +2526,48 @@ def cmd_project_converge(args: argparse.Namespace) -> None:
1113
2526
  repo = Path(args.repo).resolve()
1114
2527
  template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
1115
2528
  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
2529
+ config_plan = _project_config_convergence_plan(repo, template)
2530
+ output = config_plan["engineering_output"]
2531
+ current = config_plan["engineering_current"]
2532
+ changed = current != output
1126
2533
  actions: list[dict] = []
1127
2534
  version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
2535
+ managed_templates = templates_for("all")
2536
+ managed_plan = _managed_scaffold_convergence(repo, managed_templates, version, write=False)
1128
2537
 
1129
2538
  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():
2539
+ archive = (
2540
+ Path(".agents") / "archive" / "auto-coding-skill" / version
2541
+ / source_path.relative_to(repo)
2542
+ )
2543
+ content_bytes = content.encode("utf-8")
2544
+ archive, archive_required = _select_project_archive_target(
2545
+ repo,
2546
+ archive,
2547
+ content_bytes,
2548
+ legacy_digest_payload=content_bytes,
2549
+ )
2550
+ if not archive_required:
1136
2551
  return
1137
- actions.append({"action": "archive", "path": _repo_rel(repo, archive), "detail": label})
2552
+ actions.append({"action": "archive", "path": archive.as_posix(), "detail": label})
1138
2553
  if args.write:
1139
- archive.parent.mkdir(parents=True, exist_ok=True)
1140
- archive.write_text(content, encoding="utf-8")
2554
+ _safe_create_project_file(repo, archive, content_bytes)
1141
2555
 
1142
2556
  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})
2557
+ source_rel = source_path.relative_to(repo)
2558
+ content = _safe_read_project_file(repo, source_rel)
2559
+ if content is None:
2560
+ raise APError(f"Project file disappeared during convergence: {source_rel.as_posix()}")
2561
+ archive, archive_required = _select_project_archive_target(
2562
+ repo,
2563
+ Path(".agents") / "archive" / "auto-coding-skill" / version / source_rel,
2564
+ content,
2565
+ legacy_digest_payload=content,
2566
+ )
2567
+ if archive_required:
2568
+ actions.append({"action": "archive", "path": archive.as_posix(), "detail": label})
1151
2569
  if args.write:
1152
- archive.parent.mkdir(parents=True, exist_ok=True)
1153
- archive.write_bytes(content)
2570
+ _safe_create_project_file(repo, archive, content)
1154
2571
 
1155
2572
  if changed and current:
1156
2573
  archive_header = (
@@ -1158,18 +2575,38 @@ def cmd_project_converge(args: argparse.Namespace) -> None:
1158
2575
  "Historical and non-authoritative. Do not use this file as workflow policy.\n\n---\n\n"
1159
2576
  )
1160
2577
  archive_previous(engineering, archive_header + current, "previous project configuration")
2578
+ if config_plan["overlay_output"] is not None:
2579
+ actions.append({
2580
+ "action": "create",
2581
+ "path": _PROJECT_CONFIG_RELATIVE.as_posix(),
2582
+ "detail": (
2583
+ "project-owned effective-config overlay; migrated "
2584
+ f"{len(config_plan['migrated_paths'])} value paths"
2585
+ ),
2586
+ })
2587
+ if args.write:
2588
+ _safe_create_project_file(
2589
+ repo,
2590
+ _PROJECT_CONFIG_RELATIVE,
2591
+ config_plan["overlay_output"],
2592
+ )
1161
2593
  if changed:
1162
2594
  actions.append({
1163
2595
  "action": "create" if not current else "replace",
1164
2596
  "path": "docs/ENGINEERING.md",
1165
2597
  })
1166
2598
  if args.write:
1167
- engineering.parent.mkdir(parents=True, exist_ok=True)
1168
- engineering.write_text(output, encoding="utf-8")
2599
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), output.encode("utf-8"))
1169
2600
 
1170
2601
  for rel, canonical in sorted(templates_for("all").items()):
2602
+ if rel in MANAGED_FRAMEWORK_DOCS:
2603
+ continue
1171
2604
  target = repo / rel
1172
- existing = target.read_text(encoding="utf-8") if target.exists() else ""
2605
+ existing_payload = _safe_read_project_file(repo, rel)
2606
+ try:
2607
+ existing = existing_payload.decode("utf-8") if existing_payload is not None else ""
2608
+ except UnicodeDecodeError as exc:
2609
+ raise APError(f"Project documentation must be UTF-8: {rel}") from exc
1173
2610
  managed = rel in MANAGED_FRAMEWORK_DOCS
1174
2611
  if existing and (not managed or existing == canonical):
1175
2612
  continue
@@ -1177,12 +2614,18 @@ def cmd_project_converge(args: argparse.Namespace) -> None:
1177
2614
  archive_previous(target, existing, "previous managed documentation template")
1178
2615
  actions.append({"action": "create" if not existing else "replace", "path": rel})
1179
2616
  if args.write:
1180
- target.parent.mkdir(parents=True, exist_ok=True)
1181
- target.write_text(canonical, encoding="utf-8")
2617
+ _safe_write_project_file(repo, rel, canonical.encode("utf-8"))
2618
+
2619
+ actions.extend(
2620
+ _managed_scaffold_convergence(repo, managed_templates, version, write=True)
2621
+ if args.write
2622
+ else managed_plan
2623
+ )
1182
2624
 
1183
2625
  allowed_docs = {
1184
2626
  Path("docs/ENGINEERING.md"),
1185
2627
  Path("docs/tools/autopipeline/ap.py"),
2628
+ _PROJECT_CONFIG_RELATIVE,
1186
2629
  *(Path(rel) for rel in templates_for("all")),
1187
2630
  }
1188
2631
  docs_root = repo / "docs"
@@ -1191,7 +2634,16 @@ def cmd_project_converge(args: argparse.Namespace) -> None:
1191
2634
  if not candidate.is_file() and not candidate.is_symlink():
1192
2635
  continue
1193
2636
  rel = candidate.relative_to(repo)
1194
- if rel in allowed_docs or _is_allowed_project_doc(rel):
2637
+ if rel in allowed_docs or _is_allowed_project_doc(rel, candidate):
2638
+ continue
2639
+ if candidate.is_symlink() and any(rel.match(pattern) for pattern in PROJECT_FEEDBACK_PATTERNS):
2640
+ actions.append({
2641
+ "action": "delete",
2642
+ "path": rel.as_posix(),
2643
+ "detail": "feedback reports must be regular non-symlink Markdown files",
2644
+ })
2645
+ if args.write:
2646
+ candidate.unlink()
1195
2647
  continue
1196
2648
  archive_extra(candidate, "removed from the exact docs framework")
1197
2649
  actions.append({"action": "delete", "path": rel.as_posix()})
@@ -1218,119 +2670,6 @@ def cmd_project_converge(args: argparse.Namespace) -> None:
1218
2670
  print("[project-converge] OK: already current")
1219
2671
 
1220
2672
 
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")
1322
-
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
-
1331
- return changed
1332
-
1333
-
1334
2673
  def cmd_scaffold(args: argparse.Namespace) -> None:
1335
2674
  repo = Path(args.repo).resolve()
1336
2675
  group = str(args.group or "").strip().lower()
@@ -1344,15 +2683,14 @@ def cmd_scaffold(args: argparse.Namespace) -> None:
1344
2683
  force = bool(args.force)
1345
2684
  actions: list[dict] = []
1346
2685
  for rel, content in sorted(selected.items()):
1347
- path = repo / rel
1348
- if path.exists() and not force:
2686
+ current = _safe_read_project_file(repo, rel)
2687
+ if current is not None and not force:
1349
2688
  actions.append({"path": rel, "action": "exists"})
1350
2689
  continue
1351
2690
  action = "write" if write else "would-write"
1352
2691
  actions.append({"path": rel, "action": action})
1353
2692
  if write:
1354
- path.parent.mkdir(parents=True, exist_ok=True)
1355
- path.write_text(content, encoding="utf-8")
2693
+ _safe_write_project_file(repo, rel, content.encode("utf-8"))
1356
2694
 
1357
2695
  result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
1358
2696
  if args.json:
@@ -1364,11 +2702,160 @@ def cmd_scaffold(args: argparse.Namespace) -> None:
1364
2702
  print("[scaffold] plan only; re-run with --write to create missing files")
1365
2703
 
1366
2704
 
2705
+ def cmd_managed_scaffold_converge(args: argparse.Namespace) -> None:
2706
+ repo = Path(args.repo).resolve()
2707
+ group = str(args.group or "").strip().lower()
2708
+ selected = templates_for(group)
2709
+ write = bool(args.write)
2710
+ template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
2711
+ version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
2712
+ actions = _managed_scaffold_convergence(repo, selected, version, write=write)
2713
+ result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
2714
+ if args.json:
2715
+ print(json.dumps(result, ensure_ascii=False, indent=2))
2716
+ return
2717
+ for item in actions:
2718
+ print(f"[managed-scaffold-converge] {item['action']}: {item['path']}")
2719
+
2720
+
2721
+ _CONFIG_STATUS_FIELDS: tuple[tuple[str, tuple[str, ...], bool, bool], ...] = (
2722
+ ("workflow.skill_version", ("workflow", "skill_version"), False, True),
2723
+ ("workflow.mode", ("workflow", "mode"), False, True),
2724
+ ("workflow.profile", ("workflow", "profile"), False, True),
2725
+ ("workflow.completion", ("workflow", "completion"), False, True),
2726
+ ("project.name", ("project", "name"), False, True),
2727
+ ("concurrency.isolation", ("concurrency", "isolation"), False, True),
2728
+ ("concurrency.base_ref", ("concurrency", "base_ref"), False, True),
2729
+ ("concurrency.target_branch", ("concurrency", "target_branch"), False, True),
2730
+ ("concurrency.branch_prefix", ("concurrency", "branch_prefix"), False, True),
2731
+ ("concurrency.worktree_root", ("concurrency", "worktree_root"), False, True),
2732
+ ("concurrency.cleanup_merged", ("concurrency", "cleanup_merged"), False, True),
2733
+ ("concurrency.delete_remote_branch", ("concurrency", "delete_remote_branch"), False, True),
2734
+ ("concurrency.disposable_ignored", ("concurrency", "disposable_ignored"), True, False),
2735
+ ("validation.on_unmapped", ("validation", "on_unmapped"), False, True),
2736
+ ("validation.max_command_seconds", ("validation", "max_command_seconds"), False, True),
2737
+ ("validation.max_total_seconds", ("validation", "max_total_seconds"), False, True),
2738
+ ("validation.routes", ("validation", "routes"), True, False),
2739
+ ("risk.rules", ("risk", "rules"), True, False),
2740
+ ("docs.framework", ("docs", "framework"), False, True),
2741
+ ("access.project.frontend.url", ("access", "project", "frontend", "url"), False, False),
2742
+ ("access.project.frontend.username", ("access", "project", "frontend", "username"), False, False),
2743
+ ("access.project.frontend.password", ("access", "project", "frontend", "password"), False, False),
2744
+ ("access.project.backend.url", ("access", "project", "backend", "url"), False, False),
2745
+ ("access.project.backend.username", ("access", "project", "backend", "username"), False, False),
2746
+ ("access.project.backend.password", ("access", "project", "backend", "password"), False, False),
2747
+ ("access.jenkins.frontend.url", ("access", "jenkins", "frontend", "url"), False, False),
2748
+ ("access.jenkins.frontend.username", ("access", "jenkins", "frontend", "username"), False, False),
2749
+ ("access.jenkins.frontend.password", ("access", "jenkins", "frontend", "password"), False, False),
2750
+ ("access.jenkins.backend.url", ("access", "jenkins", "backend", "url"), False, False),
2751
+ ("access.jenkins.backend.username", ("access", "jenkins", "backend", "username"), False, False),
2752
+ ("access.jenkins.backend.password", ("access", "jenkins", "backend", "password"), False, False),
2753
+ ("access.gitlab.url", ("access", "gitlab", "url"), False, False),
2754
+ ("access.gitlab.username", ("access", "gitlab", "username"), False, False),
2755
+ ("access.gitlab.password", ("access", "gitlab", "password"), False, False),
2756
+ ("access.nexus.frontend.url", ("access", "nexus", "frontend", "url"), False, False),
2757
+ ("access.nexus.frontend.username", ("access", "nexus", "frontend", "username"), False, False),
2758
+ ("access.nexus.frontend.password", ("access", "nexus", "frontend", "password"), False, False),
2759
+ )
2760
+
2761
+
2762
+ def _config_value(cfg: dict, path: tuple[str, ...]) -> tuple[bool, object]:
2763
+ current: object = cfg
2764
+ for key in path:
2765
+ if not isinstance(current, dict) or key not in current:
2766
+ return False, ""
2767
+ current = current[key]
2768
+ return True, current
2769
+
2770
+
2771
+ def _config_status_report(repo: Path) -> dict:
2772
+ cfg = load_effective_config(repo)
2773
+ fields: dict[str, dict] = {}
2774
+ for label, path, sequence, expose_value in _CONFIG_STATUS_FIELDS:
2775
+ present, value = _config_value(cfg, path)
2776
+ if label.startswith("access.") or label in {"project.name", "docs.framework"}:
2777
+ configured = isinstance(value, str) and _is_explicit_fill(value)
2778
+ elif sequence:
2779
+ configured = isinstance(value, list) and bool(value)
2780
+ else:
2781
+ configured = bool(present and (
2782
+ len(value) > 0 if isinstance(value, (list, dict, str)) else value is not None
2783
+ ))
2784
+ state = {
2785
+ "present": present,
2786
+ "configured": bool(present and configured),
2787
+ }
2788
+ if sequence:
2789
+ state["item_count"] = len(value) if isinstance(value, list) else -1
2790
+ if expose_value and present and isinstance(value, (str, bool, int, float)):
2791
+ state["value"] = value
2792
+ fields[label] = state
2793
+ commands = _mapping(cfg.get("commands"))
2794
+ overlay_payload = _safe_read_project_file(
2795
+ repo,
2796
+ _PROJECT_CONFIG_RELATIVE,
2797
+ max_bytes=128 * 1024,
2798
+ )
2799
+ contract = cmd_doctor(
2800
+ argparse.Namespace(repo=str(repo), collect=True, quiet=True, record=False)
2801
+ )
2802
+ report = {
2803
+ "schema": "auto-coding-skill/effective-config-status/v1",
2804
+ "managed_version": _text(_mapping(cfg.get("workflow")).get("skill_version")),
2805
+ "project_overlay": {
2806
+ "path": _PROJECT_CONFIG_RELATIVE.as_posix(),
2807
+ "present": overlay_payload is not None,
2808
+ "schema": PROJECT_CONFIG_SCHEMA if overlay_payload is not None else "",
2809
+ },
2810
+ "project": {"name": _text(_mapping(cfg.get("project")).get("name"))},
2811
+ "fields": fields,
2812
+ "commands": {
2813
+ "configured_names": sorted(
2814
+ str(name)
2815
+ for name, value in commands.items()
2816
+ if isinstance(name, str) and isinstance(value, str) and value.strip()
2817
+ )
2818
+ },
2819
+ "risk_rule_count": len(_mapping(cfg.get("risk")).get("rules") or [])
2820
+ if isinstance(_mapping(cfg.get("risk")).get("rules") or [], list)
2821
+ else -1,
2822
+ "validation_route_count": len(_mapping(cfg.get("validation")).get("routes") or [])
2823
+ if isinstance(_mapping(cfg.get("validation")).get("routes") or [], list)
2824
+ else -1,
2825
+ "policy_issues": _workflow_policy_issues(repo, cfg),
2826
+ "contract_valid": not bool(contract["issues"]),
2827
+ "contract_issues": contract["issues"],
2828
+ "contract_advisories": contract["advisories"],
2829
+ }
2830
+ canonical = json.dumps(report, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
2831
+ report["redacted_sha256"] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
2832
+ return report
2833
+
2834
+
2835
+ def cmd_config_effective(args: argparse.Namespace) -> None:
2836
+ report = _config_status_report(Path(args.repo).resolve())
2837
+ if args.json:
2838
+ print(json.dumps(report, ensure_ascii=False, indent=2))
2839
+ return
2840
+ print(f"[config] managed_version={report['managed_version'] or '(missing)'}")
2841
+ print(
2842
+ "[config] project_overlay="
2843
+ + ("valid" if report["project_overlay"]["present"] else "missing")
2844
+ )
2845
+ print(f"[config] project={report['project']['name'] or '(missing)'}")
2846
+ print(f"[config] contract_valid={str(report['contract_valid']).lower()}")
2847
+ print(f"[config] redacted_sha256={report['redacted_sha256']}")
2848
+
2849
+
1367
2850
  def cmd_install(args: argparse.Namespace) -> None:
1368
2851
  repo = Path(args.repo).resolve()
1369
2852
  templates = _skill_root() / "data" / "templates"
2853
+ config_convergence = _project_config_convergence_plan(
2854
+ repo,
2855
+ templates / "ENGINEERING.md",
2856
+ )
1370
2857
 
1371
- planned_copies = [(templates / "ENGINEERING.md", repo / "docs" / "ENGINEERING.md")]
2858
+ planned_copies: list[tuple[Path, Path]] = []
1372
2859
  for rel in _CORE_DOC_TEMPLATES:
1373
2860
  planned_copies.append((templates / "docs" / rel, repo / "docs" / rel))
1374
2861
 
@@ -1378,23 +2865,45 @@ def cmd_install(args: argparse.Namespace) -> None:
1378
2865
  tools_dir = repo / "docs" / "tools" / "autopipeline"
1379
2866
  planned_copies.append((templates / "tools" / "ap.py", tools_dir / "ap.py"))
1380
2867
 
1381
- conflicts: list[Path] = []
2868
+ engineering = repo / "docs" / "ENGINEERING.md"
2869
+ conflicts: list[Path] = [engineering] if config_convergence["engineering_current"] else []
2870
+ planned_files: list[tuple[Path, Path]] = []
1382
2871
  for src, dst in planned_copies:
1383
- conflicts.extend(_copy_conflicts(src, dst))
2872
+ if src.is_file():
2873
+ planned_files.append((src, dst))
2874
+ continue
2875
+ for source_file in _iter_files(src):
2876
+ planned_files.append((source_file, dst / source_file.relative_to(src)))
2877
+ for _, dst in planned_files:
2878
+ if _safe_read_project_file(repo, dst.relative_to(repo)) is not None:
2879
+ conflicts.append(dst)
1384
2880
  if conflicts and not args.force:
1385
2881
  conflict_list = "\n".join(f"- {_repo_rel(repo, path)}" for path in conflicts[:20])
1386
2882
  extra = "" if len(conflicts) <= 20 else f"\n- ... and {len(conflicts) - 20} more"
1387
2883
  raise APError(
1388
2884
  "Install would overwrite existing files:\n"
1389
2885
  f"{conflict_list}{extra}\n"
1390
- "For existing projects, run `ap.py upgrade --dry-run` then `ap.py upgrade --write`. "
2886
+ "For existing projects, run `autocoding init` or an explicit `autocoding sync`. "
1391
2887
  "Use `install --force` only when intentionally resetting generated docs/tooling."
1392
2888
  )
1393
2889
 
1394
- for src, dst in planned_copies:
1395
- copy_tree(src, dst)
2890
+ for src, dst in planned_files:
2891
+ _safe_write_project_file(repo, dst.relative_to(repo), src.read_bytes())
1396
2892
 
1397
- _initialize_engineering_defaults(repo / "docs" / "ENGINEERING.md", repo)
2893
+ if config_convergence["overlay_output"] is not None:
2894
+ _safe_create_project_file(
2895
+ repo,
2896
+ _PROJECT_CONFIG_RELATIVE,
2897
+ config_convergence["overlay_output"],
2898
+ )
2899
+ _safe_write_project_file(
2900
+ repo,
2901
+ Path("docs/ENGINEERING.md"),
2902
+ config_convergence["engineering_output"].encode("utf-8"),
2903
+ )
2904
+ cmd_scaffold(
2905
+ argparse.Namespace(repo=str(repo), group="feedback", write=True, force=args.force, json=False)
2906
+ )
1398
2907
  if args.full:
1399
2908
  cmd_scaffold(
1400
2909
  argparse.Namespace(repo=str(repo), group="all", write=True, force=args.force, json=False)
@@ -1404,7 +2913,7 @@ def cmd_install(args: argparse.Namespace) -> None:
1404
2913
  print(f"[install] OK: {layout} scaffold installed into {repo}")
1405
2914
  print(
1406
2915
  "[install] Next: fill every access.* URL, username, and password in "
1407
- "docs/ENGINEERING.md, run doctor, and commit that file into Git."
2916
+ "docs/project/auto-coding-skill.yaml, run doctor, and commit that file into Git."
1408
2917
  )
1409
2918
 
1410
2919
 
@@ -1412,11 +2921,25 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1412
2921
  repo = Path(args.repo).resolve()
1413
2922
  ensure_git_repo(repo)
1414
2923
  write = bool(args.write) and not bool(args.dry_run)
2924
+ if write:
2925
+ raise APError(
2926
+ "Project-local `ap.py upgrade --write` was retired in favor of the "
2927
+ "transactional installer. Run `autocoding init` for one project or "
2928
+ "`autocoding sync --projects <path[,path...]>` for explicit projects. "
2929
+ "Use `ap.py upgrade --dry-run` only as a read-only legacy diagnostic."
2930
+ )
1415
2931
  source_root = _find_skill_asset_root(repo)
1416
2932
  templates = source_root / "data" / "templates"
1417
2933
  template_engineering = templates / "ENGINEERING.md"
1418
2934
  template_agents = templates / "bridges" / "AGENTS.md"
1419
2935
  actions: list[dict] = []
2936
+ managed_version = _text(
2937
+ _mapping(_read_frontmatter_markdown(template_engineering)[0].get("workflow")).get("skill_version")
2938
+ ) or "current"
2939
+ feedback_templates = templates_for("feedback")
2940
+ feedback_plan = _managed_scaffold_convergence(
2941
+ repo, feedback_templates, managed_version, write=False
2942
+ )
1420
2943
 
1421
2944
  registry = _task_state_root(repo) / "tasks"
1422
2945
  active_manifests = sorted(registry.glob("*.json")) if registry.exists() else []
@@ -1428,6 +2951,8 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1428
2951
  "workflow semantics must not change mid-task."
1429
2952
  )
1430
2953
 
2954
+ config_convergence = _project_config_convergence_plan(repo, template_engineering)
2955
+
1431
2956
  def add_action(kind: str, path: Path, action: str, detail: str = "") -> None:
1432
2957
  actions.append({
1433
2958
  "kind": kind,
@@ -1477,20 +3002,21 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1477
3002
  archive_header = (
1478
3003
  f"# Archived ENGINEERING.md before auto-coding-skill {version} docs convergence\n\n"
1479
3004
  "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"
3005
+ "were removed from docs/ENGINEERING.md. Move still-current configuration into\n"
3006
+ "docs/project/auto-coding-skill.yaml and durable facts into docs/project/.\n\n---\n\n"
1482
3007
  )
1483
3008
  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():
3009
+ archive_rel, archive_required = _select_project_archive_target(
3010
+ repo,
3011
+ Path("docs/archive/workflow") / f"ENGINEERING.pre-{version}.md",
3012
+ archive_content.encode("utf-8"),
3013
+ legacy_digest_payload=engineering_plan["original"].encode("utf-8"),
3014
+ )
3015
+ archive = repo / archive_rel
3016
+ if archive_required:
1490
3017
  add_action("policy", archive, "archive", "before duplicate workflow section cleanup")
1491
3018
  if write:
1492
- archive.parent.mkdir(parents=True, exist_ok=True)
1493
- archive.write_text(archive_content, encoding="utf-8")
3019
+ _safe_create_project_file(repo, archive_rel, archive_content.encode("utf-8"))
1494
3020
 
1495
3021
  tool_files = [
1496
3022
  (
@@ -1543,23 +3069,24 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1543
3069
  current_agents = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
1544
3070
  if canonical_agents and current_agents != canonical_agents:
1545
3071
  if current_agents:
1546
- archive_dir = repo / "docs" / "archive" / "workflow"
1547
3072
  archive_header = (
1548
- "# Archived AGENTS.md before auto-coding-skill 4.2.8\n\n"
3073
+ "# Archived AGENTS.md before auto-coding-skill 4.3.0\n\n"
1549
3074
  "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"
3075
+ "Move project configuration into docs/project/auto-coding-skill.yaml and facts into docs/project/,\n"
1551
3076
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
1552
3077
  )
1553
3078
  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():
3079
+ archive_rel, archive_required = _select_project_archive_target(
3080
+ repo,
3081
+ Path("docs/archive/workflow/AGENTS.pre-4.3.0.md"),
3082
+ archive_content.encode("utf-8"),
3083
+ legacy_digest_payload=current_agents.encode("utf-8"),
3084
+ )
3085
+ archive = repo / archive_rel
3086
+ if archive_required:
1559
3087
  add_action("policy", archive, "archive", "historical and non-authoritative")
1560
3088
  if write:
1561
- archive.parent.mkdir(parents=True, exist_ok=True)
1562
- archive.write_text(archive_content, encoding="utf-8")
3089
+ _safe_create_project_file(repo, archive_rel, archive_content.encode("utf-8"))
1563
3090
  add_action("policy", agents_path, "replace", "fully managed canonical AGENTS.md")
1564
3091
  if write:
1565
3092
  agents_path.write_text(canonical_agents, encoding="utf-8")
@@ -1579,40 +3106,46 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1579
3106
  else:
1580
3107
  add_action("doc", dst, "ok")
1581
3108
 
3109
+ feedback_actions = (
3110
+ _managed_scaffold_convergence(repo, feedback_templates, managed_version, write=True)
3111
+ if write
3112
+ else feedback_plan
3113
+ )
3114
+ for item in feedback_actions:
3115
+ actions.append({
3116
+ "kind": "doc",
3117
+ "path": item["path"],
3118
+ "action": item["action"],
3119
+ "detail": "managed Skill feedback template",
3120
+ })
3121
+
1582
3122
  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"),
3123
+ if config_convergence["overlay_output"] is not None:
3124
+ add_action(
3125
+ "config",
3126
+ repo / _PROJECT_CONFIG_RELATIVE,
3127
+ "create",
3128
+ f"migrate {len(config_convergence['migrated_paths'])} project-owned value paths",
3129
+ )
3130
+ if write:
3131
+ _safe_create_project_file(
3132
+ repo,
3133
+ _PROJECT_CONFIG_RELATIVE,
3134
+ config_convergence["overlay_output"],
3135
+ )
3136
+ engineering_output = config_convergence["engineering_output"]
3137
+ engineering_current = config_convergence["engineering_current"]
3138
+ if engineering_current != engineering_output:
3139
+ add_action(
3140
+ "config",
3141
+ engineering,
3142
+ "create" if not engineering_current else "replace",
3143
+ "managed default configuration",
1588
3144
  )
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
3145
  if write:
1614
- copy_tree(template_engineering, engineering)
1615
- _initialize_engineering_defaults(engineering, repo)
3146
+ _safe_write_project_file(repo, Path("docs/ENGINEERING.md"), engineering_output.encode("utf-8"))
3147
+ else:
3148
+ add_action("config", engineering, "ok")
1616
3149
 
1617
3150
  result = {
1618
3151
  "source_root": str(source_root),
@@ -1794,8 +3327,58 @@ def cmd_check_matrix(args: argparse.Namespace) -> None:
1794
3327
 
1795
3328
 
1796
3329
  def _load_cfg(repo: Path) -> dict:
1797
- cfg_path = find_config(repo)
1798
- return load_yaml(cfg_path)
3330
+ _require_no_install_transaction(repo)
3331
+ return load_effective_config(repo)
3332
+
3333
+
3334
+ def _require_no_install_transaction(repo: Path, *, allow_installer: bool = False) -> None:
3335
+ transaction = repo / _INSTALL_TRANSACTION_RELATIVE
3336
+ if not os.path.lexists(transaction):
3337
+ return
3338
+ if allow_installer:
3339
+ _require_active_install_transaction(repo)
3340
+ return
3341
+ raise APError(
3342
+ "An interrupted auto-coding-skill install transaction requires recovery. "
3343
+ "Run autocoding init or a single-project autocoding sync before using or modifying the project runtime."
3344
+ )
3345
+
3346
+
3347
+ def _require_active_install_transaction(repo: Path) -> dict:
3348
+ transaction = repo / _INSTALL_TRANSACTION_RELATIVE
3349
+ if not os.path.lexists(transaction):
3350
+ raise APError("Internal project mutation requires an active install transaction.")
3351
+ token = os.environ.get("AUTOCODING_INSTALL_TRANSACTION_TOKEN", "")
3352
+ if not re.fullmatch(r"[0-9a-f]{64}", token):
3353
+ raise APError("Internal project mutation requires the active installer token.")
3354
+ owner_payload = _safe_read_project_file(
3355
+ repo,
3356
+ _INSTALL_TRANSACTION_RELATIVE / "owner.json",
3357
+ max_bytes=4096,
3358
+ )
3359
+ state_payload = _safe_read_project_file(
3360
+ repo,
3361
+ _INSTALL_TRANSACTION_RELATIVE / "state.json",
3362
+ max_bytes=64 * 1024,
3363
+ )
3364
+ if owner_payload is None or state_payload is None:
3365
+ raise APError("Internal project mutation requires a complete active install transaction.")
3366
+ try:
3367
+ owner = json.loads(owner_payload.decode("utf-8"))
3368
+ state = json.loads(state_payload.decode("utf-8"))
3369
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
3370
+ raise APError("Active install transaction metadata is invalid.") from exc
3371
+ actual = hashlib.sha256(token.encode("ascii")).hexdigest()
3372
+ owner_hash = _text(_mapping(owner).get("token_sha256"))
3373
+ state_owner_hash = _text(_mapping(state).get("owner_token_sha256"))
3374
+ internal_hash = _text(_mapping(state).get("internal_token_sha256"))
3375
+ if not all(
3376
+ re.fullmatch(r"[0-9a-f]{64}", value)
3377
+ and hmac.compare_digest(value, actual)
3378
+ for value in (owner_hash, state_owner_hash, internal_hash)
3379
+ ):
3380
+ raise APError("Internal project mutation token does not match the active transaction.")
3381
+ return _mapping(state)
1799
3382
 
1800
3383
 
1801
3384
  def _candidate_skill_roots(repo: Path) -> list[Path]:
@@ -2094,9 +3677,8 @@ def _workflow_document_plan(repo: Path, rel: str, policy: dict) -> dict:
2094
3677
  if not match or (_text(rule.get("id")), line) in seen_issues:
2095
3678
  continue
2096
3679
  seen_issues.add((_text(rule.get("id")), line))
2097
- snippet = " ".join(match.group(0).strip().split())[:180]
2098
3680
  message = _text(rule.get("message")) or "conflicts with the fast development workflow"
2099
- issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}: {snippet}")
3681
+ issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}")
2100
3682
 
2101
3683
  output = original
2102
3684
  for start, end, _, _, replacement, match_mode in sorted(known, reverse=True):
@@ -2158,11 +3740,11 @@ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
2158
3740
  issues: list[str] = []
2159
3741
  gate_cfg = cfg.get("gate") or {}
2160
3742
  if not isinstance(gate_cfg, dict):
2161
- return ["docs/ENGINEERING.md frontmatter gate must be a mapping"]
3743
+ return ["effective configuration gate must be a mapping"]
2162
3744
  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")
3745
+ issues.append("effective configuration gate.full_on is legacy automatic full escalation; run autocoding init")
2164
3746
  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")
3747
+ issues.append("effective configuration gate.full_on_unknown=true is legacy automatic full escalation; run autocoding init")
2166
3748
  rules = gate_cfg.get("rules") or []
2167
3749
  if isinstance(rules, list):
2168
3750
  for index, rule in enumerate(rules):
@@ -2171,7 +3753,7 @@ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
2171
3753
  for key in ["scope", "commands"]:
2172
3754
  if key in rule:
2173
3755
  issues.append(
2174
- f"docs/ENGINEERING.md frontmatter gate.rules[{index}].{key} is legacy automatic gate escalation; run ap.py upgrade"
3756
+ f"effective configuration gate.rules[{index}].{key} is legacy automatic gate escalation; run autocoding init"
2175
3757
  )
2176
3758
  return issues
2177
3759
 
@@ -2183,7 +3765,7 @@ def _workflow_policy_issues(repo: Path, cfg: Optional[dict] = None) -> list[str]
2183
3765
  for migration in plan["migrations"]:
2184
3766
  issues.append(
2185
3767
  f"{plan['path']}:{migration['line']} [{migration['id']}] known legacy workflow rule; "
2186
- "run `ap.py upgrade --dry-run` then `ap.py upgrade --write`"
3768
+ "run `autocoding init` or an explicit `autocoding sync`"
2187
3769
  )
2188
3770
  issues.extend(_legacy_gate_config_issues(cfg if cfg is not None else _load_cfg(repo)))
2189
3771
  return issues
@@ -2250,13 +3832,391 @@ def _text(value: object) -> str:
2250
3832
  return str(value or "").strip()
2251
3833
 
2252
3834
 
3835
+ def _feedback_error(path: Path, message: str) -> APError:
3836
+ return APError(f"Invalid Skill feedback report {path}: {message}")
3837
+
3838
+
3839
+ def _feedback_scalar(data: dict, field: str, path: Path) -> str:
3840
+ value = data.get(field)
3841
+ if not isinstance(value, str) or not value.strip():
3842
+ raise _feedback_error(path, f"{field} must be a non-empty string")
3843
+ return value.strip()
3844
+
3845
+
3846
+ def _feedback_created_at(value: object, path: Path) -> str:
3847
+ if isinstance(value, _dt.datetime):
3848
+ return value.isoformat()
3849
+ if isinstance(value, _dt.date):
3850
+ return value.isoformat()
3851
+ if not isinstance(value, str) or not value.strip():
3852
+ raise _feedback_error(path, "created_at must be an ISO-8601 date or timestamp")
3853
+ raw = value.strip()
3854
+ try:
3855
+ if "T" in raw or " " in raw:
3856
+ _dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
3857
+ else:
3858
+ _dt.date.fromisoformat(raw)
3859
+ except ValueError as exc:
3860
+ raise _feedback_error(path, "created_at must be an ISO-8601 date or timestamp") from exc
3861
+ return raw
3862
+
3863
+
3864
+ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3865
+ try:
3866
+ text = payload.decode("utf-8")
3867
+ except UnicodeDecodeError as exc:
3868
+ raise _feedback_error(path, "file must be UTF-8") from exc
3869
+ text = text.replace("\r\n", "\n").replace("\r", "\n")
3870
+ if "\x00" in text:
3871
+ raise _feedback_error(path, "file must be plain Markdown text")
3872
+ if any(pattern.search(text) for pattern in _FEEDBACK_SENSITIVE_PATTERNS):
3873
+ raise _feedback_error(path, "report contains sensitive or machine-specific evidence; redact it")
3874
+ match = re.match(r"^---[ \t]*\n(.*?)\n---[ \t]*(?:\n|$)(.*)$", text, flags=re.DOTALL)
3875
+ if not match:
3876
+ raise _feedback_error(path, "YAML frontmatter is required")
3877
+ try:
3878
+ data = require_yaml().safe_load(match.group(1))
3879
+ except Exception as exc:
3880
+ raise _feedback_error(path, "YAML frontmatter is not safe and valid") from exc
3881
+ if not isinstance(data, dict):
3882
+ raise _feedback_error(path, "YAML frontmatter must be a flat mapping")
3883
+ if any(not isinstance(key, str) for key in data):
3884
+ raise _feedback_error(path, "frontmatter field names must be strings")
3885
+ unknown = sorted(set(data) - set(_FEEDBACK_FIELDS))
3886
+ missing = [field for field in _FEEDBACK_FIELDS if field not in data]
3887
+ if unknown:
3888
+ raise _feedback_error(path, "unknown frontmatter fields are not allowed")
3889
+ if missing:
3890
+ raise _feedback_error(path, f"missing frontmatter fields: {', '.join(missing)}")
3891
+ if any(isinstance(value, (dict, list, tuple, set)) for value in data.values()):
3892
+ raise _feedback_error(path, "frontmatter values must be scalars")
3893
+
3894
+ metadata: dict[str, str] = {}
3895
+ schema_value = _feedback_scalar(data, "schema", path)
3896
+ if schema_value != _FEEDBACK_SCHEMA:
3897
+ raise _feedback_error(path, f"schema must be {_FEEDBACK_SCHEMA}")
3898
+ metadata["schema"] = schema_value
3899
+ report_id = _feedback_scalar(data, "report_id", path)
3900
+ if not _FEEDBACK_SAFE_ID_RE.fullmatch(report_id):
3901
+ raise _feedback_error(path, "report_id must be a safe identifier")
3902
+ metadata["report_id"] = report_id
3903
+ status_value = _feedback_scalar(data, "status", path)
3904
+ if status_value not in _FEEDBACK_STATUSES:
3905
+ raise _feedback_error(path, "status is not supported")
3906
+ metadata["status"] = status_value
3907
+ metadata["created_at"] = _feedback_created_at(data.get("created_at"), path)
3908
+ project_value = _feedback_scalar(data, "project", path)
3909
+ if not _FEEDBACK_SAFE_ID_RE.fullmatch(project_value):
3910
+ raise _feedback_error(path, "project must be a safe identifier")
3911
+ metadata["project"] = project_value
3912
+ version = _feedback_scalar(data, "observed_skill_version", path)
3913
+ if not _FEEDBACK_SEMVER_RE.fullmatch(version):
3914
+ raise _feedback_error(path, "observed_skill_version must be valid SemVer")
3915
+ metadata["observed_skill_version"] = version
3916
+ component = _feedback_scalar(data, "component", path)
3917
+ if not _FEEDBACK_SLUG_RE.fullmatch(component):
3918
+ raise _feedback_error(path, "component must be a lowercase kebab-case slug")
3919
+ metadata["component"] = component
3920
+ kind = _feedback_scalar(data, "kind", path)
3921
+ if kind not in _FEEDBACK_KINDS:
3922
+ raise _feedback_error(path, "kind is not supported")
3923
+ metadata["kind"] = kind
3924
+ impact = _feedback_scalar(data, "impact", path)
3925
+ if impact not in _FEEDBACK_IMPACTS:
3926
+ raise _feedback_error(path, "impact is not supported")
3927
+ metadata["impact"] = impact
3928
+ origin_surface = _feedback_scalar(data, "origin_surface", path)
3929
+ if origin_surface not in _FEEDBACK_ORIGIN_SURFACES:
3930
+ raise _feedback_error(path, "origin_surface is not supported")
3931
+ metadata["origin_surface"] = origin_surface
3932
+ suspected_scope = _feedback_scalar(data, "suspected_scope", path)
3933
+ if suspected_scope != "shared":
3934
+ raise _feedback_error(path, "suspected_scope must be shared")
3935
+ metadata["suspected_scope"] = suspected_scope
3936
+ signature = _feedback_scalar(data, "signature", path)
3937
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
3938
+ raise _feedback_error(path, "signature must be sha256 followed by 64 lowercase hex characters")
3939
+ metadata["signature"] = signature
3940
+ export_value = _feedback_scalar(data, "export", path)
3941
+ if export_value != "metadata-only":
3942
+ raise _feedback_error(path, "export must be metadata-only")
3943
+ metadata["export"] = export_value
3944
+
3945
+ body_lines = match.group(2).splitlines()
3946
+ titles = [line[2:].strip() for line in body_lines if line.startswith("# ")]
3947
+ if len(titles) != 1 or not titles[0]:
3948
+ raise _feedback_error(path, "body must contain exactly one non-empty level-one title")
3949
+ for heading in _FEEDBACK_HEADINGS:
3950
+ if body_lines.count(f"## {heading}") != 1:
3951
+ raise _feedback_error(path, f"body must contain exactly one '## {heading}' heading")
3952
+ heading_positions = [body_lines.index(f"## {heading}") for heading in _FEEDBACK_HEADINGS]
3953
+ if heading_positions != sorted(heading_positions):
3954
+ raise _feedback_error(path, "body headings must use the canonical order")
3955
+ for index, heading in enumerate(_FEEDBACK_HEADINGS):
3956
+ start = heading_positions[index] + 1
3957
+ end = heading_positions[index + 1] if index + 1 < len(heading_positions) else len(body_lines)
3958
+ if not any(line.strip() for line in body_lines[start:end]):
3959
+ raise _feedback_error(path, f"body section '{heading}' must not be empty")
3960
+ return metadata
3961
+
3962
+
3963
+ def _read_feedback_report(
3964
+ directory_fd: int | Path,
3965
+ name: str,
3966
+ display_path: Path,
3967
+ ) -> tuple[bytes, int, tuple[int, int]]:
3968
+ flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
3969
+ descriptor = -1
3970
+ target = directory_fd / name if isinstance(directory_fd, Path) else None
3971
+ target_identity: tuple[int, int] | None = None
3972
+ try:
3973
+ if target is not None:
3974
+ checked = target.lstat()
3975
+ if _is_windows_reparse_point(checked) or not stat.S_ISREG(checked.st_mode):
3976
+ raise _feedback_error(display_path, "report must be a regular non-symlink file")
3977
+ target_identity = _project_path_identity(checked)
3978
+ descriptor = (
3979
+ os.open(target, flags)
3980
+ if isinstance(directory_fd, Path)
3981
+ else os.open(name, flags, dir_fd=directory_fd)
3982
+ )
3983
+ metadata = os.fstat(descriptor)
3984
+ if (
3985
+ not stat.S_ISREG(metadata.st_mode)
3986
+ or (target_identity is not None and _project_path_identity(metadata) != target_identity)
3987
+ ):
3988
+ raise _feedback_error(display_path, "report must be a regular non-symlink file")
3989
+ if target is not None:
3990
+ checked = target.lstat()
3991
+ if (
3992
+ _is_windows_reparse_point(checked)
3993
+ or not stat.S_ISREG(checked.st_mode)
3994
+ or _project_path_identity(checked) != target_identity
3995
+ ):
3996
+ raise _feedback_error(display_path, "report changed during its safety check")
3997
+ if metadata.st_size > _FEEDBACK_REPORT_MAX_BYTES:
3998
+ raise _feedback_error(display_path, f"report exceeds {_FEEDBACK_REPORT_MAX_BYTES} bytes")
3999
+ with os.fdopen(descriptor, "rb") as handle:
4000
+ descriptor = -1
4001
+ payload = handle.read(_FEEDBACK_REPORT_MAX_BYTES + 1)
4002
+ if target is not None:
4003
+ checked = target.lstat()
4004
+ if (
4005
+ _is_windows_reparse_point(checked)
4006
+ or not stat.S_ISREG(checked.st_mode)
4007
+ or _project_path_identity(checked) != target_identity
4008
+ ):
4009
+ raise _feedback_error(display_path, "report changed while it was read")
4010
+ except APError:
4011
+ raise
4012
+ except OSError as exc:
4013
+ raise _feedback_error(display_path, "report could not be read safely") from exc
4014
+ finally:
4015
+ if descriptor >= 0:
4016
+ os.close(descriptor)
4017
+ if len(payload) > _FEEDBACK_REPORT_MAX_BYTES:
4018
+ raise _feedback_error(display_path, f"report exceeds {_FEEDBACK_REPORT_MAX_BYTES} bytes")
4019
+ return payload, len(payload), (int(metadata.st_dev), int(metadata.st_ino))
4020
+
4021
+
4022
+ def _feedback_project_root(raw: str) -> Path:
4023
+ try:
4024
+ root = Path(raw).expanduser().resolve(strict=True)
4025
+ except OSError as exc:
4026
+ raise APError(f"Skill feedback project does not exist: {raw}") from exc
4027
+ if not root.is_dir():
4028
+ raise APError(f"Skill feedback project is not a directory: {raw}")
4029
+ return root
4030
+
4031
+
4032
+ def _feedback_configured_project(root: Path) -> str:
4033
+ config = load_effective_config(root)
4034
+ name = _text(_mapping(config.get("project")).get("name"))
4035
+ if not _FEEDBACK_SAFE_ID_RE.fullmatch(name):
4036
+ raise APError("Effective project.name must be a safe non-empty identifier for feedback")
4037
+ return name
4038
+
4039
+
4040
+ def _collect_project_feedback(
4041
+ root: Path,
4042
+ ) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str | None]:
4043
+ reports_relative = Path("docs/skill-feedback/reports")
4044
+ configured_project = _feedback_configured_project(root)
4045
+ with _open_project_directory(root, reports_relative) as directory_fd:
4046
+ if directory_fd is None:
4047
+ return [], 0, None, set(), configured_project
4048
+ directory_metadata = (
4049
+ directory_fd.stat() if isinstance(directory_fd, Path) else os.fstat(directory_fd)
4050
+ )
4051
+ directory_identity = (int(directory_metadata.st_dev), int(directory_metadata.st_ino))
4052
+ try:
4053
+ entries = os.listdir(directory_fd)
4054
+ except OSError as exc:
4055
+ raise APError("Cannot list Skill feedback reports safely") from exc
4056
+ if len(entries) > _FEEDBACK_PROJECT_MAX_ENTRIES:
4057
+ raise APError(
4058
+ f"Skill feedback directory exceeds {_FEEDBACK_PROJECT_MAX_ENTRIES} entries"
4059
+ )
4060
+ candidates: list[str] = []
4061
+ for name in entries:
4062
+ if not name.endswith(".md"):
4063
+ continue
4064
+ if not _FEEDBACK_FILENAME_RE.fullmatch(name):
4065
+ raise APError("Skill feedback directory contains an invalid Markdown filename")
4066
+ try:
4067
+ metadata = (
4068
+ (directory_fd / name).stat(follow_symlinks=False)
4069
+ if isinstance(directory_fd, Path)
4070
+ else os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
4071
+ )
4072
+ except OSError as exc:
4073
+ raise APError("Cannot inspect Skill feedback report safely") from exc
4074
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
4075
+ raise APError(f"Skill feedback report must be a regular non-symlink file: {name}")
4076
+ candidates.append(name)
4077
+ candidates.sort()
4078
+ if len(candidates) > _FEEDBACK_PROJECT_MAX_REPORTS:
4079
+ raise APError(
4080
+ f"Skill feedback project exceeds {_FEEDBACK_PROJECT_MAX_REPORTS} reports"
4081
+ )
4082
+
4083
+ reports: list[dict] = []
4084
+ total_bytes = 0
4085
+ file_identities: set[tuple[int, int]] = set()
4086
+ for name in candidates:
4087
+ display_path = reports_relative / name
4088
+ payload, size, file_identity = _read_feedback_report(directory_fd, name, display_path)
4089
+ if file_identity in file_identities:
4090
+ raise APError("Skill feedback project contains duplicate physical report files")
4091
+ file_identities.add(file_identity)
4092
+ report = _parse_feedback_report(payload, display_path)
4093
+ if report["project"] != configured_project:
4094
+ raise _feedback_error(
4095
+ display_path,
4096
+ "project must equal effective project.name",
4097
+ )
4098
+ report["source_path"] = display_path.as_posix()
4099
+ report["size_bytes"] = size
4100
+ reports.append(report)
4101
+ total_bytes += size
4102
+ return reports, total_bytes, directory_identity, file_identities, configured_project
4103
+
4104
+
4105
+ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4106
+ raw_projects = list(args.project or [])
4107
+ if not raw_projects:
4108
+ raise APError("feedback-collect requires at least one explicit --project")
4109
+ roots: list[Path] = []
4110
+ seen_roots: set[str] = set()
4111
+ for raw in raw_projects:
4112
+ root = _feedback_project_root(raw)
4113
+ key = str(root)
4114
+ if key not in seen_roots:
4115
+ seen_roots.add(key)
4116
+ roots.append(root)
4117
+ if len(roots) > _FEEDBACK_COLLECTION_MAX_PROJECTS:
4118
+ raise APError(
4119
+ f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_PROJECTS} projects"
4120
+ )
4121
+
4122
+ reports: list[dict] = []
4123
+ total_bytes = 0
4124
+ source_projects: list[dict[str, str]] = []
4125
+ seen_report_directories: set[tuple[int, int]] = set()
4126
+ seen_report_files: set[tuple[int, int]] = set()
4127
+ seen_configured_projects: set[str] = set()
4128
+ for index, root in enumerate(roots, start=1):
4129
+ source_id = f"project-{index}"
4130
+ (
4131
+ project_reports,
4132
+ project_bytes,
4133
+ directory_identity,
4134
+ file_identities,
4135
+ configured_project,
4136
+ ) = _collect_project_feedback(root)
4137
+ if directory_identity is not None:
4138
+ if directory_identity in seen_report_directories:
4139
+ raise APError("Explicit projects resolve to the same Skill feedback report directory")
4140
+ seen_report_directories.add(directory_identity)
4141
+ if seen_report_files.intersection(file_identities):
4142
+ raise APError("Explicit projects contain the same physical Skill feedback report file")
4143
+ seen_report_files.update(file_identities)
4144
+ if configured_project is not None:
4145
+ if configured_project in seen_configured_projects:
4146
+ raise APError("Explicit projects must have distinct effective project.name values")
4147
+ seen_configured_projects.add(configured_project)
4148
+ source_descriptor = {"source_project": source_id}
4149
+ if configured_project is not None:
4150
+ source_descriptor["project"] = configured_project
4151
+ source_projects.append(source_descriptor)
4152
+ total_bytes += project_bytes
4153
+ if total_bytes > _FEEDBACK_COLLECTION_MAX_BYTES:
4154
+ raise APError(
4155
+ f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_BYTES} bytes"
4156
+ )
4157
+ if len(reports) + len(project_reports) > _FEEDBACK_COLLECTION_MAX_REPORTS:
4158
+ raise APError(
4159
+ f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_REPORTS} reports"
4160
+ )
4161
+ for report in project_reports:
4162
+ report["source_project"] = source_id
4163
+ reports.extend(project_reports)
4164
+
4165
+ reports.sort(key=lambda item: (item["signature"], item["project"], item["report_id"], item["source_path"]))
4166
+ grouped: dict[str, list[dict]] = {}
4167
+ for report in reports:
4168
+ grouped.setdefault(report["signature"], []).append(report)
4169
+ groups: list[dict] = []
4170
+ for signature, items in sorted(grouped.items()):
4171
+ projects = sorted({item["project"] for item in items})
4172
+ group_source_projects = sorted({item["source_project"] for item in items})
4173
+ groups.append(
4174
+ {
4175
+ "signature": signature,
4176
+ "report_count": len(items),
4177
+ "project_count": len(group_source_projects),
4178
+ "projects": projects,
4179
+ "source_projects": group_source_projects,
4180
+ "report_ids": [item["report_id"] for item in items],
4181
+ "cross_project": len(group_source_projects) > 1,
4182
+ }
4183
+ )
4184
+ cross_project = [group for group in groups if group["cross_project"]]
4185
+ result = {
4186
+ "schema": _FEEDBACK_COLLECTION_SCHEMA,
4187
+ "projects": source_projects,
4188
+ "report_count": len(reports),
4189
+ "total_bytes": total_bytes,
4190
+ "metadata": reports,
4191
+ "groups": groups,
4192
+ "cross_project": cross_project,
4193
+ }
4194
+ if args.json:
4195
+ print(json.dumps(result, ensure_ascii=False, indent=2))
4196
+ return
4197
+ print(
4198
+ f"[feedback-collect] projects={len(roots)} reports={len(reports)} "
4199
+ f"groups={len(groups)} cross_project={len(cross_project)} bytes={total_bytes}"
4200
+ )
4201
+ for group in groups:
4202
+ print(
4203
+ f"[feedback-collect] signature={group['signature']} "
4204
+ f"cross_project={str(group['cross_project']).lower()} "
4205
+ f"projects={','.join(group['projects'])} reports={','.join(group['report_ids'])}"
4206
+ )
4207
+
4208
+
2253
4209
  _TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
2254
4210
  _DIRECT_CLAIM_ID_RE = re.compile(r"^[0-9a-f]{32}$")
2255
4211
 
2256
4212
 
2257
4213
  def _concurrency_cfg(cfg: dict) -> dict:
2258
- value = cfg.get("concurrency") or {}
2259
- return value if isinstance(value, dict) else {}
4214
+ value = cfg.get("concurrency")
4215
+ if value is None:
4216
+ return {}
4217
+ if not isinstance(value, dict):
4218
+ raise APError("concurrency must be a mapping")
4219
+ return value
2260
4220
 
2261
4221
 
2262
4222
  def _task_isolation(cfg: dict) -> str:
@@ -3948,6 +5908,7 @@ _DEFAULT_FULL_PATH_PATTERNS = [
3948
5908
  "compose*.yml",
3949
5909
  "compose*.yaml",
3950
5910
  "docs/ENGINEERING.md",
5911
+ _PROJECT_CONFIG_RELATIVE.as_posix(),
3951
5912
  "docs/tools/autopipeline/**",
3952
5913
  "package.json",
3953
5914
  "**/package.json",
@@ -3967,18 +5928,30 @@ _DEFAULT_FULL_PATH_PATTERNS = [
3967
5928
 
3968
5929
 
3969
5930
  def _gate_cfg(cfg: dict) -> dict:
3970
- gate_cfg = cfg.get("gate") or {}
3971
- return gate_cfg if isinstance(gate_cfg, dict) else {}
5931
+ gate_cfg = cfg.get("gate")
5932
+ if gate_cfg is None:
5933
+ return {}
5934
+ if not isinstance(gate_cfg, dict):
5935
+ raise APError("gate must be a mapping")
5936
+ return gate_cfg
3972
5937
 
3973
5938
 
3974
5939
  def _risk_cfg(cfg: dict) -> dict:
3975
- value = cfg.get("risk") or {}
3976
- return value if isinstance(value, dict) else {}
5940
+ value = cfg.get("risk")
5941
+ if value is None:
5942
+ return {}
5943
+ if not isinstance(value, dict):
5944
+ raise APError("risk must be a mapping")
5945
+ return value
3977
5946
 
3978
5947
 
3979
5948
  def _validation_cfg(cfg: dict) -> dict:
3980
- value = cfg.get("validation") or {}
3981
- return value if isinstance(value, dict) else {}
5949
+ value = cfg.get("validation")
5950
+ if value is None:
5951
+ return {}
5952
+ if not isinstance(value, dict):
5953
+ raise APError("validation must be a mapping")
5954
+ return value
3982
5955
 
3983
5956
 
3984
5957
  def _positive_seconds(value: object, default: float, label: str) -> float:
@@ -4185,7 +6158,11 @@ def _cleanup_generated_noise(repo: Path, protected_paths: Optional[set[str]] = N
4185
6158
 
4186
6159
 
4187
6160
  def _docs_only(paths: list[str]) -> bool:
4188
- return bool(paths) and all(_path_matches(path, _DOC_PATH_PATTERNS) for path in paths)
6161
+ return bool(paths) and all(
6162
+ path not in _EFFECTIVE_CONFIG_PATHS
6163
+ and _path_matches(path, _DOC_PATH_PATTERNS)
6164
+ for path in paths
6165
+ )
4189
6166
 
4190
6167
 
4191
6168
  def _tests_only(paths: list[str]) -> bool:
@@ -4199,13 +6176,46 @@ def _tests_only(paths: list[str]) -> bool:
4199
6176
 
4200
6177
 
4201
6178
  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)]
6179
+ rules = gate_cfg.get("rules", [])
6180
+ if not isinstance(rules, list):
6181
+ raise APError("gate.rules must be a list")
6182
+ validated: list[dict] = []
6183
+ for index, rule in enumerate(rules):
6184
+ if not isinstance(rule, dict):
6185
+ raise APError(f"gate.rules[{index}] must be a mapping")
6186
+ profile = _text(rule.get("profile")).lower()
6187
+ if profile and profile not in _WORKFLOW_PROFILES - {"auto"}:
6188
+ raise APError(
6189
+ f"gate.rules[{index}].profile must be micro, standard, or high-risk"
6190
+ )
6191
+ if "scope" in rule:
6192
+ raise APError(
6193
+ f"gate.rules[{index}].scope is legacy automatic gate escalation; run autocoding init"
6194
+ )
6195
+ if "commands" in rule:
6196
+ raise APError(
6197
+ f"gate.rules[{index}].commands is legacy automatic gate escalation; run autocoding init"
6198
+ )
6199
+ validated.append(rule)
6200
+ return validated
4204
6201
 
4205
6202
 
4206
6203
  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)]
6204
+ rules = _risk_cfg(cfg).get("rules", [])
6205
+ if not isinstance(rules, list):
6206
+ raise APError("risk.rules must be a list")
6207
+ current: list[dict] = []
6208
+ for index, rule in enumerate(rules):
6209
+ if not isinstance(rule, dict):
6210
+ raise APError(f"risk.rules[{index}] must be a mapping")
6211
+ if not _as_list(rule.get("paths")):
6212
+ raise APError(f"risk.rules[{index}].paths must not be empty")
6213
+ profile = _text(rule.get("profile")).lower()
6214
+ if profile and profile not in _WORKFLOW_PROFILES - {"auto"}:
6215
+ raise APError(
6216
+ f"risk.rules[{index}].profile must be micro, standard, or high-risk"
6217
+ )
6218
+ current.append(rule)
4209
6219
  # Keep reading 3.x gate.rules while projects migrate. They remain planning
4210
6220
  # metadata only and never execute validation commands.
4211
6221
  return current or _gate_rules(_gate_cfg(cfg))
@@ -4230,8 +6240,19 @@ def _matching_risk_rules(paths: list[str], cfg: dict) -> list[dict]:
4230
6240
 
4231
6241
 
4232
6242
  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)]
6243
+ routes = _validation_cfg(cfg).get("routes", [])
6244
+ if not isinstance(routes, list):
6245
+ raise APError("validation.routes must be a list")
6246
+ validated: list[dict] = []
6247
+ for index, route in enumerate(routes):
6248
+ if not isinstance(route, dict):
6249
+ raise APError(f"validation.routes[{index}] must be a mapping")
6250
+ if not _as_list(route.get("paths")):
6251
+ raise APError(f"validation.routes[{index}].paths must not be empty")
6252
+ if not [_command_name(item) for item in _as_list(route.get("commands"))]:
6253
+ raise APError(f"validation.routes[{index}].commands must not be empty")
6254
+ validated.append(route)
6255
+ return validated
4235
6256
 
4236
6257
 
4237
6258
  def _validation_route_matches(path: str, route: dict) -> bool:
@@ -4253,11 +6274,19 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
4253
6274
  command_names: list[str] = []
4254
6275
  command_timeouts: dict[str, float] = {}
4255
6276
  matched_routes: list[str] = []
6277
+ builtins: list[str] = []
4256
6278
  coverage: dict[str, list[str]] = {}
4257
6279
  unmapped: list[str] = []
4258
6280
 
4259
6281
  for path in normalized:
4260
6282
  names: list[str] = []
6283
+ if path in _EFFECTIVE_CONFIG_PATHS:
6284
+ builtin_name = "effective-config"
6285
+ names.append(builtin_name)
6286
+ if builtin_name not in builtins:
6287
+ builtins.append(builtin_name)
6288
+ if builtin_name not in matched_routes:
6289
+ matched_routes.append(builtin_name)
4261
6290
  for index, route in enumerate(routes):
4262
6291
  if not _validation_route_matches(path, route):
4263
6292
  continue
@@ -4289,7 +6318,13 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
4289
6318
 
4290
6319
  validation_cfg = _validation_cfg(cfg)
4291
6320
  compatibility_command = ""
4292
- if not routes:
6321
+ project_validation_paths = [
6322
+ path
6323
+ for path in normalized
6324
+ if path not in _EFFECTIVE_CONFIG_PATHS
6325
+ and not _path_matches(path, _DOC_PATH_PATTERNS)
6326
+ ]
6327
+ if not routes and project_validation_paths:
4293
6328
  compatibility_command = _command_name(validation_cfg.get("fallback_command"))
4294
6329
  if not compatibility_command and _configured_command(cfg, "gate_changed"):
4295
6330
  compatibility_command = "gate_changed"
@@ -4313,6 +6348,7 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
4313
6348
  "commands": command_names,
4314
6349
  "command_timeouts": command_timeouts,
4315
6350
  "matched_routes": matched_routes,
6351
+ "builtins": builtins,
4316
6352
  "coverage": coverage,
4317
6353
  "unmapped": unmapped,
4318
6354
  "docs_only": _docs_only(normalized),
@@ -4328,9 +6364,9 @@ def _validate_validation_plan(cfg: dict, plan: dict) -> None:
4328
6364
  raise APError(
4329
6365
  "Changed code paths have no validation route:\n- "
4330
6366
  + "\n- ".join(plan["unmapped"])
4331
- + "\nAdd validation.routes entries in docs/ENGINEERING.md."
6367
+ + "\nAdd validation.routes entries in docs/project/auto-coding-skill.yaml."
4332
6368
  )
4333
- if plan["paths"] and not plan["docs_only"] and not plan["commands"]:
6369
+ if plan["paths"] and not plan["docs_only"] and not plan["commands"] and not plan["builtins"]:
4334
6370
  raise APError(
4335
6371
  "Changed code has no fast validation command. Add validation.routes with project-native commands."
4336
6372
  )
@@ -4448,6 +6484,14 @@ def _run_changed_gate(
4448
6484
  deadline: Optional[float] = None,
4449
6485
  command_timeout_s: Optional[float] = None,
4450
6486
  ) -> list[str]:
6487
+ contract = cmd_doctor(
6488
+ argparse.Namespace(repo=str(repo), collect=True, quiet=True, record=False)
6489
+ )
6490
+ if contract["issues"]:
6491
+ raise APError(
6492
+ "Effective project configuration contract is invalid:\n- "
6493
+ + "\n- ".join(contract["issues"])
6494
+ )
4451
6495
  plan = _validation_plan(cfg, paths)
4452
6496
  _validate_validation_plan(cfg, plan)
4453
6497
  if not paths:
@@ -4461,14 +6505,17 @@ def _run_changed_gate(
4461
6505
  "[validation] WARN: using 3.x compatibility fallback; migrate to validation.routes",
4462
6506
  file=sys.stderr,
4463
6507
  )
4464
- executed = _run_configured_command_list(
6508
+ executed = list(plan["builtins"])
6509
+ if plan["builtins"]:
6510
+ print("[validation] effective project configuration contract is valid")
6511
+ executed.extend(_run_configured_command_list(
4465
6512
  repo,
4466
6513
  cfg,
4467
6514
  plan["commands"],
4468
6515
  deadline=deadline,
4469
6516
  command_timeout_s=command_timeout_s,
4470
6517
  command_timeouts=plan["command_timeouts"],
4471
- )
6518
+ ))
4472
6519
  print(
4473
6520
  "[validation] routes="
4474
6521
  + (", ".join(plan["matched_routes"]) or "(none)")
@@ -4495,6 +6542,7 @@ def cmd_validation_map_check(args: argparse.Namespace) -> None:
4495
6542
  "commands": plan["commands"],
4496
6543
  "command_timeouts": plan["command_timeouts"],
4497
6544
  "matched_routes": plan["matched_routes"],
6545
+ "builtins": plan["builtins"],
4498
6546
  "coverage": plan["coverage"],
4499
6547
  "docs_only": plan["docs_only"],
4500
6548
  }
@@ -4711,18 +6759,30 @@ _DEFAULT_LAYER_RULES = {
4711
6759
 
4712
6760
 
4713
6761
  def _structure_cfg(cfg: dict) -> dict:
4714
- value = cfg.get("structure") or {}
4715
- return value if isinstance(value, dict) else {}
6762
+ value = cfg.get("structure")
6763
+ if value is None:
6764
+ return {}
6765
+ if not isinstance(value, dict):
6766
+ raise APError("structure must be a mapping")
6767
+ return value
4716
6768
 
4717
6769
 
4718
6770
  def _optimization_cfg(cfg: dict) -> dict:
4719
- value = cfg.get("optimization") or {}
4720
- return value if isinstance(value, dict) else {}
6771
+ value = cfg.get("optimization")
6772
+ if value is None:
6773
+ return {}
6774
+ if not isinstance(value, dict):
6775
+ raise APError("optimization must be a mapping")
6776
+ return value
4721
6777
 
4722
6778
 
4723
6779
  def _verification_cfg(cfg: dict) -> dict:
4724
- value = cfg.get("verification") or {}
4725
- return value if isinstance(value, dict) else {}
6780
+ value = cfg.get("verification")
6781
+ if value is None:
6782
+ return {}
6783
+ if not isinstance(value, dict):
6784
+ raise APError("verification must be a mapping")
6785
+ return value
4726
6786
 
4727
6787
 
4728
6788
  def _bool_config(value: object, default: bool = False) -> bool:
@@ -6582,14 +8642,24 @@ def _render_optimization_backlog(inventory: dict) -> str:
6582
8642
  def _update_accepted_debt_paths(repo: Path, cfg: dict, paths: list[str]) -> list[str]:
6583
8643
  if not paths:
6584
8644
  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()]
8645
+ overrides = json.loads(json.dumps(load_project_overrides(repo)))
8646
+ effective_structure = _mapping(cfg.get("structure"))
8647
+ existing = [
8648
+ str(item)
8649
+ for item in _as_list(effective_structure.get("accepted_debt_paths"))
8650
+ if str(item).strip()
8651
+ ]
6589
8652
  added = [path for path in paths if path not in existing]
6590
8653
  if added:
8654
+ structure_cfg = overrides.setdefault("structure", {})
8655
+ if not isinstance(structure_cfg, dict):
8656
+ raise APError("Project structure override must be a mapping")
6591
8657
  structure_cfg["accepted_debt_paths"] = existing + added
6592
- _write_frontmatter_markdown(engineering, current_cfg, body)
8658
+ overlay_payload = _render_project_overlay(overrides)
8659
+ if _safe_read_project_file(repo, _PROJECT_CONFIG_RELATIVE) is None:
8660
+ _safe_create_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay_payload)
8661
+ else:
8662
+ _safe_write_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay_payload)
6593
8663
  return added
6594
8664
 
6595
8665
 
@@ -6624,7 +8694,7 @@ def cmd_baseline_init(args: argparse.Namespace) -> None:
6624
8694
  accepted_added = _update_accepted_debt_paths(repo, cfg, accepted_paths)
6625
8695
  if accepted_added:
6626
8696
  actions.append({
6627
- "path": "docs/ENGINEERING.md",
8697
+ "path": _PROJECT_CONFIG_RELATIVE.as_posix(),
6628
8698
  "action": "merge",
6629
8699
  "kind": "accepted_debt_paths",
6630
8700
  "detail": ", ".join(accepted_added),
@@ -8627,7 +10697,7 @@ def cmd_agent_result_template(args: argparse.Namespace) -> None:
8627
10697
  def cmd_run(args: argparse.Namespace) -> None:
8628
10698
  """
8629
10699
  Run any configured gate command by name.
8630
- Commands are read from docs/ENGINEERING.md frontmatter.
10700
+ Commands are read from the effective managed-default plus project-overlay configuration.
8631
10701
  """
8632
10702
  repo = Path(args.repo).resolve()
8633
10703
  cfg = _load_cfg(repo)
@@ -8636,12 +10706,12 @@ def cmd_run(args: argparse.Namespace) -> None:
8636
10706
  if name not in commands:
8637
10707
  raise APError(
8638
10708
  f"Command not configured: commands.{name}. "
8639
- "Edit docs/ENGINEERING.md frontmatter. "
10709
+ "Edit docs/project/auto-coding-skill.yaml. "
8640
10710
  f"Available: {', '.join(commands.keys()) or '(none)'}"
8641
10711
  )
8642
10712
  cmd = str(commands.get(name) or "").strip()
8643
10713
  if not cmd:
8644
- raise APError(f"Command is blank: commands.{name}. Edit docs/ENGINEERING.md frontmatter.")
10714
+ raise APError(f"Command is blank: commands.{name}. Edit docs/project/auto-coding-skill.yaml.")
8645
10715
  print(f"[run] {name}: {cmd}")
8646
10716
  run_shell(cmd, cwd=repo)
8647
10717
  print(f"[run] OK: {name}")
@@ -8961,9 +11031,12 @@ def cmd_verify_jenkins(args: argparse.Namespace) -> None:
8961
11031
  print(f"[verify-jenkins] OK: {jenkinsfile}")
8962
11032
 
8963
11033
 
8964
- def cmd_doctor(args: argparse.Namespace) -> None:
11034
+ def cmd_doctor(args: argparse.Namespace) -> dict | None:
8965
11035
  repo = Path(args.repo).resolve()
8966
11036
  cfg = _load_cfg(repo)
11037
+ collect = bool(getattr(args, "collect", False))
11038
+ quiet = bool(getattr(args, "quiet", False))
11039
+ record = bool(getattr(args, "record", True))
8967
11040
  workflow_cfg = (cfg.get("workflow") or {})
8968
11041
  project_cfg = (cfg.get("project") or {})
8969
11042
  docs_cfg = (cfg.get("docs") or {})
@@ -8976,9 +11049,18 @@ def cmd_doctor(args: argparse.Namespace) -> None:
8976
11049
  advisories: List[str] = []
8977
11050
  validation_errors.extend(_workflow_policy_issues(repo, cfg))
8978
11051
 
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()
11052
+ raw_mode = workflow_cfg.get("mode", "dev")
11053
+ raw_profile = workflow_cfg.get("profile", "auto")
11054
+ raw_completion = workflow_cfg.get("completion", "")
11055
+ if not isinstance(raw_mode, str):
11056
+ validation_errors.append("workflow.mode must be a string")
11057
+ if not isinstance(raw_profile, str):
11058
+ validation_errors.append("workflow.profile must be a string")
11059
+ if not isinstance(raw_completion, str):
11060
+ validation_errors.append("workflow.completion must be a string")
11061
+ mode = raw_mode.strip().lower() if isinstance(raw_mode, str) else ""
11062
+ profile = raw_profile.strip().lower() if isinstance(raw_profile, str) else ""
11063
+ completion = raw_completion.strip().lower() if isinstance(raw_completion, str) else ""
8982
11064
  skill_version = _text(workflow_cfg.get("skill_version"))
8983
11065
  if mode != "dev":
8984
11066
  missing.append("workflow.mode (must be dev; external verification is owner-managed)")
@@ -8988,24 +11070,42 @@ def cmd_doctor(args: argparse.Namespace) -> None:
8988
11070
  missing.append("workflow.completion (must be push)")
8989
11071
  if skill_version.startswith("4.1") and _text(docs_cfg.get("framework")) != "engineering-centered":
8990
11072
  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"}:
11073
+ raw_isolation = concurrency_cfg.get("isolation", "adaptive")
11074
+ if not isinstance(raw_isolation, str):
11075
+ validation_errors.append("concurrency.isolation must be a string")
11076
+ isolation = ""
11077
+ else:
11078
+ isolation = raw_isolation.strip().lower() or "adaptive"
11079
+ if isolation and isolation not in {"adaptive", "worktree"}:
8993
11080
  validation_errors.append(
8994
11081
  "concurrency.isolation must be adaptive or worktree; legacy shared-checkout mode is unsupported"
8995
11082
  )
8996
- branch_prefix = _text(concurrency_cfg.get("branch_prefix")) or "codex/"
8997
- if not branch_prefix.endswith("/"):
11083
+ raw_branch_prefix = concurrency_cfg.get("branch_prefix", "codex/")
11084
+ if not isinstance(raw_branch_prefix, str):
11085
+ validation_errors.append("concurrency.branch_prefix must be a string")
11086
+ branch_prefix = ""
11087
+ else:
11088
+ branch_prefix = raw_branch_prefix.strip() or "codex/"
11089
+ if branch_prefix and not branch_prefix.endswith("/"):
8998
11090
  validation_errors.append("concurrency.branch_prefix must end with '/'")
8999
- elif run(
11091
+ elif branch_prefix and run(
9000
11092
  ["git", "check-ref-format", "--branch", f"{branch_prefix}TASK"],
9001
11093
  cwd=repo,
9002
11094
  check=False,
9003
11095
  ).returncode != 0:
9004
11096
  validation_errors.append("concurrency.branch_prefix does not form a valid Git branch")
9005
- if not str(project_cfg.get("name") or "").strip():
11097
+ raw_project_name = project_cfg.get("name")
11098
+ if raw_project_name is not None and not isinstance(raw_project_name, str):
11099
+ validation_errors.append("project.name must be a string")
11100
+ if not isinstance(raw_project_name, str) or not raw_project_name.strip():
9006
11101
  missing.append("project.name")
9007
11102
  missing.extend(_access_config_issues(cfg))
9008
- enforcement = _text(structure_cfg.get("enforcement")).lower()
11103
+ raw_enforcement = structure_cfg.get("enforcement")
11104
+ if raw_enforcement is not None and not isinstance(raw_enforcement, str):
11105
+ validation_errors.append("structure.enforcement must be a string")
11106
+ enforcement = ""
11107
+ else:
11108
+ enforcement = raw_enforcement.strip().lower() if isinstance(raw_enforcement, str) else ""
9009
11109
  if enforcement and enforcement not in {"advisory", "blocking"}:
9010
11110
  validation_errors.append("structure.enforcement must be advisory or blocking")
9011
11111
  raw_block_warnings = structure_cfg.get("block_warnings")
@@ -9017,7 +11117,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9017
11117
  )
9018
11118
  gate_cfg = _gate_cfg(cfg)
9019
11119
  if "full_on" in gate_cfg:
9020
- validation_errors.append("gate.full_on is legacy automatic full escalation; run ap.py upgrade")
11120
+ validation_errors.append("gate.full_on is legacy automatic full escalation; run autocoding init")
9021
11121
  raw_rules = gate_cfg.get("rules") or []
9022
11122
  rules_valid = isinstance(raw_rules, list)
9023
11123
  if not rules_valid:
@@ -9038,12 +11138,12 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9038
11138
  if "scope" in rule:
9039
11139
  rules_valid = False
9040
11140
  validation_errors.append(
9041
- f"gate.rules[{index}].scope is legacy automatic gate escalation; run ap.py upgrade"
11141
+ f"gate.rules[{index}].scope is legacy automatic gate escalation; run autocoding init"
9042
11142
  )
9043
11143
  if "commands" in rule:
9044
11144
  rules_valid = False
9045
11145
  validation_errors.append(
9046
- f"gate.rules[{index}].commands is legacy automatic gate escalation; run ap.py upgrade"
11146
+ f"gate.rules[{index}].commands is legacy automatic gate escalation; run autocoding init"
9047
11147
  )
9048
11148
 
9049
11149
  risk_rules = _risk_cfg(cfg).get("rules") or []
@@ -9063,8 +11163,13 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9063
11163
  )
9064
11164
 
9065
11165
  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"}:
11166
+ raw_on_unmapped = validation_cfg.get("on_unmapped", "error")
11167
+ if not isinstance(raw_on_unmapped, str):
11168
+ validation_errors.append("validation.on_unmapped must be a string")
11169
+ on_unmapped = ""
11170
+ else:
11171
+ on_unmapped = raw_on_unmapped.strip().lower() or "error"
11172
+ if on_unmapped and on_unmapped not in {"error", "fallback"}:
9068
11173
  validation_errors.append("validation.on_unmapped must be error or fallback")
9069
11174
  try:
9070
11175
  final_budget = _final_gate_budget(cfg)
@@ -9188,19 +11293,27 @@ def cmd_doctor(args: argparse.Namespace) -> None:
9188
11293
  missing.extend(validation_errors)
9189
11294
 
9190
11295
  if missing:
9191
- _record_evidence(repo, cfg, "doctor", "fail", {"issues": missing})
11296
+ if record:
11297
+ _record_evidence(repo, cfg, "doctor", "fail", {"issues": missing})
11298
+ if collect:
11299
+ return {"issues": missing, "advisories": advisories}
9192
11300
  raise APError("Doctor found blocking config issues:\n- " + "\n- ".join(missing))
9193
11301
 
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")
11302
+ if record:
11303
+ _record_evidence(
11304
+ repo,
11305
+ cfg,
11306
+ "doctor",
11307
+ "pass",
11308
+ {"mode": mode, "completion": completion, "access_fields": len(_REQUIRED_ACCESS_FIELDS)},
11309
+ )
11310
+ if collect:
11311
+ return {"issues": [], "advisories": advisories}
11312
+ if not quiet:
11313
+ for advisory in advisories:
11314
+ print(f"[doctor] WARN: {advisory}")
11315
+ print("[doctor] OK")
11316
+ return None
9204
11317
 
9205
11318
 
9206
11319
  def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
@@ -10456,6 +12569,9 @@ def cmd_task_start(args: argparse.Namespace) -> None:
10456
12569
  or getattr(args, "force_lifecycle", False)
10457
12570
  or continue_direct
10458
12571
  )
12572
+ # Validate legacy workflow policy before planning reads gate/risk rules so
12573
+ # task-start reports the complete migration set and remains zero-write.
12574
+ _require_workflow_policy_clean(repo, cfg)
10459
12575
  preflight_plan = _resolve_execution_plan(
10460
12576
  cfg,
10461
12577
  repo,
@@ -10478,12 +12594,11 @@ def cmd_task_start(args: argparse.Namespace) -> None:
10478
12594
  "only when classify requires isolation/review or the user explicitly requests it."
10479
12595
  )
10480
12596
 
10481
- _require_workflow_policy_clean(repo, cfg)
10482
12597
  configured_isolation = _task_isolation(cfg)
10483
12598
  access_issues = _access_config_issues(cfg)
10484
12599
  if access_issues:
10485
12600
  raise APError(
10486
- "Project initialization is incomplete; fill docs/ENGINEERING.md before starting work:\n- "
12601
+ "Project initialization is incomplete; fill docs/project/auto-coding-skill.yaml before starting work:\n- "
10487
12602
  + "\n- ".join(access_issues)
10488
12603
  )
10489
12604
  remote, target_branch, base_ref = _task_remote_and_target(cfg, args)
@@ -13746,6 +15861,12 @@ def main(argv: Optional[List[str]] = None) -> int:
13746
15861
  s.add_argument("--json", action="store_true")
13747
15862
  s.set_defaults(func=cmd_scaffold)
13748
15863
 
15864
+ s = sp.add_parser("managed-scaffold-converge", help=argparse.SUPPRESS)
15865
+ s.add_argument("group", choices=scaffold_groups())
15866
+ s.add_argument("--write", action="store_true")
15867
+ s.add_argument("--json", action="store_true")
15868
+ s.set_defaults(func=cmd_managed_scaffold_converge)
15869
+
13749
15870
  s = sp.add_parser("upgrade")
13750
15871
  s.add_argument("--dry-run", action="store_true")
13751
15872
  s.add_argument("--write", action="store_true")
@@ -13757,6 +15878,49 @@ def main(argv: Optional[List[str]] = None) -> int:
13757
15878
  s.add_argument("--json", action="store_true")
13758
15879
  s.set_defaults(func=cmd_project_converge)
13759
15880
 
15881
+ s = sp.add_parser("project-config-prepare", help=argparse.SUPPRESS)
15882
+ s.add_argument("--write", action="store_true")
15883
+ s.add_argument("--json", action="store_true")
15884
+ s.set_defaults(func=cmd_project_config_prepare)
15885
+
15886
+ s = sp.add_parser("project-config-finalize", help=argparse.SUPPRESS)
15887
+ s.add_argument("--write", action="store_true")
15888
+ s.add_argument("--json", action="store_true")
15889
+ s.add_argument("--engineering-sha256", required=True)
15890
+ s.add_argument("--overlay-sha256", required=True)
15891
+ s.add_argument("--template-sha256", required=True)
15892
+ s.set_defaults(func=cmd_project_config_finalize)
15893
+
15894
+ s = sp.add_parser("project-file-safe", help=argparse.SUPPRESS)
15895
+ s.add_argument("operation", choices=["write", "create", "chmod", "chmod-batch"])
15896
+ s.add_argument("--path", default="")
15897
+ s.add_argument("--mode", default="")
15898
+ s.add_argument("--json", action="store_true")
15899
+ s.set_defaults(func=cmd_project_file_safe)
15900
+
15901
+ s = sp.add_parser("install-io", help=argparse.SUPPRESS)
15902
+ s.add_argument("operation", choices=["switch", "recover", "complete"])
15903
+ s.add_argument("--old-skill-present", action="store_true")
15904
+ s.add_argument("--old-manifest-present", action="store_true")
15905
+ s.add_argument("--old-engineering-present", action="store_true")
15906
+ s.add_argument("--json", action="store_true")
15907
+ s.set_defaults(func=cmd_install_io)
15908
+
15909
+ s = sp.add_parser(
15910
+ "config-effective",
15911
+ help="Show a redacted summary of managed defaults plus project overrides",
15912
+ )
15913
+ s.add_argument("--json", action="store_true")
15914
+ s.set_defaults(func=cmd_config_effective)
15915
+
15916
+ s = sp.add_parser(
15917
+ "feedback-collect",
15918
+ help="Read bounded metadata-only Skill feedback reports from explicit projects",
15919
+ )
15920
+ s.add_argument("--project", action="append", required=True)
15921
+ s.add_argument("--json", action="store_true")
15922
+ s.set_defaults(func=cmd_feedback_collect)
15923
+
13760
15924
  s = sp.add_parser("baseline")
13761
15925
  baseline_sp = s.add_subparsers(dest="baseline_cmd", required=True)
13762
15926
  b = baseline_sp.add_parser("init")
@@ -14060,6 +16224,24 @@ def main(argv: Optional[List[str]] = None) -> int:
14060
16224
 
14061
16225
  try:
14062
16226
  args = p.parse_args(argv)
16227
+ repo = Path(args.repo).resolve()
16228
+ tokenized_write = (
16229
+ args.cmd == "project-file-safe"
16230
+ or (
16231
+ args.cmd in {
16232
+ "managed-scaffold-converge",
16233
+ "project-config-finalize",
16234
+ "project-converge",
16235
+ }
16236
+ and bool(getattr(args, "write", False))
16237
+ )
16238
+ )
16239
+ if args.cmd == "install-io":
16240
+ pass
16241
+ elif tokenized_write:
16242
+ _require_active_install_transaction(repo)
16243
+ elif args.cmd != "config-effective":
16244
+ _require_no_install_transaction(repo)
14063
16245
  args.func(args)
14064
16246
  return 0
14065
16247
  except APError as e: