@elvis1513/auto-coding-skill 4.3.0 → 4.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.1", "engineering": "4.3.1"},
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:
@@ -3070,7 +3091,7 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
3070
3091
  if canonical_agents and current_agents != canonical_agents:
3071
3092
  if current_agents:
3072
3093
  archive_header = (
3073
- "# Archived AGENTS.md before auto-coding-skill 4.3.0\n\n"
3094
+ "# Archived AGENTS.md before auto-coding-skill 4.3.1\n\n"
3074
3095
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
3075
3096
  "Move project configuration into docs/project/auto-coding-skill.yaml and facts into docs/project/,\n"
3076
3097
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
@@ -3078,7 +3099,7 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
3078
3099
  archive_content = archive_header + current_agents
3079
3100
  archive_rel, archive_required = _select_project_archive_target(
3080
3101
  repo,
3081
- Path("docs/archive/workflow/AGENTS.pre-4.3.0.md"),
3102
+ Path("docs/archive/workflow/AGENTS.pre-4.3.1.md"),
3082
3103
  archive_content.encode("utf-8"),
3083
3104
  legacy_digest_payload=current_agents.encode("utf-8"),
3084
3105
  )
@@ -3843,13 +3864,13 @@ def _feedback_scalar(data: dict, field: str, path: Path) -> str:
3843
3864
  return value.strip()
3844
3865
 
3845
3866
 
3846
- def _feedback_created_at(value: object, path: Path) -> str:
3867
+ def _feedback_timestamp(value: object, path: Path, field: str) -> str:
3847
3868
  if isinstance(value, _dt.datetime):
3848
3869
  return value.isoformat()
3849
3870
  if isinstance(value, _dt.date):
3850
3871
  return value.isoformat()
3851
3872
  if not isinstance(value, str) or not value.strip():
3852
- raise _feedback_error(path, "created_at must be an ISO-8601 date or timestamp")
3873
+ raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp")
3853
3874
  raw = value.strip()
3854
3875
  try:
3855
3876
  if "T" in raw or " " in raw:
@@ -3857,7 +3878,7 @@ def _feedback_created_at(value: object, path: Path) -> str:
3857
3878
  else:
3858
3879
  _dt.date.fromisoformat(raw)
3859
3880
  except ValueError as exc:
3860
- raise _feedback_error(path, "created_at must be an ISO-8601 date or timestamp") from exc
3881
+ raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp") from exc
3861
3882
  return raw
3862
3883
 
3863
3884
 
@@ -3882,8 +3903,12 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3882
3903
  raise _feedback_error(path, "YAML frontmatter must be a flat mapping")
3883
3904
  if any(not isinstance(key, str) for key in data):
3884
3905
  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]
3906
+ schema_value = _feedback_scalar(data, "schema", path)
3907
+ if schema_value not in _FEEDBACK_SCHEMAS:
3908
+ raise _feedback_error(path, "schema must be auto-coding-skill-feedback/v1 or /v2")
3909
+ expected_fields = _FEEDBACK_V2_FIELDS if schema_value.endswith("/v2") else _FEEDBACK_V1_FIELDS
3910
+ unknown = sorted(set(data) - set(expected_fields))
3911
+ missing = [field for field in expected_fields if field not in data]
3887
3912
  if unknown:
3888
3913
  raise _feedback_error(path, "unknown frontmatter fields are not allowed")
3889
3914
  if missing:
@@ -3892,9 +3917,6 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3892
3917
  raise _feedback_error(path, "frontmatter values must be scalars")
3893
3918
 
3894
3919
  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
3920
  metadata["schema"] = schema_value
3899
3921
  report_id = _feedback_scalar(data, "report_id", path)
3900
3922
  if not _FEEDBACK_SAFE_ID_RE.fullmatch(report_id):
@@ -3904,7 +3926,12 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3904
3926
  if status_value not in _FEEDBACK_STATUSES:
3905
3927
  raise _feedback_error(path, "status is not supported")
3906
3928
  metadata["status"] = status_value
