@brucewaynedecoy/make-docs 1.0.0-rc.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.
Files changed (88) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +93 -0
  3. package/dist/chunk-HP3HBG7F.js +626 -0
  4. package/dist/chunk-HP3HBG7F.js.map +1 -0
  5. package/dist/chunk-QRFH4J6H.js +1194 -0
  6. package/dist/chunk-QRFH4J6H.js.map +1 -0
  7. package/dist/chunk-WM3OXYTW.js +2630 -0
  8. package/dist/chunk-WM3OXYTW.js.map +1 -0
  9. package/dist/index.js +1720 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/skills-command-3ESCZ75U.js +547 -0
  12. package/dist/skills-command-3ESCZ75U.js.map +1 -0
  13. package/dist/uninstall-GQE4SJF2.js +150 -0
  14. package/dist/uninstall-GQE4SJF2.js.map +1 -0
  15. package/package.json +49 -0
  16. package/skill-registry.json +276 -0
  17. package/skill-registry.schema.json +64 -0
  18. package/template/.make-docs/scripts/check_path_hygiene.py +435 -0
  19. package/template/AGENTS.md +3 -0
  20. package/template/CLAUDE.md +3 -0
  21. package/template/docs/AGENTS.md +15 -0
  22. package/template/docs/CLAUDE.md +15 -0
  23. package/template/docs/assets/AGENTS.md +9 -0
  24. package/template/docs/assets/CLAUDE.md +9 -0
  25. package/template/docs/assets/archive/AGENTS.md +20 -0
  26. package/template/docs/assets/archive/CLAUDE.md +20 -0
  27. package/template/docs/assets/history/AGENTS.md +12 -0
  28. package/template/docs/assets/history/CLAUDE.md +12 -0
  29. package/template/docs/assets/prompts/AGENTS.md +8 -0
  30. package/template/docs/assets/prompts/CLAUDE.md +8 -0
  31. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +14 -0
  32. package/template/docs/assets/prompts/designs-to-plan.prompt.md +10 -0
  33. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +27 -0
  34. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +8 -0
  35. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +6 -0
  36. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +10 -0
  37. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +6 -0
  38. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +6 -0
  39. package/template/docs/assets/prompts/request-to-design.prompt.md +16 -0
  40. package/template/docs/assets/prompts/session-to-history-record.prompt.md +19 -0
  41. package/template/docs/assets/prompts/update-readme-green-field.prompt.md +6 -0
  42. package/template/docs/assets/prompts/work-to-commit-message.prompt.md +27 -0
  43. package/template/docs/assets/prompts/work-to-guides.prompt.md +18 -0
  44. package/template/docs/assets/references/AGENTS.md +9 -0
  45. package/template/docs/assets/references/CLAUDE.md +9 -0
  46. package/template/docs/assets/references/commit-message-convention.md +198 -0
  47. package/template/docs/assets/references/design-contract.md +62 -0
  48. package/template/docs/assets/references/design-workflow.md +60 -0
  49. package/template/docs/assets/references/execution-workflow.md +157 -0
  50. package/template/docs/assets/references/guide-contract.md +159 -0
  51. package/template/docs/assets/references/harness-capability-matrix.md +52 -0
  52. package/template/docs/assets/references/history-record-contract.md +137 -0
  53. package/template/docs/assets/references/output-contract.md +221 -0
  54. package/template/docs/assets/references/path-and-link-hygiene.md +49 -0
  55. package/template/docs/assets/references/planning-workflow.md +160 -0
  56. package/template/docs/assets/references/prd-change-management.md +129 -0
  57. package/template/docs/assets/references/wave-model.md +76 -0
  58. package/template/docs/assets/templates/AGENTS.md +8 -0
  59. package/template/docs/assets/templates/CLAUDE.md +8 -0
  60. package/template/docs/assets/templates/design.md +30 -0
  61. package/template/docs/assets/templates/guide-developer.md +54 -0
  62. package/template/docs/assets/templates/guide-user.md +58 -0
  63. package/template/docs/assets/templates/history-record.md +62 -0
  64. package/template/docs/assets/templates/plan-overview.md +32 -0
  65. package/template/docs/assets/templates/plan-prd-change.md +99 -0
  66. package/template/docs/assets/templates/plan-prd-decompose.md +70 -0
  67. package/template/docs/assets/templates/plan-prd.md +124 -0
  68. package/template/docs/assets/templates/prd-architecture.md +51 -0
  69. package/template/docs/assets/templates/prd-change-addition.md +45 -0
  70. package/template/docs/assets/templates/prd-change-revision.md +45 -0
  71. package/template/docs/assets/templates/prd-glossary.md +15 -0
  72. package/template/docs/assets/templates/prd-index.md +45 -0
  73. package/template/docs/assets/templates/prd-overview.md +43 -0
  74. package/template/docs/assets/templates/prd-reference.md +17 -0
  75. package/template/docs/assets/templates/prd-risk-register.md +55 -0
  76. package/template/docs/assets/templates/prd-subsystem.md +49 -0
  77. package/template/docs/assets/templates/work-index.md +21 -0
  78. package/template/docs/assets/templates/work-phase.md +34 -0
  79. package/template/docs/designs/AGENTS.md +21 -0
  80. package/template/docs/designs/CLAUDE.md +21 -0
  81. package/template/docs/guides/AGENTS.md +15 -0
  82. package/template/docs/guides/CLAUDE.md +15 -0
  83. package/template/docs/plans/AGENTS.md +20 -0
  84. package/template/docs/plans/CLAUDE.md +20 -0
  85. package/template/docs/prd/AGENTS.md +9 -0
  86. package/template/docs/prd/CLAUDE.md +9 -0
  87. package/template/docs/work/AGENTS.md +18 -0
  88. package/template/docs/work/CLAUDE.md +18 -0
