@elvis1513/auto-coding-skill 4.2.8 → 4.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -7
- package/cli/assets/managed-install.json +1 -1
- package/cli/assets/skill/SKILL.md +7 -7
- package/cli/assets/skill/data/policies/feedback-resolutions-v1.json +15 -0
- package/cli/assets/skill/data/policies/workflow-migrations-v1.json +2 -2
- package/cli/assets/skill/data/templates/ENGINEERING.md +17 -12
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +14 -8
- package/cli/assets/skill/scripts/ap.py +3094 -641
- package/cli/assets/skill/scripts/core.py +363 -1
- package/cli/assets/skill/scripts/install_integrity.py +12 -10
- package/cli/assets/skill/scripts/scaffold_templates.py +146 -0
- package/cli/src/index.js +1188 -317
- package/cli/tests/ap_concurrency_test.py +1 -1
- package/cli/tests/ap_profiles_test.py +98 -33
- package/cli/tests/core_shell_test.py +261 -0
- package/cli/tests/index.test.js +1694 -180
- package/package.json +1 -1
|
@@ -4,11 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
from __future__ import annotations
|
|
6
6
|
|
|
7
|
+
import copy
|
|
8
|
+
import math
|
|
7
9
|
import os
|
|
8
10
|
import re
|
|
9
11
|
import signal
|
|
10
12
|
import shlex
|
|
11
13
|
import shutil
|
|
14
|
+
import stat
|
|
12
15
|
import subprocess
|
|
13
16
|
import sys
|
|
14
17
|
import urllib.error
|
|
@@ -25,6 +28,33 @@ class APError(RuntimeError):
|
|
|
25
28
|
pass
|
|
26
29
|
|
|
27
30
|
|
|
31
|
+
MANAGED_CONFIG_RELATIVE_PATH = Path("docs/ENGINEERING.md")
|
|
32
|
+
PROJECT_CONFIG_PATH = Path("docs/project/auto-coding-skill.yaml")
|
|
33
|
+
PROJECT_CONFIG_OVERLAY_RELATIVE_PATH = PROJECT_CONFIG_PATH
|
|
34
|
+
PROJECT_CONFIG_SCHEMA = "auto-coding-skill/project-config/v1"
|
|
35
|
+
MANAGED_CONFIG_FRONTMATTER_MAX_BYTES = 256 * 1024
|
|
36
|
+
PROJECT_CONFIG_OVERLAY_MAX_BYTES = 128 * 1024
|
|
37
|
+
PROJECT_CONFIG_MAX_YAML_DEPTH = 64
|
|
38
|
+
PROJECT_CONFIG_MAX_YAML_NODES = 10_000
|
|
39
|
+
PROJECT_CONFIG_PROTECTED_WORKFLOW_FIELDS = frozenset(
|
|
40
|
+
{"skill_version", "mode", "completion"}
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class _ConfigYamlViolation(RuntimeError):
|
|
45
|
+
"""Internal marker whose message never includes user-controlled YAML."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _is_windows_reparse_point(metadata: os.stat_result) -> bool:
|
|
49
|
+
attributes = int(getattr(metadata, "st_file_attributes", 0) or 0)
|
|
50
|
+
reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))
|
|
51
|
+
return stat.S_ISLNK(metadata.st_mode) or bool(attributes & reparse_flag)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _file_identity(metadata: os.stat_result) -> tuple[int, int]:
|
|
55
|
+
return int(metadata.st_dev), int(metadata.st_ino)
|
|
56
|
+
|
|
57
|
+
|
|
28
58
|
def runtime_requirements_path() -> Path:
|
|
29
59
|
return Path(__file__).resolve().parents[1] / "requirements.txt"
|
|
30
60
|
|
|
@@ -115,7 +145,7 @@ def http_get_status(url: str, timeout_s: int = 5) -> int:
|
|
|
115
145
|
def find_config(repo: Path) -> Path:
|
|
116
146
|
"""Find single source project config file."""
|
|
117
147
|
candidates = [
|
|
118
|
-
repo /
|
|
148
|
+
repo / MANAGED_CONFIG_RELATIVE_PATH,
|
|
119
149
|
]
|
|
120
150
|
for c in candidates:
|
|
121
151
|
if c.exists():
|
|
@@ -126,6 +156,338 @@ def find_config(repo: Path) -> Path:
|
|
|
126
156
|
)
|
|
127
157
|
|
|
128
158
|
|
|
159
|
+
def _config_source_name(relative: Path) -> str:
|
|
160
|
+
if relative == MANAGED_CONFIG_RELATIVE_PATH:
|
|
161
|
+
return "Managed project configuration"
|
|
162
|
+
return "Project configuration overlay"
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def _read_project_config_file(
|
|
166
|
+
repo: Path,
|
|
167
|
+
relative: Path,
|
|
168
|
+
*,
|
|
169
|
+
max_bytes: int,
|
|
170
|
+
require_eof: bool,
|
|
171
|
+
) -> bytes | None:
|
|
172
|
+
"""Read a bounded project-relative config without following in-repo links."""
|
|
173
|
+
source = _config_source_name(relative)
|
|
174
|
+
if relative.is_absolute() or not relative.parts or any(
|
|
175
|
+
part in {"", ".", ".."} for part in relative.parts
|
|
176
|
+
):
|
|
177
|
+
raise APError(f"{source} path is invalid.")
|
|
178
|
+
if max_bytes <= 0:
|
|
179
|
+
raise APError(f"{source} read bound is invalid.")
|
|
180
|
+
|
|
181
|
+
repo = Path(repo)
|
|
182
|
+
if os.name == "nt":
|
|
183
|
+
try:
|
|
184
|
+
repo_metadata = repo.lstat()
|
|
185
|
+
if _is_windows_reparse_point(repo_metadata) or not stat.S_ISDIR(repo_metadata.st_mode):
|
|
186
|
+
raise APError(f"{source} repository root must be a real directory.")
|
|
187
|
+
checked_directories = [(repo, _file_identity(repo_metadata))]
|
|
188
|
+
current = repo
|
|
189
|
+
for part in relative.parts[:-1]:
|
|
190
|
+
current = current / part
|
|
191
|
+
if not os.path.lexists(current):
|
|
192
|
+
return None
|
|
193
|
+
metadata = current.lstat()
|
|
194
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
|
|
195
|
+
raise APError(f"{source} parent must be a real directory.")
|
|
196
|
+
checked_directories.append((current, _file_identity(metadata)))
|
|
197
|
+
target = current / relative.parts[-1]
|
|
198
|
+
if not os.path.lexists(target):
|
|
199
|
+
return None
|
|
200
|
+
metadata = target.lstat()
|
|
201
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
|
|
202
|
+
raise APError(f"{source} must be a regular non-symlink file.")
|
|
203
|
+
if require_eof and metadata.st_size > max_bytes:
|
|
204
|
+
raise APError(f"{source} exceeds its size limit.")
|
|
205
|
+
with target.open("rb") as handle:
|
|
206
|
+
opened = os.fstat(handle.fileno())
|
|
207
|
+
if not stat.S_ISREG(opened.st_mode) or _file_identity(opened) != _file_identity(metadata):
|
|
208
|
+
raise APError(f"{source} changed during its safety check.")
|
|
209
|
+
for directory, identity in checked_directories:
|
|
210
|
+
checked = directory.lstat()
|
|
211
|
+
if (
|
|
212
|
+
_is_windows_reparse_point(checked)
|
|
213
|
+
or not stat.S_ISDIR(checked.st_mode)
|
|
214
|
+
or _file_identity(checked) != identity
|
|
215
|
+
):
|
|
216
|
+
raise APError(f"{source} parent changed during its safety check.")
|
|
217
|
+
payload = handle.read(max_bytes + 1)
|
|
218
|
+
except APError:
|
|
219
|
+
raise
|
|
220
|
+
except OSError as exc:
|
|
221
|
+
raise APError(f"{source} could not be read safely.") from exc
|
|
222
|
+
else:
|
|
223
|
+
directory_flags = (
|
|
224
|
+
os.O_RDONLY
|
|
225
|
+
| getattr(os, "O_DIRECTORY", 0)
|
|
226
|
+
| getattr(os, "O_NOFOLLOW", 0)
|
|
227
|
+
)
|
|
228
|
+
descriptors: list[int] = []
|
|
229
|
+
file_descriptor = -1
|
|
230
|
+
try:
|
|
231
|
+
current = os.open(repo, directory_flags)
|
|
232
|
+
descriptors.append(current)
|
|
233
|
+
for part in relative.parts[:-1]:
|
|
234
|
+
try:
|
|
235
|
+
metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
|
|
236
|
+
except FileNotFoundError:
|
|
237
|
+
return None
|
|
238
|
+
if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
|
|
239
|
+
raise APError(f"{source} parent must be a real directory.")
|
|
240
|
+
next_descriptor = os.open(part, directory_flags, dir_fd=current)
|
|
241
|
+
descriptors.append(next_descriptor)
|
|
242
|
+
current = next_descriptor
|
|
243
|
+
try:
|
|
244
|
+
metadata = os.stat(
|
|
245
|
+
relative.parts[-1],
|
|
246
|
+
dir_fd=current,
|
|
247
|
+
follow_symlinks=False,
|
|
248
|
+
)
|
|
249
|
+
if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
|
|
250
|
+
raise APError(f"{source} must be a regular non-symlink file.")
|
|
251
|
+
file_descriptor = os.open(
|
|
252
|
+
relative.parts[-1],
|
|
253
|
+
os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
|
|
254
|
+
dir_fd=current,
|
|
255
|
+
)
|
|
256
|
+
except FileNotFoundError:
|
|
257
|
+
return None
|
|
258
|
+
metadata = os.fstat(file_descriptor)
|
|
259
|
+
if not stat.S_ISREG(metadata.st_mode):
|
|
260
|
+
raise APError(f"{source} must be a regular non-symlink file.")
|
|
261
|
+
if require_eof and metadata.st_size > max_bytes:
|
|
262
|
+
raise APError(f"{source} exceeds its size limit.")
|
|
263
|
+
with os.fdopen(file_descriptor, "rb") as handle:
|
|
264
|
+
file_descriptor = -1
|
|
265
|
+
payload = handle.read(max_bytes + 1)
|
|
266
|
+
except APError:
|
|
267
|
+
raise
|
|
268
|
+
except OSError as exc:
|
|
269
|
+
raise APError(f"{source} could not be read safely.") from exc
|
|
270
|
+
finally:
|
|
271
|
+
if file_descriptor >= 0:
|
|
272
|
+
os.close(file_descriptor)
|
|
273
|
+
for descriptor in reversed(descriptors):
|
|
274
|
+
try:
|
|
275
|
+
os.close(descriptor)
|
|
276
|
+
except OSError:
|
|
277
|
+
pass
|
|
278
|
+
|
|
279
|
+
if require_eof and len(payload) > max_bytes:
|
|
280
|
+
raise APError(f"{source} exceeds its size limit.")
|
|
281
|
+
return payload
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
_FRONTMATTER_BYTES_RE = re.compile(
|
|
285
|
+
rb"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)",
|
|
286
|
+
flags=re.DOTALL,
|
|
287
|
+
)
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def _decode_managed_frontmatter(payload: bytes) -> str:
|
|
291
|
+
match = _FRONTMATTER_BYTES_RE.match(payload)
|
|
292
|
+
if not match or match.end() > MANAGED_CONFIG_FRONTMATTER_MAX_BYTES:
|
|
293
|
+
raise APError(
|
|
294
|
+
"Managed project configuration must contain bounded YAML frontmatter at the file start."
|
|
295
|
+
)
|
|
296
|
+
try:
|
|
297
|
+
return match.group(1).decode("utf-8")
|
|
298
|
+
except UnicodeDecodeError as exc:
|
|
299
|
+
raise APError("Managed project configuration frontmatter must be UTF-8.") from exc
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def _strict_yaml_mapping(text: str, source: str) -> Dict[str, Any]:
|
|
303
|
+
yaml_module = require_yaml()
|
|
304
|
+
merge_tag = "tag:yaml.org,2002:merge"
|
|
305
|
+
|
|
306
|
+
class StrictConfigLoader(yaml_module.SafeLoader):
|
|
307
|
+
def compose_node(self, parent: Any, index: Any) -> Any:
|
|
308
|
+
event = self.peek_event()
|
|
309
|
+
if isinstance(event, yaml_module.events.AliasEvent) or getattr(event, "anchor", None):
|
|
310
|
+
raise _ConfigYamlViolation("alias")
|
|
311
|
+
depth = getattr(self, "_project_config_depth", 0)
|
|
312
|
+
nodes = getattr(self, "_project_config_nodes", 0) + 1
|
|
313
|
+
if depth >= PROJECT_CONFIG_MAX_YAML_DEPTH or nodes > PROJECT_CONFIG_MAX_YAML_NODES:
|
|
314
|
+
raise _ConfigYamlViolation("complexity")
|
|
315
|
+
self._project_config_depth = depth + 1
|
|
316
|
+
self._project_config_nodes = nodes
|
|
317
|
+
try:
|
|
318
|
+
return super().compose_node(parent, index)
|
|
319
|
+
finally:
|
|
320
|
+
self._project_config_depth = depth
|
|
321
|
+
|
|
322
|
+
def construct_mapping(self, node: Any, deep: bool = False) -> Dict[str, Any]:
|
|
323
|
+
if not isinstance(node, yaml_module.nodes.MappingNode):
|
|
324
|
+
raise _ConfigYamlViolation("mapping")
|
|
325
|
+
result: Dict[str, Any] = {}
|
|
326
|
+
for key_node, value_node in node.value:
|
|
327
|
+
if getattr(key_node, "tag", "") == merge_tag:
|
|
328
|
+
raise _ConfigYamlViolation("merge")
|
|
329
|
+
key = self.construct_object(key_node, deep=deep)
|
|
330
|
+
if not isinstance(key, str):
|
|
331
|
+
raise _ConfigYamlViolation("key")
|
|
332
|
+
if key in result:
|
|
333
|
+
raise _ConfigYamlViolation("duplicate")
|
|
334
|
+
result[key] = self.construct_object(value_node, deep=deep)
|
|
335
|
+
return result
|
|
336
|
+
|
|
337
|
+
try:
|
|
338
|
+
value = yaml_module.load(text, Loader=StrictConfigLoader)
|
|
339
|
+
except _ConfigYamlViolation as exc:
|
|
340
|
+
messages = {
|
|
341
|
+
"alias": "must not use YAML anchors or aliases.",
|
|
342
|
+
"merge": "must not use YAML merge keys.",
|
|
343
|
+
"mapping": "contains an invalid YAML mapping.",
|
|
344
|
+
"key": "must use string YAML mapping keys.",
|
|
345
|
+
"duplicate": "contains duplicate YAML keys.",
|
|
346
|
+
"complexity": "exceeds the YAML complexity limit.",
|
|
347
|
+
}
|
|
348
|
+
raise APError(f"{source} {messages.get(str(exc), 'contains invalid YAML.')}") from None
|
|
349
|
+
except Exception:
|
|
350
|
+
raise APError(f"{source} contains invalid YAML.") from None
|
|
351
|
+
|
|
352
|
+
if value is None:
|
|
353
|
+
raise APError(f"{source} must not contain null values.")
|
|
354
|
+
if not isinstance(value, dict):
|
|
355
|
+
raise APError(f"{source} root must be a mapping.")
|
|
356
|
+
_validate_config_value(value, source)
|
|
357
|
+
return value
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
def _validate_config_value(value: Any, source: str) -> None:
|
|
361
|
+
if value is None:
|
|
362
|
+
raise APError(f"{source} must not contain null values.")
|
|
363
|
+
if isinstance(value, dict):
|
|
364
|
+
for key, nested in value.items():
|
|
365
|
+
if not isinstance(key, str):
|
|
366
|
+
raise APError(f"{source} must use string YAML mapping keys.")
|
|
367
|
+
_validate_config_string(key, source)
|
|
368
|
+
_validate_config_value(nested, source)
|
|
369
|
+
return
|
|
370
|
+
if isinstance(value, list):
|
|
371
|
+
for nested in value:
|
|
372
|
+
_validate_config_value(nested, source)
|
|
373
|
+
return
|
|
374
|
+
if isinstance(value, float) and not math.isfinite(value):
|
|
375
|
+
raise APError(f"{source} contains an unsupported scalar value.")
|
|
376
|
+
if isinstance(value, str):
|
|
377
|
+
_validate_config_string(value, source)
|
|
378
|
+
return
|
|
379
|
+
if not isinstance(value, (str, bool, int, float)):
|
|
380
|
+
raise APError(f"{source} contains an unsupported scalar value.")
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
def _validate_config_string(value: str, source: str) -> None:
|
|
384
|
+
try:
|
|
385
|
+
value.encode("utf-8")
|
|
386
|
+
except UnicodeEncodeError:
|
|
387
|
+
raise APError(f"{source} contains an invalid Unicode string.") from None
|
|
388
|
+
if any(
|
|
389
|
+
(ord(char) < 0x20 and char not in {"\t", "\n", "\r"})
|
|
390
|
+
or 0x7F <= ord(char) <= 0x9F
|
|
391
|
+
for char in value
|
|
392
|
+
):
|
|
393
|
+
raise APError(f"{source} contains an unsupported control character.")
|
|
394
|
+
|
|
395
|
+
|
|
396
|
+
def parse_managed_config_payload(payload: bytes) -> Dict[str, Any]:
|
|
397
|
+
"""Strictly parse a bounded managed ENGINEERING document already in memory."""
|
|
398
|
+
frontmatter = _decode_managed_frontmatter(payload)
|
|
399
|
+
return _strict_yaml_mapping(frontmatter, "Managed project configuration")
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def load_managed_config(repo: Path) -> Dict[str, Any]:
|
|
403
|
+
"""Load the Skill-managed defaults from docs/ENGINEERING.md frontmatter."""
|
|
404
|
+
payload = _read_project_config_file(
|
|
405
|
+
repo,
|
|
406
|
+
MANAGED_CONFIG_RELATIVE_PATH,
|
|
407
|
+
max_bytes=MANAGED_CONFIG_FRONTMATTER_MAX_BYTES,
|
|
408
|
+
require_eof=False,
|
|
409
|
+
)
|
|
410
|
+
if payload is None:
|
|
411
|
+
raise APError("Managed project configuration was not found.")
|
|
412
|
+
return parse_managed_config_payload(payload)
|
|
413
|
+
|
|
414
|
+
|
|
415
|
+
def parse_project_overrides_payload(payload: bytes) -> Dict[str, Any]:
|
|
416
|
+
"""Strictly parse a bounded project overlay already in memory."""
|
|
417
|
+
if len(payload) > PROJECT_CONFIG_OVERLAY_MAX_BYTES:
|
|
418
|
+
raise APError("Project configuration overlay exceeds its size limit.")
|
|
419
|
+
try:
|
|
420
|
+
text = payload.decode("utf-8")
|
|
421
|
+
except UnicodeDecodeError as exc:
|
|
422
|
+
raise APError("Project configuration overlay must be UTF-8.") from exc
|
|
423
|
+
document = _strict_yaml_mapping(text, "Project configuration overlay")
|
|
424
|
+
if set(document) != {"schema", "overrides"}:
|
|
425
|
+
raise APError("Project configuration overlay has unsupported top-level wrapper fields.")
|
|
426
|
+
if document.get("schema") != PROJECT_CONFIG_SCHEMA:
|
|
427
|
+
raise APError("Project configuration overlay schema is unsupported.")
|
|
428
|
+
overrides = document.get("overrides")
|
|
429
|
+
if not isinstance(overrides, dict):
|
|
430
|
+
raise APError("Project configuration overlay overrides must be a mapping.")
|
|
431
|
+
workflow = overrides.get("workflow")
|
|
432
|
+
if workflow is not None:
|
|
433
|
+
if not isinstance(workflow, dict) or PROJECT_CONFIG_PROTECTED_WORKFLOW_FIELDS.intersection(
|
|
434
|
+
workflow
|
|
435
|
+
):
|
|
436
|
+
raise APError(
|
|
437
|
+
"Project configuration overlay cannot override managed workflow fields."
|
|
438
|
+
)
|
|
439
|
+
return overrides
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
def load_project_overrides(repo: Path) -> Dict[str, Any]:
|
|
443
|
+
"""Load the optional project-owned overlay after validating its wrapper."""
|
|
444
|
+
payload = _read_project_config_file(
|
|
445
|
+
repo,
|
|
446
|
+
PROJECT_CONFIG_OVERLAY_RELATIVE_PATH,
|
|
447
|
+
max_bytes=PROJECT_CONFIG_OVERLAY_MAX_BYTES,
|
|
448
|
+
require_eof=True,
|
|
449
|
+
)
|
|
450
|
+
if payload is None:
|
|
451
|
+
return {}
|
|
452
|
+
return parse_project_overrides_payload(payload)
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
def merge_project_config(
|
|
456
|
+
defaults: Dict[str, Any],
|
|
457
|
+
overrides: Dict[str, Any],
|
|
458
|
+
) -> Dict[str, Any]:
|
|
459
|
+
"""Recursively merge mappings; project scalars and lists replace defaults."""
|
|
460
|
+
if not isinstance(defaults, dict) or not isinstance(overrides, dict):
|
|
461
|
+
raise APError("Effective project configuration layers must be mappings.")
|
|
462
|
+
_validate_config_value(defaults, "Managed project configuration")
|
|
463
|
+
_validate_config_value(overrides, "Project configuration overlay")
|
|
464
|
+
workflow = overrides.get("workflow")
|
|
465
|
+
if workflow is not None:
|
|
466
|
+
if not isinstance(workflow, dict) or PROJECT_CONFIG_PROTECTED_WORKFLOW_FIELDS.intersection(
|
|
467
|
+
workflow
|
|
468
|
+
):
|
|
469
|
+
raise APError(
|
|
470
|
+
"Project configuration overlay cannot override managed workflow fields."
|
|
471
|
+
)
|
|
472
|
+
|
|
473
|
+
def merge(base: Dict[str, Any], project: Dict[str, Any]) -> Dict[str, Any]:
|
|
474
|
+
result = copy.deepcopy(base)
|
|
475
|
+
for key, value in project.items():
|
|
476
|
+
current = result.get(key)
|
|
477
|
+
if isinstance(current, dict) and isinstance(value, dict):
|
|
478
|
+
result[key] = merge(current, value)
|
|
479
|
+
else:
|
|
480
|
+
result[key] = copy.deepcopy(value)
|
|
481
|
+
return result
|
|
482
|
+
|
|
483
|
+
return merge(defaults, overrides)
|
|
484
|
+
|
|
485
|
+
|
|
486
|
+
def load_effective_config(repo: Path) -> Dict[str, Any]:
|
|
487
|
+
"""Return managed defaults merged with the project-owned overlay."""
|
|
488
|
+
return merge_project_config(load_managed_config(repo), load_project_overrides(repo))
|
|
489
|
+
|
|
490
|
+
|
|
129
491
|
def run_shell(command: str, cwd: Optional[Path] = None, timeout_s: Optional[float] = None) -> None:
|
|
130
492
|
"""Run in the caller's environment and terminate the process group on timeout."""
|
|
131
493
|
p = subprocess.Popen(
|
|
@@ -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
|
|
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
|
|
@@ -189,9 +194,9 @@ def build_manifest(skill_root: Path, agents_root: Path, version: str) -> dict[st
|
|
|
189
194
|
engineering = skill_root / "data/templates/ENGINEERING.md"
|
|
190
195
|
entries.append(_entry(
|
|
191
196
|
target="docs/ENGINEERING.md",
|
|
192
|
-
source="skill/data/templates/ENGINEERING.md
|
|
193
|
-
strategy="
|
|
194
|
-
data=
|
|
197
|
+
source="skill/data/templates/ENGINEERING.md",
|
|
198
|
+
strategy="exact",
|
|
199
|
+
data=engineering.read_bytes(),
|
|
195
200
|
executable=bool(engineering.stat().st_mode & 0o111),
|
|
196
201
|
scope="project",
|
|
197
202
|
version=version,
|
|
@@ -224,13 +229,10 @@ 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
|
|
232
|
+
"docs/project/auto-coding-skill.yaml",
|
|
228
233
|
"docs/architecture/structure-standard.md",
|
|
229
|
-
"
|
|
230
|
-
|
|
231
|
-
"docs/interfaces/*.md",
|
|
232
|
-
"docs/deployment/deploy-records/*.md",
|
|
233
|
-
"docs/reviews/*.md",
|
|
234
|
+
*(f"{root}/** (except exact-managed entries)" for root in PROJECT_OWNED_DOC_ROOTS),
|
|
235
|
+
*PROJECT_FEEDBACK_PATTERNS,
|
|
234
236
|
],
|
|
235
237
|
}
|
|
236
238
|
|
|
@@ -5,6 +5,131 @@ from __future__ import annotations
|
|
|
5
5
|
|
|
6
6
|
|
|
7
7
|
TEMPLATES: dict[str, dict[str, str]] = {
|
|
8
|
+
"feedback": {
|
|
9
|
+
"docs/skill-feedback/README.md": """# Auto Coding Skill Feedback
|
|
10
|
+
|
|
11
|
+
This directory is the project-owned inbox for candidate defects or capability
|
|
12
|
+
gaps in the shared `auto-coding-skill`. It is not the project's business bug
|
|
13
|
+
list and it does not make a reported issue an accepted shared defect.
|
|
14
|
+
|
|
15
|
+
Route the observation before writing a report:
|
|
16
|
+
|
|
17
|
+
| Observation | Project-owned destination |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| Risk rules, commands, validation routes, access values, structure policy, budgets, or project preferences | `docs/project/auto-coding-skill.yaml` |
|
|
20
|
+
| Durable product, repository, runtime, or operating facts | `docs/project/*.md` |
|
|
21
|
+
| A defect or capability gap reproducible in managed defaults, scripts, agents, CLI, or installer | `docs/skill-feedback/reports/*.md` |
|
|
22
|
+
|
|
23
|
+
Project configuration may intentionally override managed defaults. A preference
|
|
24
|
+
that is correct for only this project is not shared-Skill feedback.
|
|
25
|
+
|
|
26
|
+
## Record a candidate
|
|
27
|
+
|
|
28
|
+
1. Copy `_TEMPLATE-SKILL-FEEDBACK.md` into `reports/`.
|
|
29
|
+
2. Name it `YYYY-MM-DD-<short-slug>-<8-hex>.md`.
|
|
30
|
+
3. Fill every frontmatter field and all six body sections. Set
|
|
31
|
+
`last_verified_skill_version` to the version actually reproduced.
|
|
32
|
+
4. Use one stable root-cause signature for duplicate observations.
|
|
33
|
+
5. Redact credentials, tokens, private keys, customer/device data, absolute user
|
|
34
|
+
paths, complete patches, Reviewer artifacts, and raw logs.
|
|
35
|
+
|
|
36
|
+
Reports are project-owned and preserved byte-for-byte by `autocoding init`.
|
|
37
|
+
Managed README/template files may be upgraded. Recording is explicit: ordinary
|
|
38
|
+
test failures, Reviewer findings, environment incidents, and project-only policy
|
|
39
|
+
gaps do not automatically create a report. If a frozen Reviewer assignment
|
|
40
|
+
already exists, record the feedback after delivery as a separate docs-only change
|
|
41
|
+
so the reviewed fingerprint is not mutated.
|
|
42
|
+
|
|
43
|
+
For a known duplicate, reuse its exact signature. For a new observation, hash the
|
|
44
|
+
lowercase UTF-8 key `<component>|<origin_surface>|<short-root-cause-slug>` and
|
|
45
|
+
prefix the 64-hex digest with `sha256:`. Exclude project names, paths, versions,
|
|
46
|
+
timestamps, and log text so another project can independently reuse the key.
|
|
47
|
+
|
|
48
|
+
## Keep reports current
|
|
49
|
+
|
|
50
|
+
Each Skill release carries a managed resolution catalog keyed by `signature`.
|
|
51
|
+
The collector compares that catalog, the project's installed Skill version, and
|
|
52
|
+
`last_verified_skill_version` without changing the report. It may request an
|
|
53
|
+
upgrade, recheck, fix verification, closure, or routing into the project overlay.
|
|
54
|
+
|
|
55
|
+
After upgrading a project:
|
|
56
|
+
|
|
57
|
+
- If the issue is fixed, verify it and either delete a local-only report or set
|
|
58
|
+
`status: resolved`, `resolution: fixed`, update `updated_at`, and set
|
|
59
|
+
`last_verified_skill_version` to the verified release.
|
|
60
|
+
- If it still reproduces, keep an active status and update the verification
|
|
61
|
+
version; the collector treats it as a current regression.
|
|
62
|
+
- If triage says it is project configuration, maintain the value in
|
|
63
|
+
`docs/project/auto-coding-skill.yaml`, then delete the report or set
|
|
64
|
+
`status: rejected` and `resolution: project-config`.
|
|
65
|
+
- Use `duplicate` or another supported rejected resolution for closed reports.
|
|
66
|
+
Closed reports remain project history but are excluded from active grouping.
|
|
67
|
+
|
|
68
|
+
Do not reopen a closed historical report. Create a new report with the same
|
|
69
|
+
signature if the behavior later regresses.
|
|
70
|
+
|
|
71
|
+
## Periodic read-only collection
|
|
72
|
+
|
|
73
|
+
From the Skill source checkout, explicitly list the projects to inspect:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
autocoding feedback --projects /path/project-a,/path/project-b --json
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Collection reads bounded metadata only, never executes report content, never
|
|
80
|
+
modifies a project, and groups exact signatures for human triage. Triage decides
|
|
81
|
+
whether the result is a shared defect, project configuration, environment issue,
|
|
82
|
+
duplicate, or insufficient evidence before any Skill fix or release is planned.
|
|
83
|
+
""",
|
|
84
|
+
"docs/skill-feedback/_TEMPLATE-SKILL-FEEDBACK.md": """---
|
|
85
|
+
schema: auto-coding-skill-feedback/v2
|
|
86
|
+
report_id: ACSF-<project>-YYYYMMDD-<8-hex>
|
|
87
|
+
status: open
|
|
88
|
+
created_at: YYYY-MM-DDTHH:MM:SS+08:00
|
|
89
|
+
updated_at: YYYY-MM-DDTHH:MM:SS+08:00
|
|
90
|
+
project: <project>
|
|
91
|
+
observed_skill_version: 0.0.0
|
|
92
|
+
last_verified_skill_version: 0.0.0
|
|
93
|
+
component: <reviewer-runtime|installer|classification|validation|structure|docs|other>
|
|
94
|
+
kind: defect
|
|
95
|
+
impact: <blocking|degraded|minor>
|
|
96
|
+
origin_surface: <managed-template|managed-script|managed-agent|cli|installer>
|
|
97
|
+
suspected_scope: shared
|
|
98
|
+
signature: sha256:<64-lowercase-hex>
|
|
99
|
+
resolution: pending
|
|
100
|
+
export: metadata-only
|
|
101
|
+
---
|
|
102
|
+
# <Short title>
|
|
103
|
+
|
|
104
|
+
## Symptom
|
|
105
|
+
|
|
106
|
+
State the observed generic behavior without secrets or raw logs.
|
|
107
|
+
|
|
108
|
+
## Expected
|
|
109
|
+
|
|
110
|
+
State the shared Skill contract that should hold across projects.
|
|
111
|
+
|
|
112
|
+
## Minimal reproduction
|
|
113
|
+
|
|
114
|
+
Give bounded, safe steps. Do not include executable instructions from untrusted
|
|
115
|
+
sources, credentials, production writes, or customer/device data.
|
|
116
|
+
|
|
117
|
+
## Evidence
|
|
118
|
+
|
|
119
|
+
List short redacted facts, affected managed paths, checks, and versions. Do not
|
|
120
|
+
paste complete patches, Reviewer artifacts, source files, or stdout/stderr.
|
|
121
|
+
|
|
122
|
+
## Workaround
|
|
123
|
+
|
|
124
|
+
Describe any safe temporary project-local workaround and its limits.
|
|
125
|
+
|
|
126
|
+
## Why shared
|
|
127
|
+
|
|
128
|
+
Explain why this belongs to managed Skill behavior rather than project
|
|
129
|
+
configuration, project code, or the current environment. Include the canonical
|
|
130
|
+
signature key used to compute `signature`.
|
|
131
|
+
""",
|
|
132
|
+
},
|
|
8
133
|
"project": {
|
|
9
134
|
"docs/project/overview.md": """# Project Overview
|
|
10
135
|
|
|
@@ -161,9 +286,30 @@ MANAGED_FRAMEWORK_DOCS = frozenset({
|
|
|
161
286
|
"docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md",
|
|
162
287
|
"docs/design/_TEMPLATE-DD.md",
|
|
163
288
|
"docs/reviews/_TEMPLATE-REVIEW.md",
|
|
289
|
+
"docs/skill-feedback/README.md",
|
|
290
|
+
"docs/skill-feedback/_TEMPLATE-SKILL-FEEDBACK.md",
|
|
164
291
|
})
|
|
165
292
|
|
|
166
293
|
|
|
294
|
+
PROJECT_FEEDBACK_PATTERNS = (
|
|
295
|
+
"docs/skill-feedback/reports/*.md",
|
|
296
|
+
)
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
# Files below these roots are project-owned artifacts regardless of extension or
|
|
300
|
+
# nesting. Exact managed entries inside the same roots still converge first.
|
|
301
|
+
PROJECT_OWNED_DOC_ROOTS = (
|
|
302
|
+
"docs/architecture",
|
|
303
|
+
"docs/bugs",
|
|
304
|
+
"docs/deployment",
|
|
305
|
+
"docs/design",
|
|
306
|
+
"docs/interfaces",
|
|
307
|
+
"docs/project",
|
|
308
|
+
"docs/reviews",
|
|
309
|
+
"docs/testing",
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
|
|
167
313
|
def scaffold_groups() -> list[str]:
|
|
168
314
|
return sorted(TEMPLATES)
|
|
169
315
|
|