3907
- metadata["created_at"] = _feedback_created_at(data.get("created_at"), path)
3929
+ metadata["created_at"] = _feedback_timestamp(data.get("created_at"), path, "created_at")
3930
+ metadata["updated_at"] = (
3931
+ _feedback_timestamp(data.get("updated_at"), path, "updated_at")
3932
+ if schema_value.endswith("/v2")
3933
+ else metadata["created_at"]
3934
+ )
3908
3935
  project_value = _feedback_scalar(data, "project", path)
3909
3936
  if not _FEEDBACK_SAFE_ID_RE.fullmatch(project_value):
3910
3937
  raise _feedback_error(path, "project must be a safe identifier")
@@ -3913,6 +3940,13 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3913
3940
  if not _FEEDBACK_SEMVER_RE.fullmatch(version):
3914
3941
  raise _feedback_error(path, "observed_skill_version must be valid SemVer")
3915
3942
  metadata["observed_skill_version"] = version
3943
+ if schema_value.endswith("/v2"):
3944
+ last_verified = _feedback_scalar(data, "last_verified_skill_version", path)
3945
+ if not _FEEDBACK_SEMVER_RE.fullmatch(last_verified):
3946
+ raise _feedback_error(path, "last_verified_skill_version must be valid SemVer")
3947
+ else:
3948
+ last_verified = version
3949
+ metadata["last_verified_skill_version"] = last_verified
3916
3950
  component = _feedback_scalar(data, "component", path)
3917
3951
  if not _FEEDBACK_SLUG_RE.fullmatch(component):
3918
3952
  raise _feedback_error(path, "component must be a lowercase kebab-case slug")
@@ -3937,6 +3971,33 @@ def _parse_feedback_report(payload: bytes, path: Path) -> dict:
3937
3971
  if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
3938
3972
  raise _feedback_error(path, "signature must be sha256 followed by 64 lowercase hex characters")
3939
3973
  metadata["signature"] = signature
3974
+ if schema_value.endswith("/v2"):
3975
+ resolution = _feedback_scalar(data, "resolution", path)
3976
+ if resolution not in _FEEDBACK_RESOLUTIONS:
3977
+ raise _feedback_error(path, "resolution is not supported")
3978
+ if status_value in _FEEDBACK_ACTIVE_STATUSES and resolution != "pending":
3979
+ raise _feedback_error(path, "active status requires resolution=pending")
3980
+ if status_value == "resolved" and resolution != "fixed":
3981
+ raise _feedback_error(path, "status=resolved requires resolution=fixed")
3982
+ if status_value == "duplicate" and resolution != "duplicate":
3983
+ raise _feedback_error(path, "status=duplicate requires resolution=duplicate")
3984
+ if status_value == "rejected" and resolution not in {
3985
+ "project-config",
3986
+ "environment",
3987
+ "not-shared",
3988
+ "not-reproducible",
3989
+ "wont-fix",
3990
+ }:
3991
+ raise _feedback_error(path, "status=rejected requires a supported rejected resolution")
3992
+ elif status_value in _FEEDBACK_ACTIVE_STATUSES:
3993
+ resolution = "pending"
3994
+ elif status_value == "resolved":
3995
+ resolution = "fixed"
3996
+ elif status_value == "duplicate":
3997
+ resolution = "duplicate"
3998
+ else:
3999
+ resolution = "not-shared"
4000
+ metadata["resolution"] = resolution
3940
4001
  export_value = _feedback_scalar(data, "export", path)
3941
4002
  if export_value != "metadata-only":
3942
4003
  raise _feedback_error(path, "export must be metadata-only")
@@ -4029,22 +4090,101 @@ def _feedback_project_root(raw: str) -> Path:
4029
4090
  return root
4030
4091
 
4031
4092
 
4032
- def _feedback_configured_project(root: Path) -> str:
4093
+ def _feedback_configured_project(root: Path) -> tuple[str, str]:
4033
4094
  config = load_effective_config(root)
4034
4095
  name = _text(_mapping(config.get("project")).get("name"))
4035
4096
  if not _FEEDBACK_SAFE_ID_RE.fullmatch(name):
