@elvis1513/auto-coding-skill 4.3.0 → 4.3.2

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.
@@ -57,6 +57,7 @@ from install_integrity import verify_managed_install
57
57
  from scaffold_templates import (
58
58
  MANAGED_FRAMEWORK_DOCS,
59
59
  PROJECT_FEEDBACK_PATTERNS,
60
+ PROJECT_OWNED_DOC_ROOTS,
60
61
  scaffold_groups,
61
62
  templates_for,
62
63
  )
@@ -100,8 +101,14 @@ _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
100
101
  _REVIEW_DIFF_ARTIFACT_FORMAT = "git-binary-patch-v1"
101
102
  _REVIEW_DIFF_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024
102
103
  _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"
104
+ _FEEDBACK_SCHEMAS = {
105
+ "auto-coding-skill-feedback/v1",
106
+ "auto-coding-skill-feedback/v2",
107
+ }
108
+ _FEEDBACK_COLLECTION_SCHEMA = "auto-coding-skill-feedback-collection/v2"
109
+ _FEEDBACK_RESOLUTION_SCHEMA = "auto-coding-skill-feedback-resolutions/v1"
110
+ _FEEDBACK_RESOLUTION_POLICY = Path("data/policies/feedback-resolutions-v1.json")
111
+ _FEEDBACK_RESOLUTION_MAX_BYTES = 64 * 1024
105
112
  _FEEDBACK_REPORT_MAX_BYTES = 16 * 1024
106
113
  _FEEDBACK_PROJECT_MAX_REPORTS = 100
107
114
  _FEEDBACK_PROJECT_MAX_ENTRIES = 200
@@ -114,7 +121,7 @@ _EFFECTIVE_CONFIG_PATHS = {
114
121
  "docs/ENGINEERING.md",
115
122
  _PROJECT_CONFIG_RELATIVE.as_posix(),
116
123
  }
