@brucewaynedecoy/make-docs 1.0.0-rc.1 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (187) hide show
  1. package/LICENSE +21 -201
  2. package/README.md +36 -27
  3. package/dist/backup-73HQNKMC.js +20 -0
  4. package/dist/backup-73HQNKMC.js.map +1 -0
  5. package/dist/chunk-3BAJQXGH.js +1575 -0
  6. package/dist/chunk-3BAJQXGH.js.map +1 -0
  7. package/dist/chunk-64CTKJO7.js +4136 -0
  8. package/dist/chunk-64CTKJO7.js.map +1 -0
  9. package/dist/chunk-BENO4IH5.js +875 -0
  10. package/dist/chunk-BENO4IH5.js.map +1 -0
  11. package/dist/chunk-D4HDZEJT.js +37 -0
  12. package/dist/chunk-D4HDZEJT.js.map +1 -0
  13. package/dist/chunk-G5EF63GG.js +1291 -0
  14. package/dist/chunk-G5EF63GG.js.map +1 -0
  15. package/dist/chunk-GNP6HRVP.js +523 -0
  16. package/dist/chunk-GNP6HRVP.js.map +1 -0
  17. package/dist/chunk-HJYIQTMD.js +204 -0
  18. package/dist/chunk-HJYIQTMD.js.map +1 -0
  19. package/dist/chunk-LQ5NSWCJ.js +39 -0
  20. package/dist/chunk-LQ5NSWCJ.js.map +1 -0
  21. package/dist/chunk-LRVV7UDD.js +2340 -0
  22. package/dist/chunk-LRVV7UDD.js.map +1 -0
  23. package/dist/chunk-LVQSJF63.js +24674 -0
  24. package/dist/chunk-LVQSJF63.js.map +1 -0
  25. package/dist/chunk-MXBHCHSM.js +13995 -0
  26. package/dist/chunk-MXBHCHSM.js.map +1 -0
  27. package/dist/chunk-Z5K4FHYP.js +922 -0
  28. package/dist/chunk-Z5K4FHYP.js.map +1 -0
  29. package/dist/index.js +3798 -250
  30. package/dist/index.js.map +1 -1
  31. package/dist/self-YYXOLDKU.js +653 -0
  32. package/dist/self-YYXOLDKU.js.map +1 -0
  33. package/dist/server-O2ZELIMX.js +512 -0
  34. package/dist/server-O2ZELIMX.js.map +1 -0
  35. package/dist/setup-system-HZROFNMP.js +544 -0
  36. package/dist/setup-system-HZROFNMP.js.map +1 -0
  37. package/dist/{skills-command-3ESCZ75U.js → skills-command-MGGHY7HU.js} +190 -32
  38. package/dist/skills-command-MGGHY7HU.js.map +1 -0
  39. package/dist/uninstall-3UXXXNFO.js +223 -0
  40. package/dist/uninstall-3UXXXNFO.js.map +1 -0
  41. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js +11 -0
  42. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js.map +1 -0
  43. package/package.json +9 -6
  44. package/skill-registry.json +328 -125
  45. package/skill-registry.schema.json +221 -45
  46. package/template/.make-docs/AGENTS.md +18 -0
  47. package/template/.make-docs/CLAUDE.md +18 -0
  48. package/template/.make-docs/archive/AGENTS.md +11 -0
  49. package/template/.make-docs/archive/CLAUDE.md +11 -0
  50. package/template/.make-docs/system/AGENTS.md +12 -0
  51. package/template/.make-docs/system/CLAUDE.md +12 -0
  52. package/template/.make-docs/system/contracts/AGENTS.md +13 -0
  53. package/template/.make-docs/system/contracts/CLAUDE.md +13 -0
  54. package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md +4 -4
  55. package/template/.make-docs/system/contracts/coverage-pass-contract.md +198 -0
  56. package/template/.make-docs/system/contracts/deferred-obligation-contract.md +128 -0
  57. package/template/{docs/assets/references → .make-docs/system/contracts}/design-contract.md +7 -2
  58. package/template/{docs/assets/references → .make-docs/system/contracts}/guide-contract.md +21 -19
  59. package/template/{docs/assets/references → .make-docs/system/contracts}/history-record-contract.md +17 -11
  60. package/template/.make-docs/system/contracts/human-experience-contract.md +134 -0
  61. package/template/.make-docs/system/contracts/naive-uat-contract.md +231 -0
  62. package/template/.make-docs/system/contracts/output-contract.md +277 -0
  63. package/template/.make-docs/system/contracts/performance-evidence-governance.md +257 -0
  64. package/template/.make-docs/system/contracts/system-resource-contract.md +93 -0
  65. package/template/.make-docs/system/prompts/AGENTS.md +12 -0
  66. package/template/.make-docs/system/prompts/CLAUDE.md +12 -0
  67. package/template/.make-docs/system/prompts/coverage-pass-maintainer-guide.prompt.md +20 -0
  68. package/template/.make-docs/system/prompts/coverage-pass-prd-reconciliation.prompt.md +18 -0
  69. package/template/.make-docs/system/prompts/coverage-pass-testing-uat.prompt.md +46 -0
  70. package/template/.make-docs/system/prompts/coverage-pass-user-guide.prompt.md +20 -0
  71. package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +18 -0
  72. package/template/.make-docs/system/prompts/designs-to-plan.prompt.md +14 -0
  73. package/template/.make-docs/system/prompts/docs-path-hygiene-cleanup.prompt.md +29 -0
  74. package/template/.make-docs/system/prompts/naive-uat-facilitator.prompt.md +28 -0
  75. package/template/.make-docs/system/prompts/naive-uat-tester.prompt.md +20 -0
  76. package/template/.make-docs/system/prompts/performance-coverage.prompt.md +63 -0
  77. package/template/.make-docs/system/prompts/plan-to-prd-change.prompt.md +12 -0
  78. package/template/.make-docs/system/prompts/plan-to-prd-green-field.prompt.md +10 -0
  79. package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +14 -0
  80. package/template/.make-docs/system/prompts/prd-to-work-full-prd.prompt.md +10 -0
  81. package/template/.make-docs/system/prompts/prd-to-work-prd-feature.prompt.md +10 -0
  82. package/template/.make-docs/system/prompts/request-to-design.prompt.md +20 -0
  83. package/template/.make-docs/system/prompts/session-to-history-record.prompt.md +23 -0
  84. package/template/{docs/assets → .make-docs/system}/prompts/work-to-commit-message.prompt.md +2 -2
  85. package/template/.make-docs/system/prompts/work-to-guides.prompt.md +22 -0
  86. package/template/.make-docs/system/references/AGENTS.md +14 -0
  87. package/template/.make-docs/system/references/CLAUDE.md +14 -0
  88. package/template/{docs/assets → .make-docs/system}/references/design-workflow.md +15 -2
  89. package/template/.make-docs/system/references/execution-workflow.md +189 -0
  90. package/template/.make-docs/system/references/human-experience.md +138 -0
  91. package/template/.make-docs/system/references/lifecycle.md +153 -0
  92. package/template/.make-docs/system/references/naive-uat-validation.md +65 -0
  93. package/template/.make-docs/system/references/naive-uat-workflow.md +64 -0
  94. package/template/.make-docs/system/references/path-and-link-hygiene.md +101 -0
  95. package/template/.make-docs/system/references/performance-evidence.md +114 -0
  96. package/template/.make-docs/system/references/planning-workflow.md +209 -0
  97. package/template/.make-docs/system/references/prd-change-management.md +165 -0
  98. package/template/{docs/assets → .make-docs/system}/references/wave-model.md +10 -8
  99. package/template/.make-docs/system/templates/AGENTS.md +12 -0
  100. package/template/.make-docs/system/templates/CLAUDE.md +12 -0
  101. package/template/.make-docs/system/templates/design.md +79 -0
  102. package/template/{docs/assets/templates/guide-developer.md → .make-docs/system/templates/guide-maintainer.md} +7 -3
  103. package/template/{docs/assets → .make-docs/system}/templates/guide-user.md +6 -2
  104. package/template/{docs/assets → .make-docs/system}/templates/history-record.md +6 -3
  105. package/template/.make-docs/system/templates/naive-uat-scenario.md +91 -0
  106. package/template/.make-docs/system/templates/performance-evidence-profile.md +252 -0
  107. package/template/.make-docs/system/templates/plan-overview.md +76 -0
  108. package/template/.make-docs/system/templates/plan-prd-change.md +155 -0
  109. package/template/{docs/assets → .make-docs/system}/templates/plan-prd-decompose.md +10 -0
  110. package/template/{docs/assets → .make-docs/system}/templates/plan-prd.md +28 -2
  111. package/template/{docs/assets → .make-docs/system}/templates/prd-architecture.md +13 -0
  112. package/template/.make-docs/system/templates/prd-glossary.md +28 -0
  113. package/template/.make-docs/system/templates/prd-index.md +70 -0
  114. package/template/{docs/assets → .make-docs/system}/templates/prd-overview.md +13 -0
  115. package/template/.make-docs/system/templates/prd-reference.md +30 -0
  116. package/template/{docs/assets → .make-docs/system}/templates/prd-risk-register.md +16 -1
  117. package/template/{docs/assets → .make-docs/system}/templates/prd-subsystem.md +15 -0
  118. package/template/.make-docs/system/templates/work-index.md +58 -0
  119. package/template/.make-docs/system/templates/work-phase.md +107 -0
  120. package/template/.make-docs/system-resources.catalog.json +91 -0
  121. package/template/.make-docs/system-resources.schema.json +204 -0
  122. package/template/AGENTS.md +8 -1
  123. package/template/CLAUDE.md +8 -1
  124. package/template/docs/AGENTS.codex-only.md +22 -0
  125. package/template/docs/AGENTS.md +21 -13
  126. package/template/docs/CLAUDE.claude-only.md +22 -0
  127. package/template/docs/CLAUDE.md +21 -13
  128. package/template/docs/assets/AGENTS.md +11 -7
  129. package/template/docs/assets/CLAUDE.md +11 -7
  130. package/template/docs/designs/AGENTS.md +8 -3
  131. package/template/docs/designs/CLAUDE.md +8 -3
  132. package/template/docs/plans/AGENTS.md +10 -3
  133. package/template/docs/plans/CLAUDE.md +10 -3
  134. package/template/docs/prd/AGENTS.md +14 -4
  135. package/template/docs/prd/CLAUDE.md +14 -4
  136. package/template/docs/work/AGENTS.md +10 -3
  137. package/template/docs/work/CLAUDE.md +10 -3
  138. package/dist/chunk-HP3HBG7F.js +0 -626
  139. package/dist/chunk-HP3HBG7F.js.map +0 -1
  140. package/dist/chunk-QRFH4J6H.js +0 -1194
  141. package/dist/chunk-QRFH4J6H.js.map +0 -1
  142. package/dist/chunk-WM3OXYTW.js +0 -2630
  143. package/dist/chunk-WM3OXYTW.js.map +0 -1
  144. package/dist/skills-command-3ESCZ75U.js.map +0 -1
  145. package/dist/uninstall-GQE4SJF2.js +0 -150
  146. package/dist/uninstall-GQE4SJF2.js.map +0 -1
  147. package/template/.make-docs/scripts/check_path_hygiene.py +0 -435
  148. package/template/docs/assets/archive/AGENTS.md +0 -20
  149. package/template/docs/assets/archive/CLAUDE.md +0 -20
  150. package/template/docs/assets/history/AGENTS.md +0 -12
  151. package/template/docs/assets/history/CLAUDE.md +0 -12
  152. package/template/docs/assets/prompts/AGENTS.md +0 -8
  153. package/template/docs/assets/prompts/CLAUDE.md +0 -8
  154. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +0 -14
  155. package/template/docs/assets/prompts/designs-to-plan.prompt.md +0 -10
  156. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +0 -27
  157. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +0 -8
  158. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +0 -6
  159. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +0 -10
  160. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +0 -6
  161. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +0 -6
  162. package/template/docs/assets/prompts/request-to-design.prompt.md +0 -16
  163. package/template/docs/assets/prompts/session-to-history-record.prompt.md +0 -19
  164. package/template/docs/assets/prompts/work-to-guides.prompt.md +0 -18
  165. package/template/docs/assets/references/AGENTS.md +0 -9
  166. package/template/docs/assets/references/CLAUDE.md +0 -9
  167. package/template/docs/assets/references/execution-workflow.md +0 -157
  168. package/template/docs/assets/references/output-contract.md +0 -221
  169. package/template/docs/assets/references/path-and-link-hygiene.md +0 -49
  170. package/template/docs/assets/references/planning-workflow.md +0 -160
  171. package/template/docs/assets/references/prd-change-management.md +0 -129
  172. package/template/docs/assets/templates/AGENTS.md +0 -8
  173. package/template/docs/assets/templates/CLAUDE.md +0 -8
  174. package/template/docs/assets/templates/design.md +0 -30
  175. package/template/docs/assets/templates/plan-overview.md +0 -32
  176. package/template/docs/assets/templates/plan-prd-change.md +0 -99
  177. package/template/docs/assets/templates/prd-change-addition.md +0 -45
  178. package/template/docs/assets/templates/prd-change-revision.md +0 -45
  179. package/template/docs/assets/templates/prd-glossary.md +0 -15
  180. package/template/docs/assets/templates/prd-index.md +0 -45
  181. package/template/docs/assets/templates/prd-reference.md +0 -17
  182. package/template/docs/assets/templates/work-index.md +0 -21
  183. package/template/docs/assets/templates/work-phase.md +0 -34
  184. package/template/docs/guides/AGENTS.md +0 -15
  185. package/template/docs/guides/CLAUDE.md +0 -15
  186. /package/template/{docs/assets → .make-docs/system}/prompts/update-readme-green-field.prompt.md +0 -0
  187. /package/template/{docs/assets → .make-docs/system}/references/harness-capability-matrix.md +0 -0