4036
4097
  raise APError("Effective project.name must be a safe non-empty identifier for feedback")
4037
- return name
4098
+ version = _text(_mapping(config.get("workflow")).get("skill_version"))
4099
+ if not _FEEDBACK_SEMVER_RE.fullmatch(version):
4100
+ raise APError("Effective workflow.skill_version must be valid SemVer for feedback")
4101
+ return name, version
4102
+
4103
+
4104
+ def _feedback_release_at_least(current: str, required: str) -> bool:
4105
+ def parts(value: str) -> tuple[tuple[int, int, int], bool]:
4106
+ match = re.fullmatch(r"([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([^+]+))?(?:\+.+)?", value)
4107
+ if not match:
4108
+ raise APError("Skill feedback version comparison requires valid SemVer")
4109
+ return tuple(int(match.group(index)) for index in range(1, 4)), bool(match.group(4))
4110
+
4111
+ current_core, current_prerelease = parts(current)
4112
+ required_core, required_prerelease = parts(required)
4113
+ if current_core != required_core:
4114
+ return current_core > required_core
4115
+ if current_prerelease != required_prerelease:
4116
+ return not current_prerelease
4117
+ return current == required or (not current_prerelease and not required_prerelease)
4118
+
4119
+
4120
+ def _load_feedback_resolution_catalog() -> dict[str, dict[str, str]]:
4121
+ path = _skill_root() / _FEEDBACK_RESOLUTION_POLICY
4122
+ try:
4123
+ metadata = path.lstat()
4124
+ except OSError as exc:
4125
+ raise APError("Managed Skill feedback resolution catalog is missing") from exc
4126
+ if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
4127
+ raise APError("Managed Skill feedback resolution catalog must be a regular non-symlink file")
4128
+ if metadata.st_size > _FEEDBACK_RESOLUTION_MAX_BYTES:
4129
+ raise APError("Managed Skill feedback resolution catalog exceeds its size limit")
4130
+ try:
4131
+ payload = path.read_bytes()
4132
+ value = json.loads(payload)
4133
+ except (OSError, json.JSONDecodeError) as exc:
4134
+ raise APError("Managed Skill feedback resolution catalog is invalid") from exc
4135
+ if not isinstance(value, dict) or set(value) != {"schema", "entries"}:
4136
+ raise APError("Managed Skill feedback resolution catalog has an invalid top-level contract")
4137
+ if value.get("schema") != _FEEDBACK_RESOLUTION_SCHEMA or not isinstance(value.get("entries"), list):
4138
+ raise APError("Managed Skill feedback resolution catalog schema is invalid")
4139
+ catalog: dict[str, dict[str, str]] = {}
4140
+ ordered_signatures: list[str] = []
4141
+ for index, raw in enumerate(value["entries"]):
4142
+ if not isinstance(raw, dict):
4143
+ raise APError(f"Managed Skill feedback resolution entry {index} must be an object")
4144
+ allowed = {"signature", "disposition", "effective_skill_version", "canonical_signature"}
4145
+ if set(raw) - allowed or not {"signature", "disposition", "effective_skill_version"}.issubset(raw):
4146
+ raise APError(f"Managed Skill feedback resolution entry {index} has invalid fields")
4147
+ if any(not isinstance(item, str) or not item.strip() for item in raw.values()):
4148
+ raise APError(f"Managed Skill feedback resolution entry {index} values must be non-empty strings")
4149
+ signature = raw["signature"].strip()
4150
+ disposition = raw["disposition"].strip()
4151
+ effective = raw["effective_skill_version"].strip()
4152
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
4153
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid signature")
4154
+ if disposition not in _FEEDBACK_CATALOG_DISPOSITIONS:
4155
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid disposition")
4156
+ if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", effective):
4157
+ raise APError(f"Managed Skill feedback resolution entry {index} has an invalid release version")
4158
+ canonical = _text(raw.get("canonical_signature"))
4159
+ if disposition == "duplicate":
4160
+ if not _FEEDBACK_SIGNATURE_RE.fullmatch(canonical) or canonical == signature:
4161
+ raise APError(f"Managed Skill feedback resolution entry {index} needs a distinct canonical signature")
4162
+ elif canonical:
4163
+ raise APError(f"Managed Skill feedback resolution entry {index} cannot set canonical_signature")
4164
+ if signature in catalog:
4165
+ raise APError("Managed Skill feedback resolution catalog contains duplicate signatures")
4166
+ entry = {
4167
+ "signature": signature,
4168
+ "disposition": disposition,
4169
+ "effective_skill_version": effective,
4170
+ }
4171
+ if canonical:
4172
+ entry["canonical_signature"] = canonical
4173
+ catalog[signature] = entry
4174
+ ordered_signatures.append(signature)
4175
+ if ordered_signatures != sorted(ordered_signatures):
4176
+ raise APError("Managed Skill feedback resolution entries must be sorted by signature")
4177
+ return catalog
4038
4178
 