117
- _FEEDBACK_FIELDS = (
124
+ _FEEDBACK_V1_FIELDS = (
118
125
  "schema",
119
126
  "report_id",
120
127
  "status",
@@ -129,7 +136,14 @@ _FEEDBACK_FIELDS = (
129
136
  "signature",
130
137
  "export",
131
138
  )
139
+ _FEEDBACK_V2_FIELDS = (
140
+ *_FEEDBACK_V1_FIELDS,
141
+ "updated_at",
142
+ "last_verified_skill_version",
143
+ "resolution",
144
+ )
132
145
  _FEEDBACK_STATUSES = {"open", "needs-evidence", "accepted", "duplicate", "resolved", "rejected"}
146
+ _FEEDBACK_ACTIVE_STATUSES = {"open", "needs-evidence", "accepted"}
133
147
  _FEEDBACK_KINDS = {"defect", "gap"}
134
148
  _FEEDBACK_IMPACTS = {"blocking", "degraded", "minor"}
135
149
  _FEEDBACK_ORIGIN_SURFACES = {
@@ -139,6 +153,23 @@ _FEEDBACK_ORIGIN_SURFACES = {
139
153
  "cli",
140
154
  "installer",
141
155
  }
156
+ _FEEDBACK_RESOLUTIONS = {
157
+ "pending",
158
+ "fixed",
159
+ "duplicate",
160
+ "project-config",
161
+ "environment",
162
+ "not-shared",
163
+ "not-reproducible",
164
+ "wont-fix",
165
+ }
166
+ _FEEDBACK_CATALOG_DISPOSITIONS = {
167
+ "fixed",
168
+ "project-config",
169
+ "environment",
170
+ "duplicate",
171
+ "rejected",
172
+ }
142
173
  _FEEDBACK_HEADINGS = (
143
174
  "Symptom",
144
175
  "Expected",
@@ -256,7 +287,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
256
287
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
257
288
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
258
289
  "schema_version": 1,
259
- "managed_versions": {"agents": "4.3.0", "engineering": "4.3.0"},
290
+ "managed_versions": {"agents": "4.3.2", "engineering": "4.3.2"},
260
291
  "known_official_engineering_body_sha256": [
261
292
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
262
293
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -1402,17 +1433,7 @@ def cmd_project_config_finalize(args: argparse.Namespace) -> None:
1402
1433
  print(f"[project-config-finalize] {item['action']}: {item['path']}")
1403
1434
 
1404
1435
 
1405
- _PROJECT_ARTIFACT_PATTERNS = (
1406
- "docs/architecture/*.md",
1407
- "docs/architecture/adr/*.md",
1408
- "docs/deployment/deploy-records/*.md",
1409
- "docs/design/*.md",
1410
- "docs/interfaces/*.md",
1411
- "docs/project/*.md",
1412
- _PROJECT_CONFIG_RELATIVE.as_posix(),
1413
- "docs/reviews/*.md",
1414
- *PROJECT_FEEDBACK_PATTERNS,
1415
- )
1436
+ _PROJECT_ARTIFACT_ROOTS = tuple(Path(value) for value in PROJECT_OWNED_DOC_ROOTS)
1416
1437
 
1417
1438
 
1418
1439
  def _safe_project_relative_path(rel: str | Path) -> Path:
@@ -2519,7 +2540,7 @@ def _is_allowed_project_doc(rel: Path, candidate: Path | None = None) -> bool:
2519
2540
  return candidate is None or (candidate.is_file() and not candidate.is_symlink())
2520
2541
  if any(rel.match(pattern) for pattern in PROJECT_FEEDBACK_PATTERNS):
2521
2542
  return candidate is None or (candidate.is_file() and not candidate.is_symlink())
2522
- return any(rel.match(pattern) for pattern in _PROJECT_ARTIFACT_PATTERNS)
2543
+ return any(rel == root or root in rel.parents for root in _PROJECT_ARTIFACT_ROOTS)
2523
2544
 
2524
2545
 
2525
2546
  def cmd_project_converge(args: argparse.Namespace) -> None:
@@ -2631,20 +2652,20 @@ def cmd_project_converge(args: argparse.Namespace) -> None:
2631
2652
  docs_root = repo / "docs"
2632
2653
  if docs_root.exists():
2633
2654
  for candidate in sorted(docs_root.rglob("*")):
2634
- if not candidate.is_file() and not candidate.is_symlink():
2655
+ try:
2656
+ candidate_metadata = candidate.lstat()
2657
+ except OSError as exc:
2658
+ raise APError("Cannot inspect active project documentation safely") from exc
2659
+ if stat.S_ISDIR(candidate_metadata.st_mode) and not _is_windows_reparse_point(candidate_metadata):
2635
2660
  continue
2636
2661
  rel = candidate.relative_to(repo)
2662
+ if _is_windows_reparse_point(candidate_metadata) or not stat.S_ISREG(candidate_metadata.st_mode):
2663
+ raise APError(
2664
+ "Active project documentation must contain only real directories and "
2665
+ f"regular non-symlink files: {rel.as_posix()}"
2666
+ )
2637
2667
  if rel in allowed_docs or _is_allowed_project_doc(rel, candidate):
2638
2668
  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()
2647
- continue
2648
2669
  archive_extra(candidate, "removed from the exact docs framework")
2649
2670
  actions.append({"action": "delete", "path": rel.as_posix()})
2650
2671
  if args.write:
@@ -3008,7 +3029,7 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
3008
3029
  archive_content = archive_header + engineering_plan["original"]
3009
3030
  archive_rel, archive_required = _select_project_archive_target(
3010
3031
  repo,
3011
- Path("docs/archive/workflow") / f"ENGINEERING.pre-{version}.md",
3032
+ Path(".agents/archive/auto-coding-skill") / version / "workflow/ENGINEERING.md",
3012
3033
  archive_content.encode("utf-8"),
3013
3034
  legacy_digest_payload=engineering_plan["original"].encode("utf-8"),
3014
3035
  )
@@ -3068,9 +3089,14 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
3068
3089
  canonical_agents = template_agents.read_text(encoding="utf-8") if template_agents.exists() else ""
3069
3090
  current_agents = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
3070
3091
  if canonical_agents and current_agents != canonical_agents:
3092
+ agents_version_match = re.search(
3093
+ r"auto-coding-skill:managed-agents:start\s+version=([0-9]+\.[0-9]+\.[0-9]+)",
3094
+ canonical_agents,
3095
+ )
3096
+ agents_version = agents_version_match.group(1) if agents_version_match else "current"
3071
3097
  if current_agents:
3072
3098
  archive_header = (
3073
- "# Archived AGENTS.md before auto-coding-skill 4.3.0\n\n"
3099
+ f"# Archived AGENTS.md before auto-coding-skill {agents_version}\n\n"
3074
3100
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
3075
3101
  "Move project configuration into docs/project/auto-coding-skill.yaml and facts into docs/project/,\n"
3076
3102
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
@@ -3078,7 +3104,7 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
3078
3104
  archive_content = archive_header + current_agents
3079
3105
  archive_rel, archive_required = _select_project_archive_target(
3080
3106
  repo,
3081
- Path("docs/archive/workflow/AGENTS.pre-4.3.0.md"),
3107
+ Path(".agents/archive/auto-coding-skill") / agents_version / "AGENTS.md",
3082
3108
  archive_content.encode("utf-8"),
3083
3109
  legacy_digest_payload=current_agents.encode("utf-8"),
3084
3110
  )
@@ -3843,13 +3869,13 @@ def _feedback_scalar(data: dict, field: str, path: Path) -> str:
3843
3869
  return value.strip()
3844
3870
 
3845
3871
 
3846
- def _feedback_created_at(value: object, path: Path) -> str:
3872
+ def _feedback_timestamp(value: object, path: Path, field: str) -> str:
3847
3873
  if isinstance(value, _dt.datetime):
3848
3874
  return value.isoformat()
3849
3875
  if isinstance(value, _dt.date):
3850
3876
  return value.isoformat()
3851
3877
  if not isinstance(value, str) or not value.strip():
3852
- raise _feedback_error(path, "created_at must be an ISO-8601 date or timestamp")
3878
+ raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp")
3853
3879
  raw = value.strip()
3854
3880
  try:
3855
3881
  if "T" in raw or " " in raw:
@@ -3857,7 +3883,7 @@ def _feedback_created_at(value: object, path: Path) -> str:
3857
3883
  else:
3858
3884
  _dt.date.fromisoformat(raw)
3859
3885
  except ValueError as exc:
3860
- raise _feedback_error(path, "created_at must be an ISO-8601 date or timestamp") from exc
3886
+ raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp") from exc
3861
3887
  return raw
3862
3888
 
3863
3889
 
@@ -3882,8 +3908,12 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3882
3908
  raise _feedback_error(path, "YAML frontmatter must be a flat mapping")
3883
3909
  if any(not isinstance(key, str) for key in data):
3884
3910
  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]
3911
+ schema_value = _feedback_scalar(data, "schema", path)
3912
+ if schema_value not in _FEEDBACK_SCHEMAS:
3913
+ raise _feedback_error(path, "schema must be auto-coding-skill-feedback/v1 or /v2")
3914
+ expected_fields = _FEEDBACK_V2_FIELDS if schema_value.endswith("/v2") else _FEEDBACK_V1_FIELDS
3915
+ unknown = sorted(set(data) - set(expected_fields))
3916
+ missing = [field for field in expected_fields if field not in data]
3887
3917
  if unknown:
3888
3918
  raise _feedback_error(path, "unknown frontmatter fields are not allowed")
3889
3919
  if missing:
@@ -3892,9 +3922,6 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3892
3922
  raise _feedback_error(path, "frontmatter values must be scalars")
3893
3923
 
3894
3924
  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
3925
  metadata["schema"] = schema_value
3899
3926
  report_id = _feedback_scalar(data, "report_id", path)
3900
3927
  if not _FEEDBACK_SAFE_ID_RE.fullmatch(report_id):
@@ -3904,7 +3931,12 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3904
3931
  if status_value not in _FEEDBACK_STATUSES:
3905
3932
  raise _feedback_error(path, "status is not supported")
3906
3933
  metadata["status"] = status_value
3907
- metadata["created_at"] = _feedback_created_at(data.get("created_at"), path)
3934
+ metadata["created_at"] = _feedback_timestamp(data.get("created_at"), path, "created_at")
3935
+ metadata["updated_at"] = (
3936
+ _feedback_timestamp(data.get("updated_at"), path, "updated_at")
3937
+ if schema_value.endswith("/v2")
3938
+ else metadata["created_at"]
3939
+ )
3908
3940
  project_value = _feedback_scalar(data, "project", path)
3909
3941
  if not _FEEDBACK_SAFE_ID_RE.fullmatch(project_value):
3910
3942
  raise _feedback_error(path, "project must be a safe identifier")
@@ -3913,6 +3945,13 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3913
3945
  if not _FEEDBACK_SEMVER_RE.fullmatch(version):
3914
3946
  raise _feedback_error(path, "observed_skill_version must be valid SemVer")
3915
3947
  metadata["observed_skill_version"] = version
3948
+ if schema_value.endswith("/v2"):
3949
+ last_verified = _feedback_scalar(data, "last_verified_skill_version", path)
3950
+ if not _FEEDBACK_SEMVER_RE.fullmatch(last_verified):
3951
+ raise _feedback_error(path, "last_verified_skill_version must be valid SemVer")
3952
+ else:
3953
+ last_verified = version
3954
+ metadata["last_verified_skill_version"] = last_verified
3916
3955
  component = _feedback_scalar(data, "component", path)
3917
3956
  if not _FEEDBACK_SLUG_RE.fullmatch(component):
3918
3957
  raise _feedback_error(path, "component must be a lowercase kebab-case slug")
@@ -3937,6 +3976,33 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3937
3976
  if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
3938
3977
  raise _feedback_error(path, "signature must be sha256 followed by 64 lowercase hex characters")
3939
3978
  metadata["signature"] = signature
3979
+ if schema_value.endswith("/v2"):
3980
+ resolution = _feedback_scalar(data, "resolution", path)
3981
+ if resolution not in _FEEDBACK_RESOLUTIONS:
3982
+ raise _feedback_error(path, "resolution is not supported")
3983
+ if status_value in _FEEDBACK_ACTIVE_STATUSES and resolution != "pending":
3984
+ raise _feedback_error(path, "active status requires resolution=pending")
3985
+ if status_value == "resolved" and resolution != "fixed":
3986
+ raise _feedback_error(path, "status=resolved requires resolution=fixed")
3987
+ if status_value == "duplicate" and resolution != "duplicate":
3988
+ raise _feedback_error(path, "status=duplicate requires resolution=duplicate")
3989
+ if status_value == "rejected" and resolution not in {
3990
+ "project-config",
3991
+ "environment",
3992
+ "not-shared",
3993
+ "not-reproducible",
3994
+ "wont-fix",
3995
+ }:
3996
+ raise _feedback_error(path, "status=rejected requires a supported rejected resolution")
3997
+ elif status_value in _FEEDBACK_ACTIVE_STATUSES:
3998
+ resolution = "pending"
3999
+ elif status_value == "resolved":
4000
+ resolution = "fixed"
4001
+ elif status_value == "duplicate":
4002
+ resolution = "duplicate"
4003
+ else:
4004
+ resolution = "not-shared"
4005
+ metadata["resolution"] = resolution
3940
4006
  export_value = _feedback_scalar(data, "export", path)
3941
4007
  if export_value != "metadata-only":
3942
4008
  raise _feedback_error(path, "export must be metadata-only")
@@ -4029,22 +4095,101 @@ def _feedback_project_root(raw: str) -> Path:
4029
4095
  return root
4030
4096
 
4031
4097
 
4032
- def _feedback_configured_project(root: Path) -> str:
4098
+ def _feedback_configured_project(root: Path) -> tuple[str, str]:
4033
4099
  config = load_effective_config(root)
4034
4100
  name = _text(_mapping(config.get("project")).get("name"))
4035
4101
  if not _FEEDBACK_SAFE_ID_RE.fullmatch(name):
4036
4102
  raise APError("Effective project.name must be a safe non-empty identifier for feedback")
4037
- return name
4103
+ version = _text(_mapping(config.get("workflow")).get("skill_version"))
4104
+ if not _FEEDBACK_SEMVER_RE.fullmatch(version):
4105
+ raise APError("Effective workflow.skill_version must be valid SemVer for feedback")
4106
+ return name, version
4107
+
4108
+
4109
+ def _feedback_release_at_least(current: str, required: str) -> bool:
4110
+ def parts(value: str) -> tuple[tuple[int, int, int], bool]:
4111
+ match = re.fullmatch(r"([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([^+]+))?(?:\+.+)?", value)
4112
+ if not match:
4113
+ raise APError("Skill feedback version comparison requires valid SemVer")
4114
+ return tuple(int(match.group(index)) for index in range(1, 4)), bool(match.group(4))
4115
+
4116
+ current_core, current_prerelease = parts(current)
4117
+ required_core, required_prerelease = parts(required)
4118
+ if current_core != required_core:
4119
+ return current_core > required_core
4120
+ if current_prerelease != required_prerelease:
4121
+ return not current_prerelease
4122
+ return current == required or (not current_prerelease and not required_prerelease)
4123
+
4124
+
4125
+ def _load_feedback_resolution_catalog() -> dict[str, dict[str, str]]:
4126
+ path = _skill_root() / _FEEDBACK_RESOLUTION_POLICY
4127
+ try:
4128
+ metadata = path.lstat()
4129
+ except OSError as exc:
4130
+ raise APError("Managed Skill feedback resolution catalog is missing") from exc
4131
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
4132
+ raise APError("Managed Skill feedback resolution catalog must be a regular non-symlink file")
4133
+ if metadata.st_size > _FEEDBACK_RESOLUTION_MAX_BYTES:
4134
+ raise APError("Managed Skill feedback resolution catalog exceeds its size limit")
4135
+ try:
4136
+ payload = path.read_bytes()
4137
+ value = json.loads(payload)
4138
+ except (OSError, json.JSONDecodeError) as exc:
4139
+ raise APError("Managed Skill feedback resolution catalog is invalid") from exc
4140
+ if not isinstance(value, dict) or set(value) != {"schema", "entries"}:
4141
+ raise APError("Managed Skill feedback resolution catalog has an invalid top-level contract")
4142
+ if value.get("schema") != _FEEDBACK_RESOLUTION_SCHEMA or not isinstance(value.get("entries"), list):
4143
+ raise APError("Managed Skill feedback resolution catalog schema is invalid")
4144
+ catalog: dict[str, dict[str, str]] = {}
4145
+ ordered_signatures: list[str] = []
4146
+ for index, raw in enumerate(value["entries"]):
4147
+ if not isinstance(raw, dict):
4148
+ raise APError(f"Managed Skill feedback resolution entry {index} must be an object")
4149
+ allowed = {"signature", "disposition", "effective_skill_version", "canonical_signature"}
4150
+ if set(raw) - allowed or not {"signature", "disposition", "effective_skill_version"}.issubset(raw):
4151
+ raise APError(f"Managed Skill feedback resolution entry {index} has invalid fields")
4152
+ if any(not isinstance(item, str) or not item.strip() for item in raw.values()):
4153
+ raise APError(f"Managed Skill feedback resolution entry {index} values must be non-empty strings")
4154
+ signature = raw["signature"].strip()
4155
+ disposition = raw["disposition"].strip()
4156
+ effective = raw["effective_skill_version"].strip()
4157
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
4158
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid signature")
4159
+ if disposition not in _FEEDBACK_CATALOG_DISPOSITIONS:
4160
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid disposition")
4161
+ if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", effective):
4162
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid release version")
4163
+ canonical = _text(raw.get("canonical_signature"))
4164
+ if disposition == "duplicate":
4165
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(canonical) or canonical == signature:
4166
+ raise APError(f"Managed Skill feedback resolution entry {index} needs a distinct canonical signature")
4167
+ elif canonical:
4168
+ raise APError(f"Managed Skill feedback resolution entry {index} cannot set canonical_signature")
4169
+ if signature in catalog:
4170
+ raise APError("Managed Skill feedback resolution catalog contains duplicate signatures")
4171
+ entry = {
4172
+ "signature": signature,
4173
+ "disposition": disposition,
4174
+ "effective_skill_version": effective,
4175
+ }
4176
+ if canonical:
4177
+ entry["canonical_signature"] = canonical
4178
+ catalog[signature] = entry
4179
+ ordered_signatures.append(signature)
4180
+ if ordered_signatures != sorted(ordered_signatures):
4181
+ raise APError("Managed Skill feedback resolution entries must be sorted by signature")
4182
+ return catalog
4038
4183
 
4039
4184
 
4040
4185
  def _collect_project_feedback(
4041
4186
  root: Path,
4042
- ) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str | None]:
4187
+ ) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str, str]:
4043
4188
  reports_relative = Path("docs/skill-feedback/reports")
4044
- configured_project = _feedback_configured_project(root)
4189
+ configured_project, installed_skill_version = _feedback_configured_project(root)
4045
4190
  with _open_project_directory(root, reports_relative) as directory_fd:
4046
4191
  if directory_fd is None:
4047
- return [], 0, None, set(), configured_project
4192
+ return [], 0, None, set(), configured_project, installed_skill_version
4048
4193
  directory_metadata = (
4049
4194
  directory_fd.stat() if isinstance(directory_fd, Path) else os.fstat(directory_fd)
4050
4195
  )
@@ -4099,13 +4244,77 @@ def _collect_project_feedback(
4099
4244
  report["size_bytes"] = size
4100
4245
  reports.append(report)
4101
4246
  total_bytes += size
4102
- return reports, total_bytes, directory_identity, file_identities, configured_project
4247
+ return (
4248
+ reports,
4249
+ total_bytes,
4250
+ directory_identity,
4251
+ file_identities,
4252
+ configured_project,
4253
+ installed_skill_version,
4254
+ )
4103
4255
 
4104
4256
 
4105
- def cmd_feedback_collect(args: argparse.Namespace) -> None:
4106
- raw_projects = list(args.project or [])
4257
+ def _feedback_lifecycle(
4258
+ report: dict,
4259
+ installed_skill_version: str,
4260
+ catalog: dict[str, dict[str, str]],
4261
+ ) -> tuple[str, str, dict[str, str] | None]:
4262
+ if report["status"] not in _FEEDBACK_ACTIVE_STATUSES:
4263
+ return "closed", "none", catalog.get(report["signature"])
4264
+ catalog_entry = catalog.get(report["signature"])
4265
+ if catalog_entry:
4266
+ effective = catalog_entry["effective_skill_version"]
4267
+ if not _feedback_release_at_least(installed_skill_version, effective):
4268
+ return "upgrade-due", "upgrade-project-then-verify", catalog_entry
4269
+ disposition = catalog_entry["disposition"]
4270
+ if disposition == "fixed":
4271
+ if report["last_verified_skill_version"] == installed_skill_version:
4272
+ return "regression-current", "none", catalog_entry
4273
+ if _feedback_release_at_least(report["last_verified_skill_version"], effective):
4274
+ return (
4275
+ "recheck-due",
4276
+ "reproduce-on-installed-version-and-update-or-close",
4277
+ catalog_entry,
4278
+ )
4279
+ return "verification-due", "verify-fix-then-resolve-or-delete", catalog_entry
4280
+ if disposition == "project-config":
4281
+ return (
4282
+ "reroute-due",
4283
+ "move-to-docs/project/auto-coding-skill.yaml-then-reject-or-delete",
4284
+ catalog_entry,
4285
+ )
4286
+ return "closure-due", "update-closed-status-or-delete", catalog_entry
4287
+ if report["last_verified_skill_version"] != installed_skill_version:
4288
+ return "recheck-due", "reproduce-on-installed-version-and-update-or-close", None
4289
+ return "active-current", "none", None
4290
+
4291
+
4292
+ def _feedback_groups(reports: list[dict]) -> list[dict]:
4293
+ grouped: dict[str, list[dict]] = {}
4294
+ for report in reports:
4295
+ grouped.setdefault(report["signature"], []).append(report)
4296
+ groups: list[dict] = []
4297
+ for signature, items in sorted(grouped.items()):
4298
+ projects = sorted({item["project"] for item in items})
4299
+ group_source_projects = sorted({item["source_project"] for item in items})
4300
+ groups.append(
4301
+ {
4302
+ "signature": signature,
4303
+ "report_count": len(items),
4304
+ "project_count": len(group_source_projects),
4305
+ "projects": projects,
4306
+ "source_projects": group_source_projects,
4307
+ "report_ids": [item["report_id"] for item in items],
4308
+ "cross_project": len(group_source_projects) > 1,
4309
+ }
4310
+ )
4311
+ return groups
4312
+
4313
+
4314
+ def _feedback_collection_result(raw_projects: list[str]) -> dict:
4107
4315
  if not raw_projects:
4108
4316
  raise APError("feedback-collect requires at least one explicit --project")
4317
+ catalog = _load_feedback_resolution_catalog()
4109
4318
  roots: list[Path] = []
4110
4319
  seen_roots: set[str] = set()
4111
4320
  for raw in raw_projects:
@@ -4133,6 +4342,7 @@ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4133
4342
  directory_identity,
4134
4343
  file_identities,
4135
4344
  configured_project,
4345
+ installed_skill_version,
4136
4346
  ) = _collect_project_feedback(root)
4137
4347
  if directory_identity is not None:
4138
4348
  if directory_identity in seen_report_directories:
@@ -4141,13 +4351,14 @@ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4141
4351
  if seen_report_files.intersection(file_identities):
4142
4352
  raise APError("Explicit projects contain the same physical Skill feedback report file")
4143
4353
  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
4354
+ if configured_project in seen_configured_projects:
4355
+ raise APError("Explicit projects must have distinct effective project.name values")
4356
+ seen_configured_projects.add(configured_project)
4357
+ source_descriptor = {
4358
+ "source_project": source_id,
4359
+ "project": configured_project,
4360
+ "skill_version": installed_skill_version,
4361
+ }
4151
4362
  source_projects.append(source_descriptor)
4152
4363
  total_bytes += project_bytes
4153
4364
  if total_bytes > _FEEDBACK_COLLECTION_MAX_BYTES:
@@ -4160,45 +4371,89 @@ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4160
4371
  )
4161
4372
  for report in project_reports:
4162
4373
  report["source_project"] = source_id
4374
+ report["installed_skill_version"] = installed_skill_version
4375
+ lifecycle, recommended_action, catalog_entry = _feedback_lifecycle(
4376
+ report,
4377
+ installed_skill_version,
4378
+ catalog,
4379
+ )
4380
+ report["lifecycle"] = lifecycle
4381
+ report["recommended_action"] = recommended_action
4382
+ if catalog_entry:
4383
+ report["catalog_disposition"] = catalog_entry["disposition"]
4384
+ report["catalog_effective_skill_version"] = catalog_entry["effective_skill_version"]
4385
+ if catalog_entry.get("canonical_signature"):
4386
+ report["catalog_canonical_signature"] = catalog_entry["canonical_signature"]
4163
4387
  reports.extend(project_reports)
4164
4388
 
4165
4389
  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
- )
4390
+ triage_reports = [
4391
+ report
4392
+ for report in reports
4393
+ if report["lifecycle"] in {"active-current", "regression-current"}
4394
+ ]
4395
+ groups = _feedback_groups(triage_reports)
4184
4396
  cross_project = [group for group in groups if group["cross_project"]]