@@ -0,0 +1,435 @@
1
+ #!/usr/bin/env python3
2
+ """Audit Make Docs-managed files for local absolute paths."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import re
9
+ import sys
10
+ import tempfile
11
+ import unittest
12
+ from dataclasses import asdict, dataclass
13
+ from pathlib import Path
14
+ from typing import Iterable
15
+
16
+
17
+ DEFAULT_ALLOW_TOKEN = "make-docs-path-hygiene: allow"
18
+ DEFAULT_TEXT_EXTENSIONS = {".md", ".rst", ".txt"}
19
+ SKILL_TEXT_EXTENSIONS = DEFAULT_TEXT_EXTENSIONS | {".json", ".py", ".toml", ".yaml", ".yml"}
20
+ PATH_CHARS_RE = re.compile(r"[^\s`\"'<>()\[\]{}]+")
21
+ MARKDOWN_LINK_RE = re.compile(r"(!?\[[^\]]+\]\()([^)\s]+)([^)]*\))")
22
+ POSIX_HOME_RE = re.compile(r"/(?:Users|home)/[^/\s`\"'<>()\[\]{}]+(?:/[^\s`\"'<>()\[\]{}]+)*")
23
+ WSL_HOME_RE = re.compile(r"/mnt/[A-Za-z]/Users/[^/\s`\"'<>()\[\]{}]+(?:/[^\s`\"'<>()\[\]{}]+)*")
24
+ WINDOWS_HOME_RE = re.compile(r"[A-Za-z]:\\Users\\[^\\\s`\"'<>()\[\]{}]+(?:\\[^\s`\"'<>()\[\]{}]+)*")
25
+ MAC_TEMP_RE = re.compile(r"/(?:private/)?var/folders/[^\s`\"'<>()\[\]{}]+")
26
+ SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
27
+
28
+
29
+ @dataclass
30
+ class Finding:
31
+ file: str
32
+ line: int
33
+ column: int
34
+ kind: str
35
+ match: str
36
+ suggestion: str | None
37
+ auto_fixable: bool
38
+ allowed: bool
39
+ reason: str | None = None
40
+
41
+
42
+ @dataclass
43
+ class ScanResult:
44
+ checked_files: int
45
+ changed_files: list[str]
46
+ findings: list[Finding]
47
+ io_errors: list[str]
48
+
49
+
50
+ def parse_args(argv: list[str]) -> argparse.Namespace:
51
+ parser = argparse.ArgumentParser(description=__doc__)
52
+ parser.add_argument("--manifest", default=".make-docs/manifest.json")
53
+ parser.add_argument("--repo-root", default=".")
54
+ parser.add_argument("--format", choices=("text", "json"), default="text")
55
+ parser.add_argument("--fix", action="store_true")
56
+ parser.add_argument("--include-skills", action="store_true")
57
+ parser.add_argument("--allow-comment-token", default=DEFAULT_ALLOW_TOKEN)
58
+ parser.add_argument("--self-test", action="store_true")
59
+ return parser.parse_args(argv)
60
+
61
+
62
+ def load_manifest(path: Path) -> dict:
63
+ try:
64
+ return json.loads(path.read_text(encoding="utf-8"))
65
+ except FileNotFoundError as exc:
66
+ raise ValueError(f"manifest not found: {path}") from exc
67
+ except json.JSONDecodeError as exc:
68
+ raise ValueError(f"invalid manifest JSON: {path}: {exc}") from exc
69
+
70
+
71
+ def iter_manifest_paths(manifest: dict, include_skills: bool) -> Iterable[str]:
72
+ files = manifest.get("files", {})
73
+ if isinstance(files, dict):
74
+ yield from files.keys()
75
+ elif isinstance(files, list):
76
+ for item in files:
77
+ if isinstance(item, str):
78
+ yield item
79
+ elif isinstance(item, dict) and isinstance(item.get("path"), str):
80
+ yield item["path"]
81
+ if include_skills:
82
+ for item in manifest.get("skillFiles", []):
83
+ if isinstance(item, str):
84
+ yield item
85
+ elif isinstance(item, dict) and isinstance(item.get("path"), str):
86
+ yield item["path"]
87
+
88
+
89
+ def is_text_path(path: str, include_skills: bool) -> bool:
90
+ ext = Path(path).suffix.lower()
91
+ extensions = SKILL_TEXT_EXTENSIONS if include_skills else DEFAULT_TEXT_EXTENSIONS
92
+ return ext in extensions
93
+
94
+
95
+ def is_allowed(lines: list[str], line_index: int, token: str) -> tuple[bool, str | None]:
96
+ candidates = [lines[line_index]]
97
+ if line_index > 0:
98
+ candidates.append(lines[line_index - 1])
99
+ for candidate in candidates:
100
+ if token in candidate:
101
+ reason = candidate.split(token, 1)[1].strip(" -:<>")
102
+ return True, reason or "allow comment present"
103
+ return False, None
104
+
105
+
106
+ def markdown_link_destination_at(line: str, start: int, end: int) -> bool:
107
+ for match in MARKDOWN_LINK_RE.finditer(line):
108
+ dest_start, dest_end = match.span(2)
109
+ if dest_start <= start and end <= dest_end:
110
+ return True
111
+ return False
112
+
113
+
114
+ def repo_relative_suggestion(repo_root: str, matched: str, in_link: bool) -> str:
115
+ suffix = matched[len(repo_root) :]
116
+ if suffix.startswith(("/", "\\")):
117
+ suffix = suffix[1:]
118
+ if not suffix:
119
+ return "."
120
+ normalized = suffix.replace("\\", "/")
121
+ return normalized if in_link else f"./{normalized}"
122
+
123
+
124
+ def home_placeholder_suggestion(matched: str) -> str | None:
125
+ if matched.startswith(("/Users/", "/home/")):
126
+ parts = matched.split("/", 3)
127
+ if len(parts) == 4:
128
+ return f"<user-home>/{parts[3]}"
129
+ return "<user-home>"
130
+ wsl = re.match(r"^/mnt/[A-Za-z]/Users/[^/]+(?:/(.*))?$", matched)
131
+ if wsl:
132
+ suffix = wsl.group(1)
133
+ return f"<user-home>/{suffix}" if suffix else "<user-home>"
134
+ windows = re.match(r"^[A-Za-z]:\\Users\\[^\\]+(?:\\(.*))?$", matched)
135
+ if windows:
136
+ suffix = windows.group(1)
137
+ return f"<user-home>\\{suffix}" if suffix else "<user-home>"
138
+ return None
139
+
140
+
141
+ def temp_placeholder_suggestion(matched: str) -> str:
142
+ tail_match = re.match(r"^/(?:private/)?var/folders/[^/]+/[^/]+/(.*)$", matched)
143
+ return f"<temp-dir>/{tail_match.group(1)}" if tail_match else "<temp-dir>/..."
144
+
145
+
146
+ def absolute_markdown_link_findings(line: str) -> list[tuple[int, int, str]]:
147
+ findings: list[tuple[int, int, str]] = []
148
+ for match in MARKDOWN_LINK_RE.finditer(line):
149
+ dest = match.group(2)
150
+ if dest.startswith("//") or SCHEME_RE.match(dest):
151
+ continue
152
+ if dest.startswith("/") or WINDOWS_HOME_RE.match(dest):
153
+ findings.append((match.start(2), match.end(2), dest))
154
+ return findings
155
+
156
+
157
+ def collect_line_findings(
158
+ rel_file: str,
159
+ line: str,
160
+ line_number: int,
161
+ line_index: int,
162
+ lines: list[str],
163
+ repo_root: str,
164
+ allow_token: str,
165
+ ) -> list[Finding]:
166
+ allowed, reason = is_allowed(lines, line_index, allow_token)
167
+ findings: list[Finding] = []
168
+ spans: list[tuple[int, int]] = []
169
+
170
+ search_start = 0
171
+ while True:
172
+ start = line.find(repo_root, search_start)
173
+ if start == -1:
174
+ break
175
+ path_match = PATH_CHARS_RE.match(line, start)
176
+ end = path_match.end() if path_match else start + len(repo_root)
177
+ matched = line[start:end]
178
+ in_link = markdown_link_destination_at(line, start, end)
179
+ suggestion = repo_relative_suggestion(repo_root, matched, in_link)
180
+ findings.append(
181
+ Finding(
182
+ file=rel_file,
183
+ line=line_number,
184
+ column=start + 1,
185
+ kind="repo_root_absolute_path",
186
+ match=matched,
187
+ suggestion=suggestion,
188
+ auto_fixable=True,
189
+ allowed=allowed,
190
+ reason=reason,
191
+ )
192
+ )
193
+ spans.append((start, end))
194
+ search_start = end
195
+
196
+ for pattern, kind, suggestion_fn in (
197
+ (WSL_HOME_RE, "wsl_user_home_path", home_placeholder_suggestion),
198
+ (WINDOWS_HOME_RE, "windows_user_home_path", home_placeholder_suggestion),
199
+ (POSIX_HOME_RE, "posix_user_home_path", home_placeholder_suggestion),
200
+ (MAC_TEMP_RE, "macos_temp_path", temp_placeholder_suggestion),
201
+ ):
202
+ for match in pattern.finditer(line):
203
+ start, end = match.span()
204
+ if any(span_start <= start < span_end for span_start, span_end in spans):
205
+ continue
206
+ matched = match.group(0)
207
+ findings.append(
208
+ Finding(
209
+ file=rel_file,
210
+ line=line_number,
211
+ column=start + 1,
212
+ kind=kind,
213
+ match=matched,
214
+ suggestion=suggestion_fn(matched),
215
+ auto_fixable=False,
216
+ allowed=allowed,
217
+ reason=reason,
218
+ )
219
+ )
220
+ spans.append((start, end))
221
+
222
+ for start, end, dest in absolute_markdown_link_findings(line):
223
+ if any(span_start <= start < span_end for span_start, span_end in spans):
224
+ continue
225
+ suggestion = dest[1:] if dest.startswith("/") else home_placeholder_suggestion(dest)
226
+ findings.append(
227
+ Finding(
228
+ file=rel_file,
229
+ line=line_number,
230
+ column=start + 1,
231
+ kind="absolute_markdown_link_destination",
232
+ match=dest,
233
+ suggestion=suggestion,
234
+ auto_fixable=False,
235
+ allowed=allowed,
236
+ reason=reason,
237
+ )
238
+ )
239
+
240
+ return findings
241
+
242
+
243
+ def fix_repo_root_paths(text: str, repo_root: str) -> str:
244
+ def replace_line(line: str) -> str:
245
+ matches = list(re.finditer(re.escape(repo_root), line))
246
+ if not matches:
247
+ return line
248
+ rebuilt = []
249
+ last = 0
250
+ for match in matches:
251
+ start = match.start()
252
+ path_match = PATH_CHARS_RE.match(line, start)
253
+ end = path_match.end() if path_match else match.end()
254
+ matched = line[start:end]
255
+ rebuilt.append(line[last:start])
256
+ rebuilt.append(repo_relative_suggestion(repo_root, matched, markdown_link_destination_at(line, start, end)))
257
+ last = end
258
+ rebuilt.append(line[last:])
259
+ return "".join(rebuilt)
260
+
261
+ return "\n".join(replace_line(line) for line in text.split("\n"))
262
+
263
+
264
+ def scan_file(path: Path, rel_file: str, repo_root: str, allow_token: str, fix: bool) -> tuple[list[Finding], bool]:
265
+ original = path.read_text(encoding="utf-8")
266
+ updated = fix_repo_root_paths(original, repo_root) if fix else original
267
+ changed = updated != original
268
+ if changed:
269
+ path.write_text(updated, encoding="utf-8")
270
+ lines = updated.splitlines()
271
+ findings: list[Finding] = []
272
+ for index, line in enumerate(lines):
273
+ findings.extend(collect_line_findings(rel_file, line, index + 1, index, lines, repo_root, allow_token))
274
+ return findings, changed
275
+
276
+
277
+ def scan_manifest(
278
+ manifest_path: Path,
279
+ repo_root: Path,
280
+ include_skills: bool,
281
+ allow_token: str,
282
+ fix: bool,
283
+ ) -> ScanResult:
284
+ manifest = load_manifest(manifest_path)
285
+ rel_paths = sorted({path for path in iter_manifest_paths(manifest, include_skills) if is_text_path(path, include_skills)})
286
+ findings: list[Finding] = []
287
+ io_errors: list[str] = []
288
+ changed_files: list[str] = []
289
+ checked = 0
290
+ repo_root_str = str(repo_root.resolve())
291
+ for rel_path in rel_paths:
292
+ path = repo_root / rel_path
293
+ if not path.exists():
294
+ io_errors.append(f"missing managed file: {rel_path}")
295
+ continue
296
+ try:
297
+ file_findings, changed = scan_file(path, rel_path, repo_root_str, allow_token, fix)
298
+ except UnicodeDecodeError:
299
+ io_errors.append(f"not valid UTF-8: {rel_path}")
300
+ continue
301
+ except OSError as exc:
302
+ io_errors.append(f"cannot read {rel_path}: {exc}")
303
+ continue
304
+ checked += 1
305
+ findings.extend(file_findings)
306
+ if changed:
307
+ changed_files.append(rel_path)
308
+ return ScanResult(checked, changed_files, findings, io_errors)
309
+
310
+
311
+ def failing_findings(findings: list[Finding]) -> list[Finding]:
312
+ return [finding for finding in findings if not finding.allowed]
313
+
314
+
315
+ def print_text(result: ScanResult) -> None:
316
+ for error in result.io_errors:
317
+ print(f"ERROR: {error}")
318
+ for finding in result.findings:
319
+ status = "allowed" if finding.allowed else "error"
320
+ suggestion = f" -> {finding.suggestion}" if finding.suggestion else ""
321
+ print(
322
+ f"{status}: {finding.file}:{finding.line}:{finding.column}: "
323
+ f"{finding.kind}: {finding.match}{suggestion}"
324
+ )
325
+ errors = len(failing_findings(result.findings))
326
+ allowed = len(result.findings) - errors
327
+ print(
328
+ f"checked_files={result.checked_files} "
329
+ f"changed_files={len(result.changed_files)} "
330
+ f"errors={errors} "
331
+ f"allowed={allowed}"
332
+ )
333
+
334
+
335
+ def print_json(result: ScanResult) -> None:
336
+ errors = len(failing_findings(result.findings))
337
+ allowed = len(result.findings) - errors
338
+ payload = {
339
+ "checked_files": result.checked_files,
340
+ "changed_files": result.changed_files,
341
+ "findings": [asdict(finding) for finding in result.findings],
342
+ "summary": {"errors": errors, "allowed": allowed},
343
+ }
344
+ if result.io_errors:
345
+ payload["io_errors"] = result.io_errors
346
+ print(json.dumps(payload, indent=2, sort_keys=True))
347
+
348
+
349
+ class PathHygieneTests(unittest.TestCase):
350
+ def run_scan(self, body: str, fix: bool = False) -> tuple[ScanResult, Path]:
351
+ root = Path(tempfile.mkdtemp(prefix="path-hygiene-")).resolve()
352
+ docs = root / "docs"
353
+ docs.mkdir()
354
+ target = docs / "example.md"
355
+ target.write_text(body, encoding="utf-8")
356
+ manifest = root / ".make-docs" / "manifest.json"
357
+ manifest.parent.mkdir()
358
+ manifest.write_text(
359
+ json.dumps({"files": {"docs/example.md": {"hash": "unused", "sourceId": "file:docs/example.md"}}}),
360
+ encoding="utf-8",
361
+ )
362
+ return scan_manifest(manifest, root, False, DEFAULT_ALLOW_TOKEN, fix), target
363
+
364
+ def test_repo_root_paths_are_fixable(self) -> None:
365
+ root = Path(tempfile.mkdtemp(prefix="path-hygiene-root-")).resolve()
366
+ docs = root / "docs"
367
+ docs.mkdir()
368
+ target = docs / "example.md"
369
+ target.write_text(f"[Read]({root}/README.md)\nPath `{root}/docs/example.md`\n", encoding="utf-8")
370
+ manifest = root / ".make-docs" / "manifest.json"
371
+ manifest.parent.mkdir()
372
+ manifest.write_text(
373
+ json.dumps({"files": {"docs/example.md": {"hash": "unused", "sourceId": "file:docs/example.md"}}}),
374
+ encoding="utf-8",
375
+ )
376
+ result = scan_manifest(manifest, root, False, DEFAULT_ALLOW_TOKEN, True)
377
+ self.assertEqual([], failing_findings(result.findings))
378
+ self.assertEqual("[Read](README.md)\nPath `./docs/example.md`\n", target.read_text(encoding="utf-8"))
379
+ self.assertEqual(["docs/example.md"], result.changed_files)
380
+
381
+ def test_user_home_path_reports_without_fix(self) -> None:
382
+ result, _target = self.run_scan("See `/Users/alice/project/README.md`.\n", fix=True)
383
+ self.assertEqual(1, len(failing_findings(result.findings)))
384
+ self.assertFalse(result.findings[0].auto_fixable)
385
+ self.assertEqual("<user-home>/project/README.md", result.findings[0].suggestion)
386
+
387
+ def test_allow_comment_suppresses_failure(self) -> None:
388
+ result, _target = self.run_scan(
389
+ "<!-- make-docs-path-hygiene: allow retained diagnostic evidence -->\n"
390
+ "See `/Users/alice/project/README.md`.\n"
391
+ )
392
+ self.assertEqual([], failing_findings(result.findings))
393
+ self.assertEqual(1, len(result.findings))
394
+ self.assertTrue(result.findings[0].allowed)
395
+
396
+ def test_sanitized_placeholders_are_not_flagged(self) -> None:
397
+ result, _target = self.run_scan("Use `<user-home>/project`, `$HOME/project`, and `<repo-root>/README.md`.\n")
398
+ self.assertEqual([], result.findings)
399
+
400
+ def test_absolute_markdown_link_is_reported(self) -> None:
401
+ result, _target = self.run_scan("See [docs](/docs/prd/00-index.md).\n")
402
+ self.assertEqual(1, len(failing_findings(result.findings)))
403
+ self.assertEqual("absolute_markdown_link_destination", result.findings[0].kind)
404
+ self.assertEqual("docs/prd/00-index.md", result.findings[0].suggestion)
405
+
406
+
407
+ def run_self_tests() -> int:
408
+ suite = unittest.defaultTestLoader.loadTestsFromTestCase(PathHygieneTests)
409
+ return 0 if unittest.TextTestRunner(verbosity=2).run(suite).wasSuccessful() else 1
410
+
411
+
412
+ def main(argv: list[str]) -> int:
413
+ args = parse_args(argv)
414
+ if args.self_test:
415
+ return run_self_tests()
416
+ repo_root = Path(args.repo_root).resolve()
417
+ manifest_path = Path(args.manifest)
418
+ if not manifest_path.is_absolute():
419
+ manifest_path = repo_root / manifest_path
420
+ try:
421
+ result = scan_manifest(manifest_path, repo_root, args.include_skills, args.allow_comment_token, args.fix)
422
+ except ValueError as exc:
423
+ print(f"ERROR: {exc}", file=sys.stderr)
424
+ return 2
425
+ if args.format == "json":
426
+ print_json(result)
427
+ else:
428
+ print_text(result)
429
+ if result.io_errors:
430
+ return 2
431
+ return 1 if failing_findings(result.findings) else 0
432
+
433
+
434
+ if __name__ == "__main__":
435
+ raise SystemExit(main(sys.argv[1:]))
@@ -0,0 +1,3 @@
1
+ # Agent Instructions
2
+
3
+ When asked to create documentation for this project that is not `README.md`, read the same-named instruction file in `docs/` before writing.
@@ -0,0 +1,3 @@
1
+ # Agent Instructions
2
+
3
+ When asked to create documentation for this project that is not `README.md`, read the same-named instruction file in `docs/` before writing.
@@ -0,0 +1,15 @@
1
+ # Documentation Router
2
+
3
+ Use `docs/` only as a router. Do not create generated files directly in this directory.
4
+
5
+ - Source Markdown uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `docs/assets/references/path-and-link-hygiene.md` when auditing or deciding whether an absolute path is warranted.
6
+ - For design docs, read `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`, then continue in `docs/designs/`.
7
+ - For plans, read `docs/assets/references/planning-workflow.md` and the selected plan template in `docs/assets/templates/`, then continue in `docs/plans/`.
8
+ - For PRD or work generation, read `docs/assets/references/execution-workflow.md`, `docs/assets/references/output-contract.md`, and the selected template in `docs/assets/templates/`, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
9
+ - For requirement changes, also read `docs/assets/references/prd-change-management.md` before choosing change templates or delta outputs.
10
+ - For gaps, drift, unresolved questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists; do not create separate questions, decisions, risks, gaps, or architecture-decision files unless the user explicitly asks.
11
+ - For guides, continue in `docs/guides/`. Before writing, read `docs/assets/references/guide-contract.md`, inspect existing guides for overlap, choose `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`, and use the matching template (`docs/assets/templates/guide-developer.md` or `docs/assets/templates/guide-user.md`).
12
+ - After guide work, reconcile overlapping existing guides with reciprocal links, `related` frontmatter, or concise supplemental context when it improves discoverability.
13
+ - Use `## Future Coverage` inside guides for downstream-dependent guide updates. Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
14
+ - For history records, continue in `docs/assets/history/` — read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
15
+ - For reusable prompt starters, use `docs/assets/prompts/`; prompts are optional starters, not authority.
@@ -0,0 +1,15 @@
1
+ # Documentation Router
2
+
3
+ Use `docs/` only as a router. Do not create generated files directly in this directory.
4
+
5
+ - Source Markdown uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `docs/assets/references/path-and-link-hygiene.md` when auditing or deciding whether an absolute path is warranted.
6
+ - For design docs, read `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`, then continue in `docs/designs/`.
7
+ - For plans, read `docs/assets/references/planning-workflow.md` and the selected plan template in `docs/assets/templates/`, then continue in `docs/plans/`.
8
+ - For PRD or work generation, read `docs/assets/references/execution-workflow.md`, `docs/assets/references/output-contract.md`, and the selected template in `docs/assets/templates/`, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
9
+ - For requirement changes, also read `docs/assets/references/prd-change-management.md` before choosing change templates or delta outputs.
10
+ - For gaps, drift, unresolved questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists; do not create separate questions, decisions, risks, gaps, or architecture-decision files unless the user explicitly asks.
11
+ - For guides, continue in `docs/guides/`. Before writing, read `docs/assets/references/guide-contract.md`, inspect existing guides for overlap, choose `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`, and use the matching template (`docs/assets/templates/guide-developer.md` or `docs/assets/templates/guide-user.md`).
12
+ - After guide work, reconcile overlapping existing guides with reciprocal links, `related` frontmatter, or concise supplemental context when it improves discoverability.
13
+ - Use `## Future Coverage` inside guides for downstream-dependent guide updates. Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
14
+ - For history records, continue in `docs/assets/history/` — read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
15
+ - For reusable prompt starters, use `docs/assets/prompts/`; prompts are optional starters, not authority.
@@ -0,0 +1,9 @@
1
+ # Document Assets Router
2
+
3
+ This router describes the target `docs/assets/` document-resource namespace.
4
+
5
+ - Archive records belong in `docs/assets/archive/`.
6
+ - History records belong in `docs/assets/history/`; read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
7
+ - Reusable prompts, references, and templates belong in `docs/assets/prompts/`, `docs/assets/references/`, and `docs/assets/templates/`.
8
+ - make-docs runtime state does not belong under `docs/assets/`; canonical state lives at `.make-docs/manifest.json` and `.make-docs/conflicts/<run-id>/`.
9
+ - Do not create `docs/assets/config/`, `docs/assets/state/`, `docs/assets/manifest.json`, or `docs/assets/conflicts/`.
@@ -0,0 +1,9 @@
1
+ # Document Assets Router
2
+
3
+ This router describes the target `docs/assets/` document-resource namespace.
4
+
5
+ - Archive records belong in `docs/assets/archive/`.
6
+ - History records belong in `docs/assets/history/`; read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
7
+ - Reusable prompts, references, and templates belong in `docs/assets/prompts/`, `docs/assets/references/`, and `docs/assets/templates/`.
8
+ - make-docs runtime state does not belong under `docs/assets/`; canonical state lives at `.make-docs/manifest.json` and `.make-docs/conflicts/<run-id>/`.
9
+ - Do not create `docs/assets/config/`, `docs/assets/state/`, `docs/assets/manifest.json`, or `docs/assets/conflicts/`.
@@ -0,0 +1,20 @@
1
+ # Archive Router
2
+
3
+ This directory is the single consolidated archive for all artifact types and mirrors the structure of `docs/`. It is the authority for archival rules; other routers and contracts defer here.
4
+
5
+ ## Sub-directory mapping
6
+
7
+ - `docs/assets/archive/designs/` — archived designs (mirrors `docs/designs/`).
8
+ - `docs/assets/archive/plans/` — archived plan directories (mirrors `docs/plans/`).
9
+ - `docs/assets/archive/work/` — archived work directories (mirrors `docs/work/`).
10
+ - `docs/assets/archive/prds/` — archived PRD sets grouped by date: `docs/assets/archive/prds/YYYY-MM-DD/`; use `-XX` increment suffix when the same date repeats.
11
+ - `docs/assets/archive/history/` — archived history records (mirrors `docs/assets/history/`).
12
+ - `docs/assets/archive/guides/developer/` — archived developer guides.
13
+ - `docs/assets/archive/guides/user/` — archived user guides.
14
+
15
+ Sub-directories are created only when an artifact is explicitly archived. Do not pre-create them.
16
+
17
+ ## Rules
18
+
19
+ - HARD RULE: never move anything into `docs/assets/archive/` unless the user explicitly asks. Archiving can break relative links and obscure lineage.
20
+ - Archived artifacts are referenced in place via relative links to `docs/assets/archive/...`; they are not moved back to their original location.
@@ -0,0 +1,20 @@
1
+ # Archive Router
2
+
3
+ This directory is the single consolidated archive for all artifact types and mirrors the structure of `docs/`. It is the authority for archival rules; other routers and contracts defer here.
4
+
5
+ ## Sub-directory mapping
6
+
7
+ - `docs/assets/archive/designs/` — archived designs (mirrors `docs/designs/`).
8
+ - `docs/assets/archive/plans/` — archived plan directories (mirrors `docs/plans/`).
9
+ - `docs/assets/archive/work/` — archived work directories (mirrors `docs/work/`).
10
+ - `docs/assets/archive/prds/` — archived PRD sets grouped by date: `docs/assets/archive/prds/YYYY-MM-DD/`; use `-XX` increment suffix when the same date repeats.
11
+ - `docs/assets/archive/history/` — archived history records (mirrors `docs/assets/history/`).
12
+ - `docs/assets/archive/guides/developer/` — archived developer guides.
13
+ - `docs/assets/archive/guides/user/` — archived user guides.
14
+
15
+ Sub-directories are created only when an artifact is explicitly archived. Do not pre-create them.
16
+
17
+ ## Rules
18
+
19
+ - HARD RULE: never move anything into `docs/assets/archive/` unless the user explicitly asks. Archiving can break relative links and obscure lineage.
20
+ - Archived artifacts are referenced in place via relative links to `docs/assets/archive/...`; they are not moved back to their original location.
@@ -0,0 +1,12 @@
1
+ # History Assets Router
2
+
3
+ This directory stores session history records.
4
+
5
+ - Before writing, read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md`.
6
+ - When W/R/P is known, create records at `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md`.
7
+ - If only W/R is known, create records at `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md`.
8
+ - If no coordinate is known, create records at `docs/assets/history/YYYY-MM-DD-<slug>.md`.
9
+ - Keep stage and task detail only in `coordinate` frontmatter, not filenames.
10
+ - Include only known frontmatter fields; do not invent unknown client, model, or provider values.
11
+ - Keep records concise: breadcrumbs for a future auditor, not live logs.
12
+ - Use relative Markdown links when referencing files touched during the session.
@@ -0,0 +1,12 @@
1
+ # History Assets Router
2
+
3
+ This directory stores session history records.
4
+
5
+ - Before writing, read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md`.
6
+ - When W/R/P is known, create records at `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md`.
7
+ - If only W/R is known, create records at `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md`.
8
+ - If no coordinate is known, create records at `docs/assets/history/YYYY-MM-DD-<slug>.md`.
9
+ - Keep stage and task detail only in `coordinate` frontmatter, not filenames.
10
+ - Include only known frontmatter fields; do not invent unknown client, model, or provider values.
11
+ - Keep records concise: breadcrumbs for a future auditor, not live logs.
12
+ - Use relative Markdown links when referencing files touched during the session.
@@ -0,0 +1,8 @@
1
+ # Prompts Router
2
+
3
+ This directory stores reusable prompt starters, not authoritative rules and not generated outputs.
4
+
5
+ - Use it only when the user wants a stored prompt or a reusable workflow kickoff.
6
+ - Keep placeholder tokens explicit unless the user asks to instantiate them.
7
+ - When executing a prompt, read the target workflow in `docs/assets/references/`, the matching template in `docs/assets/templates/`, and the router in the target output directory.
8
+ - Do not write generated plans, PRDs, work backlogs, or designs here.
@@ -0,0 +1,8 @@
1
+ # Prompts Router
2
+
3
+ This directory stores reusable prompt starters, not authoritative rules and not generated outputs.
4
+
5
+ - Use it only when the user wants a stored prompt or a reusable workflow kickoff.
6
+ - Keep placeholder tokens explicit unless the user asks to instantiate them.
7
+ - When executing a prompt, read the target workflow in `docs/assets/references/`, the matching template in `docs/assets/templates/`, and the router in the target output directory.
8
+ - Do not write generated plans, PRDs, work backlogs, or designs here.
@@ -0,0 +1,14 @@
1
+ ___
2
+ name: Designs to Plan Change
3
+ description: Instructs the agent to review one or more design docs and generate a change plan for the active PRD namespace.
4
+ ___
5
+
6
+ Please read the design docs {{DESIGN DOCS}} and inspect each doc's `## Intended Follow-On` section before planning. If a design includes `Coordinate Handoff`, use it as the starting point for W/R resolution.
7
+
8
+ Confirm that the referenced design docs point to the `change-plan` route. If they point to `baseline-plan`, use the baseline planning prompt instead unless the user explicitly instructs otherwise.
9
+
10
+ Then inspect the active PRD namespace in `docs/prd/` and create a detailed change plan in `docs/plans/`. Follow the instructions, references, and templates in the `docs` directory, especially `docs/assets/references/wave-model.md` and `docs/assets/references/prd-change-management.md`.
11
+
12
+ Resolve the plan coordinate before writing. Source lineage from the user request, design handoff, prior plans, prior work backlogs, and history records takes precedence over the highest existing wave. If the change revises, reworks, corrects, standardizes, or finishes work delivered in an earlier wave, keep that wave and use the next unused revision.
13
+
14
+ The plan should classify the request as an addition, enhancement, revision, or removal; record the coordinate decision; identify the impacted baseline docs; define the new PRD change docs that should be created; define the required baseline annotations; and state whether a scoped delta backlog is sufficient.
@@ -0,0 +1,10 @@
1
+ ___
2
+ name: Design to Plan
3
+ description: Instructs the agent to review referenced design docs and then generate a detailed plan.
4
+ ___
5
+
6
+ Please read the design docs {{DESIGN DOCS}} and inspect each doc's `## Intended Follow-On` section before planning. If a design includes `Coordinate Handoff`, use it as the starting point for W/R resolution.
7
+
8
+ Confirm that the referenced design docs point to the `baseline-plan` route. If they point to `change-plan`, use the change-planning prompt instead unless the user explicitly instructs otherwise.
9
+
10
+ Then help me create a detailed plan document in `docs/plans` to implement this design idea. Follow `docs/assets/references/wave-model.md` and record the coordinate decision in the plan.
@@ -0,0 +1,27 @@
1
+ ___
2
+ name: Docs Path Hygiene Cleanup
3
+ description: Instructs the agent to audit and repair Make Docs-managed documentation for local absolute checkout and user-specific paths.
4
+ ___
5
+
6
+ Please audit and repair Make Docs-managed documentation for local, user-specific, or checkout-specific paths.
7
+
8
+ Before editing anything, read `.make-docs/manifest.json`, `docs/AGENTS.md`, and `docs/assets/references/path-and-link-hygiene.md`. Treat the path hygiene reference as the authority for project-relative paths, relative Markdown links, sanitized placeholders, and full-path exceptions.
9
+
10
+ Run the deterministic checker:
11
+
12
+ ```bash
13
+ python3 .make-docs/scripts/check_path_hygiene.py --manifest .make-docs/manifest.json --format json
14
+ ```
15
+
16
+ For each still-valid finding, repair the documentation with a project-relative path or sanitized placeholder. Preserve full paths only when the reference allows the exception, and add or preserve the `make-docs-path-hygiene: allow` comment with a clear reason.
17
+
18
+ After repairs, rerun:
19
+
20
+ ```bash
21
+ python3 .make-docs/scripts/check_path_hygiene.py --manifest .make-docs/manifest.json --format text
22
+ just docs-links docs
23
+ just docs-style docs
24
+ git diff --check
25
+ ```
26
+
27
+ Report the files changed, the findings fixed, any findings intentionally skipped with reasons, and any validation command that could not be run.
@@ -0,0 +1,8 @@
1
+ ___
2
+ name: Plan to PRD Change
3
+ description: Instructs the agent to execute an approved change plan by appending change docs to the active PRD namespace and updating affected baseline docs non-destructively.
4
+ ___
5
+
6
+ Please review the approved change plan {{CHANGE PLAN DOC}} and then execute it against the active PRD namespace in `docs/prd/`.
7
+
8
+ Follow the instructions, references, and templates in the `docs` directory, especially `docs/assets/references/prd-change-management.md`. Append the required new change docs using the next available numbers, update the impacted baseline docs with the required `### Change Notes` backlinks, and update `docs/prd/00-index.md` so status and lineage are clear. Do not renumber or reorder existing PRD docs, and do not perform a cleanup rewrite unless the plan or the user explicitly asks for it.