4039
4179
 
4040
4180
  def _collect_project_feedback(
4041
4181
  root: Path,
4042
- ) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str | None]:
4182
+ ) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str, str]:
4043
4183
  reports_relative = Path("docs/skill-feedback/reports")
4044
- configured_project = _feedback_configured_project(root)
4184
+ configured_project, installed_skill_version = _feedback_configured_project(root)
4045
4185
  with _open_project_directory(root, reports_relative) as directory_fd:
4046
4186
  if directory_fd is None:
4047
- return [], 0, None, set(), configured_project
4187
+ return [], 0, None, set(), configured_project, installed_skill_version
4048
4188
  directory_metadata = (
4049
4189
  directory_fd.stat() if isinstance(directory_fd, Path) else os.fstat(directory_fd)
4050
4190
  )
@@ -4099,13 +4239,77 @@ def _collect_project_feedback(
4099
4239
  report["size_bytes"] = size
4100
4240
  reports.append(report)
4101
4241
  total_bytes += size
4102
- return reports, total_bytes, directory_identity, file_identities, configured_project
4242
+ return (
4243
+ reports,
4244
+ total_bytes,
4245
+ directory_identity,
4246
+ file_identities,
4247
+ configured_project,
4248
+ installed_skill_version,
4249
+ )
4103
4250
 
4104
4251
 
4105
- def cmd_feedback_collect(args: argparse.Namespace) -> None:
4106
- raw_projects = list(args.project or [])
4252
+ def _feedback_lifecycle(
4253
+ report: dict,
4254
+ installed_skill_version: str,
4255
+ catalog: dict[str, dict[str, str]],
4256
+ ) -> tuple[str, str, dict[str, str] | None]:
4257
+ if report["status"] not in _FEEDBACK_ACTIVE_STATUSES:
4258
+ return "closed", "none", catalog.get(report["signature"])
4259
+ catalog_entry = catalog.get(report["signature"])
4260
+ if catalog_entry:
4261
+ effective = catalog_entry["effective_skill_version"]
4262
+ if not _feedback_release_at_least(installed_skill_version, effective):
4263
+ return "upgrade-due", "upgrade-project-then-verify", catalog_entry
4264
+ disposition = catalog_entry["disposition"]
4265
+ if disposition == "fixed":
4266
+ if report["last_verified_skill_version"] == installed_skill_version:
4267
+ return "regression-current", "none", catalog_entry
4268
+ if _feedback_release_at_least(report["last_verified_skill_version"], effective):
4269
+ return (
4270
+ "recheck-due",
4271
+ "reproduce-on-installed-version-and-update-or-close",
4272
+ catalog_entry,
4273
+ )
4274
+ return "verification-due", "verify-fix-then-resolve-or-delete", catalog_entry
4275
+ if disposition == "project-config":
4276
+ return (
4277
+ "reroute-due",
4278
+ "move-to-docs/project/auto-coding-skill.yaml-then-reject-or-delete",
4279
+ catalog_entry,
4280
+ )
4281
+ return "closure-due", "update-closed-status-or-delete", catalog_entry
4282
+ if report["last_verified_skill_version"] != installed_skill_version:
4283
+ return "recheck-due", "reproduce-on-installed-version-and-update-or-close", None
4284
+ return "active-current", "none", None
4285
+
4286
+
4287
+ def _feedback_groups(reports: list[dict]) -> list[dict]:
4288
+ grouped: dict[str, list[dict]] = {}
4289
+ for report in reports:
4290
+ grouped.setdefault(report["signature"], []).append(report)
4291
+ groups: list[dict] = []
4292
+ for signature, items in sorted(grouped.items()):
4293
+ projects = sorted({item["project"] for item in items})
4294
+ group_source_projects = sorted({item["source_project"] for item in items})
4295
+ groups.append(
4296
+ {
4297
+ "signature": signature,
4298
+ "report_count": len(items),
4299
+ "project_count": len(group_source_projects),
4300
+ "projects": projects,
4301
+ "source_projects": group_source_projects,
4302
+ "report_ids": [item["report_id"] for item in items],
4303
+ "cross_project": len(group_source_projects) > 1,
4304
+ }
4305
+ )
4306
+ return groups
4307
+
4308
+
4309
+ def _feedback_collection_result(raw_projects: list[str]) -> dict:
4107
4310
  if not raw_projects:
4108
4311
  raise APError("feedback-collect requires at least one explicit --project")
4312
+ catalog = _load_feedback_resolution_catalog()
4109
4313
  roots: list[Path] = []
4110
4314
  seen_roots: set[str] = set()
4111
4315
  for raw in raw_projects:
@@ -4133,6 +4337,7 @@ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4133
4337
  directory_identity,
4134
4338
  file_identities,
4135
4339
  configured_project,
4340
+ installed_skill_version,
4136
4341
  ) = _collect_project_feedback(root)