@@ -1,435 +0,0 @@
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:]))
@@ -1,20 +0,0 @@
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.
@@ -1,20 +0,0 @@
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.
@@ -1,12 +0,0 @@
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.
@@ -1,12 +0,0 @@
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.
@@ -1,8 +0,0 @@
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.
@@ -1,8 +0,0 @@
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.
@@ -1,14 +0,0 @@
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.
@@ -1,10 +0,0 @@
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.
@@ -1,27 +0,0 @@
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.
@@ -1,8 +0,0 @@
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.
@@ -1,6 +0,0 @@
1
- ___
2
- name: Plan to PRD (Green Field)
3
- description: Instructs the agent to generate a comprehensive set of PRD documents based from a specific plan document. Agent will automatically determine if parallel agents are needed, based on scope and complexity. If there are already requirements documents in `docs/prd`, they will be archived in a dated sub-folder (per agent instructions in `AGENTS.md` and `CLAUDE.md`).
4
- ___
5
-
6
- I think we're ready to create the PRD documents in `docs/prd`. Please be as detailed as possible. Follow the instructions, references, and templates provided to you in the `docs` directory (and appropriate child directories) on how to do this. The resulting PRD set should be a comprehensive design based on the details you captured in the {{PLAN DOC}} plan doc.
@@ -1,10 +0,0 @@
1
- ___
2
- name: PRD Change to Work Backlog
3
- description: Instructs the agent to generate a dated delta backlog from one or more PRD change docs and the baseline docs they affect.
4
- ___
5
-
6
- Please review these PRD change docs: {{CHANGE DOCS}}.
7
-
8
- Also review the baseline PRD docs they affect: {{AFFECTED PRD DOCS}}.
9
-
10
- Then generate a dated delta backlog in `docs/work/`. Follow the instructions, references, and templates in the `docs` directory, especially `docs/assets/references/prd-change-management.md`. The backlog should stay scoped to the requested change, remain dependency-ordered, and cite both the new change docs and the affected baseline docs in each phase's source-traceability section.
@@ -1,6 +0,0 @@
1
- ___
2
- name: PRD to Work Backlog (Full PRD Set)
3
- description: Instructs the agent to generate a work backlog document or set of documents from the full PRD.
4
- ___
5
-
6
- Please generate a work backlog based on what's in the PRD set (in `docs/prd/`). We will need a work backlog document or documents (in `docs/work/`) for a full implementation of all of the features. Follow the instructions, references, and templates provided to you in the `docs` directory (and appropriate child directories) on how to do this.
@@ -1,6 +0,0 @@
1
- ___
2
- name: PRD to Work (for Single PRD Feature)
3
- description: Instructs the agent to generate a work backlog document or set of documents for a single requirement document from the PRD set. Generally, a requirement document encapsulates a single feature or epic.
4
- ___
5
-
6
- Please review the requirement document {{REQUIREMENT DOC}} to understand the requirements for the specific epic or feature captured in that document. Then generate a document (or possibly documents) for our work backlog in `docs/work/`. Follow the instructions, references, and templates provided to you in the `docs` directory (and appropriate child directories) on how to do this.
@@ -1,16 +0,0 @@
1
- ___
2
- name: Request to Design
3
- description: Instructs the agent to turn a user request into a design doc by updating an existing related design or creating a new dated design doc.
4
- ___
5
-
6
- Please review the request below and then either generate or update a design doc for the request.
7
-
8
- Before writing anything, inspect `docs/designs/` for related design docs. If a related design clearly covers the same decision area, update it. Otherwise create a new dated design doc in `docs/designs/`.
9
-
10
- Follow the instructions, references, and templates in the `docs` directory, especially `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`.
11
-
12
- The resulting design doc should include an explicit `## Intended Follow-On` section with either `baseline-plan` or `change-plan` and the matching prompt link. Do not create a plan as part of this workflow.
13
-
14
- Here is the request:
15
-
16
- {{REQUEST}}