4185
- result = {
4397
+ lifecycle_counts = {
4398
+ lifecycle: sum(1 for report in reports if report["lifecycle"] == lifecycle)
4399
+ for lifecycle in sorted({report["lifecycle"] for report in reports})
4400
+ }
4401
+ action_required = [
4402
+ {
4403
+ key: report[key]
4404
+ for key in (
4405
+ "source_project",
4406
+ "project",
4407
+ "report_id",
4408
+ "source_path",
4409
+ "signature",
4410
+ "installed_skill_version",
4411
+ "last_verified_skill_version",
4412
+ "lifecycle",
4413
+ "recommended_action",
4414
+ "catalog_disposition",
4415
+ "catalog_effective_skill_version",
4416
+ "catalog_canonical_signature",
4417
+ )
4418
+ if key in report
4419
+ }
4420
+ for report in reports
4421
+ if report["recommended_action"] != "none"
4422
+ ]
4423
+ return {
4186
4424
  "schema": _FEEDBACK_COLLECTION_SCHEMA,
4187
4425
  "projects": source_projects,
4188
4426
  "report_count": len(reports),
4427
+ "active_report_count": len(triage_reports),
4428
+ "closed_report_count": lifecycle_counts.get("closed", 0),
4429
+ "action_required_count": len(action_required),
4189
4430
  "total_bytes": total_bytes,
4431
+ "lifecycle_counts": lifecycle_counts,
4432
+ "action_required": action_required,
4190
4433
  "metadata": reports,
4191
4434
  "groups": groups,
4192
4435
  "cross_project": cross_project,
4193
4436
  }
4437
+
4438
+
4439
+ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4440
+ raw_projects = list(args.project or [])
4441
+ result = _feedback_collection_result(raw_projects)
4194
4442
  if args.json:
4195
4443
  print(json.dumps(result, ensure_ascii=False, indent=2))
4196
4444
  return
4197
4445
  print(
4198
- f"[feedback-collect] projects={len(roots)} reports={len(reports)} "
4199
- f"groups={len(groups)} cross_project={len(cross_project)} bytes={total_bytes}"
4446
+ f"[feedback-collect] projects={len(result['projects'])} reports={result['report_count']} "
4447
+ f"active={result['active_report_count']} closed={result['closed_report_count']} "
4448
+ f"actions={result['action_required_count']} groups={len(result['groups'])} "
4449
+ f"cross_project={len(result['cross_project'])} bytes={result['total_bytes']}"
4200
4450
  )
4201
- for group in groups:
4451
+ for item in result["action_required"]:
4452
+ print(
4453
+ f"[feedback-collect] action={item['recommended_action']} "
4454
+ f"project={item['project']} report={item['report_id']} lifecycle={item['lifecycle']}"
4455
+ )
4456
+ for group in result["groups"]:
4202
4457
  print(
4203
4458
  f"[feedback-collect] signature={group['signature']} "
4204
4459
  f"cross_project={str(group['cross_project']).lower()} "
@@ -11290,6 +11545,27 @@ def cmd_doctor(args: argparse.Namespace) -> dict | None:
11290
11545
  f"install integrity: {issue}" for issue in integrity["errors"]
11291
11546
  )
11292
11547
 
11548
+ if (
11549
+ isinstance(raw_project_name, str)
11550
+ and _FEEDBACK_SAFE_ID_RE.fullmatch(raw_project_name.strip())
11551
+ and _FEEDBACK_SEMVER_RE.fullmatch(skill_version)
11552
+ and (repo / "docs" / "skill-feedback" / "reports").exists()
11553
+ ):
11554
+ try:
11555
+ feedback = _feedback_collection_result([str(repo)])
11556
+ except APError:
11557
+ advisories.append(
11558
+ "Skill feedback metadata needs maintenance; run "
11559
+ "autocoding feedback --projects . --json for the bounded diagnostic"
11560
+ )
11561
+ else:
11562
+ if feedback["action_required_count"]:
11563
+ advisories.append(
11564
+ f"{feedback['action_required_count']} Skill feedback report(s) need recheck, "
11565
+ "closure, upgrade, or project-overlay routing; run "
11566
+ "autocoding feedback --projects . --json"
11567
+ )
11568
+
11293
11569
  missing.extend(validation_errors)
11294
11570
 
11295
11571
  if missing:
@@ -14,7 +14,12 @@ import tomllib
14
14
  from pathlib import Path
15
15
  from typing import Any
16
16
 
17
- from scaffold_templates import MANAGED_FRAMEWORK_DOCS, PROJECT_FEEDBACK_PATTERNS, templates_for
17
+ from scaffold_templates import (
18
+ MANAGED_FRAMEWORK_DOCS,
19
+ PROJECT_FEEDBACK_PATTERNS,
20
+ PROJECT_OWNED_DOC_ROOTS,
21
+ templates_for,
22
+ )
18
23
 
19
24
 
20
25
  SCHEMA_VERSION = 1
@@ -224,14 +229,9 @@ def build_manifest(skill_root: Path, agents_root: Path, version: str) -> dict[st
224
229
  "preserved": [
225
230
  ".agents/archive/**",
226
231
  ".agents/agents/* (except paths listed in entries)",
227
- "docs/project/**",
228
232
  "docs/project/auto-coding-skill.yaml",
229
233
  "docs/architecture/structure-standard.md",
230
- "docs/architecture/adr/[0-9]*.md",
231
- "docs/design/*.md",
232
- "docs/interfaces/*.md",
233
- "docs/deployment/deploy-records/*.md",
234
- "docs/reviews/*.md",
234
+ *(f"{root}/** (except exact-managed entries)" for root in PROJECT_OWNED_DOC_ROOTS),
235
235
  *PROJECT_FEEDBACK_PATTERNS,
236
236
  ],
237
237
  }