4137
4342
  if directory_identity is not None:
4138
4343
  if directory_identity in seen_report_directories:
@@ -4141,13 +4346,14 @@ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4141
4346
  if seen_report_files.intersection(file_identities):
4142
4347
  raise APError("Explicit projects contain the same physical Skill feedback report file")
4143
4348
  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
4349
+ if configured_project in seen_configured_projects:
4350
+ raise APError("Explicit projects must have distinct effective project.name values")
4351
+ seen_configured_projects.add(configured_project)
4352
+ source_descriptor = {
4353
+ "source_project": source_id,
4354
+ "project": configured_project,
4355
+ "skill_version": installed_skill_version,
4356
+ }
4151
4357
  source_projects.append(source_descriptor)
4152
4358
  total_bytes += project_bytes
4153
4359
  if total_bytes > _FEEDBACK_COLLECTION_MAX_BYTES:
@@ -4160,45 +4366,89 @@ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4160
4366
  )
4161
4367
  for report in project_reports:
4162
4368
  report["source_project"] = source_id
4369
+ report["installed_skill_version"] = installed_skill_version
4370
+ lifecycle, recommended_action, catalog_entry = _feedback_lifecycle(
4371
+ report,
4372
+ installed_skill_version,
4373
+ catalog,
4374
+ )
4375
+ report["lifecycle"] = lifecycle
4376
+ report["recommended_action"] = recommended_action
4377
+ if catalog_entry:
4378
+ report["catalog_disposition"] = catalog_entry["disposition"]
4379
+ report["catalog_effective_skill_version"] = catalog_entry["effective_skill_version"]
4380
+ if catalog_entry.get("canonical_signature"):
4381
+ report["catalog_canonical_signature"] = catalog_entry["canonical_signature"]
4163
4382
  reports.extend(project_reports)
4164
4383
 
4165
4384
  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
- )
4385
+ triage_reports = [
4386
+ report
4387
+ for report in reports
4388
+ if report["lifecycle"] in {"active-current", "regression-current"}
4389
+ ]
4390
+ groups = _feedback_groups(triage_reports)
4184
4391
  cross_project = [group for group in groups if group["cross_project"]]
4185
- result = {
4392
+ lifecycle_counts = {
4393
+ lifecycle: sum(1 for report in reports if report["lifecycle"] == lifecycle)
4394
+ for lifecycle in sorted({report["lifecycle"] for report in reports})
4395
+ }
4396
+ action_required = [
4397
+ {
4398
+ key: report[key]
4399
+ for key in (
4400
+ "source_project",
4401
+ "project",
4402
+ "report_id",
4403
+ "source_path",
4404
+ "signature",
4405
+ "installed_skill_version",
4406
+ "last_verified_skill_version",
4407
+ "lifecycle",
4408
+ "recommended_action",
4409
+ "catalog_disposition",
4410
+ "catalog_effective_skill_version",
4411
+ "catalog_canonical_signature",
4412
+ )
4413
+ if key in report
4414
+ }
4415
+ for report in reports
4416
+ if report["recommended_action"] != "none"
4417
+ ]
4418
+ return {
4186
4419
  "schema": _FEEDBACK_COLLECTION_SCHEMA,
4187
4420
  "projects": source_projects,
4188
4421
  "report_count": len(reports),
4422
+ "active_report_count": len(triage_reports),
4423
+ "closed_report_count": lifecycle_counts.get("closed", 0),
4424
+ "action_required_count": len(action_required),
4189
4425
  "total_bytes": total_bytes,
4426
+ "lifecycle_counts": lifecycle_counts,
4427
+ "action_required": action_required,
4190
4428
  "metadata": reports,
4191
4429
  "groups": groups,
4192
4430
  "cross_project": cross_project,
4193
4431
  }
4432
+
4433
+
4434
+ def cmd_feedback_collect(args: argparse.Namespace) -> None:
4435
+ raw_projects = list(args.project or [])
4436
+ result = _feedback_collection_result(raw_projects)
4194
4437
  if args.json:
4195
4438
  print(json.dumps(result, ensure_ascii=False, indent=2))
4196
4439
  return
4197
4440
  print(
4198
- f"[feedback-collect] projects={len(roots)} reports={len(reports)} "
4199
- f"groups={len(groups)} cross_project={len(cross_project)} bytes={total_bytes}"
4441
+ f"[feedback-collect] projects={len(result['projects'])} reports={result['report_count']} "
4442
+ f"active={result['active_report_count']} closed={result['closed_report_count']} "
4443
+ f"actions={result['action_required_count']} groups={len(result['groups'])} "
4444
+ f"cross_project={len(result['cross_project'])} bytes={result['total_bytes']}"
4200
4445
  )
4201
- for group in groups:
4446
+ for item in result["action_required"]:
4447
+ print(
4448
+ f"[feedback-collect] action={item['recommended_action']} "
4449
+ f"project={item['project']} report={item['report_id']} lifecycle={item['lifecycle']}"
4450
+ )
4451
+ for group in result["groups"]:
4202
4452
  print(
4203
4453
  f"[feedback-collect] signature={group['signature']} "
4204
4454
  f"cross_project={str(group['cross_project']).lower()} "
@@ -11290,6 +11540,27 @@ def cmd_doctor(args: argparse.Namespace) -> dict | None:
11290
11540
  f"install integrity: {issue}" for issue in integrity["errors"]
11291
11541
  )
11292
11542
 
11543
+ if (
11544
+ isinstance(raw_project_name, str)
11545
+ and _FEEDBACK_SAFE_ID_RE.fullmatch(raw_project_name.strip())
11546
+ and _FEEDBACK_SEMVER_RE.fullmatch(skill_version)
11547
+ and (repo / "docs" / "skill-feedback" / "reports").exists()
11548
+ ):
11549
+ try:
11550
+ feedback = _feedback_collection_result([str(repo)])
11551
+ except APError:
11552
+ advisories.append(
11553
+ "Skill feedback metadata needs maintenance; run "
11554
+ "autocoding feedback --projects . --json for the bounded diagnostic"
11555
+ )
11556
+ else:
11557
+ if feedback["action_required_count"]:
11558
+ advisories.append(
11559
+ f"{feedback['action_required_count']} Skill feedback report(s) need recheck, "
11560
+ "closure, upgrade, or project-overlay routing; run "
11561
+ "autocoding feedback --projects . --json"
11562
+ )
11563
+
11293
11564
  missing.extend(validation_errors)
11294
11565
 
11295
11566
  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
  }