@tduyng/pi-devos 0.0.0-stage → 0.14.0

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 (109) hide show
  1. package/CHANGELOG.md +1421 -0
  2. package/LICENSE +201 -0
  3. package/README.md +206 -2
  4. package/package.json +44 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +155 -0
  7. package/plugins/devos/pi/extension/devos.ts +605 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +140 -0
  9. package/plugins/devos/scripts/evidence-router.py +254 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +285 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  13. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  14. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  15. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +104 -0
  16. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  17. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  18. package/plugins/devos/scripts/gates/plan-template-check.py +141 -0
  19. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  20. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +152 -0
  22. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  23. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  24. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  25. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  26. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  27. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  28. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  29. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  30. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  31. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  32. package/plugins/devos/scripts/gates/test-gates.sh +76 -0
  33. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  34. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  35. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  36. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  37. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  38. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  39. package/plugins/devos/skills/build/SKILL.md +71 -0
  40. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  41. package/plugins/devos/skills/build/references/defect.md +17 -0
  42. package/plugins/devos/skills/build/references/exposure.md +28 -0
  43. package/plugins/devos/skills/build/references/hard.md +39 -0
  44. package/plugins/devos/skills/build/references/refactor.md +66 -0
  45. package/plugins/devos/skills/build/references/routes.md +56 -0
  46. package/plugins/devos/skills/build/references/scale.md +84 -0
  47. package/plugins/devos/skills/build/references/spike.md +19 -0
  48. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  49. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  50. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  51. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  52. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  53. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  54. package/plugins/devos/skills/frame/SKILL.md +54 -0
  55. package/plugins/devos/skills/frame/references/template.md +115 -0
  56. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  57. package/plugins/devos/skills/implement/SKILL.md +36 -0
  58. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  59. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  60. package/plugins/devos/skills/implement/references/dod.md +37 -0
  61. package/plugins/devos/skills/implement/references/implement.md +54 -0
  62. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  63. package/plugins/devos/skills/implement/references/plan.md +142 -0
  64. package/plugins/devos/skills/implement/references/resume.md +9 -0
  65. package/plugins/devos/skills/implement/references/scale.md +86 -0
  66. package/plugins/devos/skills/implement/references/verify-close.md +62 -0
  67. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  68. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  69. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  70. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  71. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  72. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  73. package/plugins/devos/skills/implement/scripts/validate-spec.sh +220 -0
  74. package/plugins/devos/skills/init/SKILL.md +100 -0
  75. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  76. package/plugins/devos/skills/init/references/context.md +42 -0
  77. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  78. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  79. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  80. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  81. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  82. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  83. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  84. package/plugins/devos/skills/learn/SKILL.md +29 -0
  85. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  86. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  87. package/plugins/devos/skills/review/SKILL.md +54 -0
  88. package/plugins/devos/skills/review/references/comments.md +13 -0
  89. package/plugins/devos/skills/review/references/gaps.md +26 -0
  90. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  91. package/plugins/devos/skills/review/references/routing.md +35 -0
  92. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  93. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  94. package/plugins/devos/skills/spec/SKILL.md +57 -0
  95. package/plugins/devos/skills/spec/references/prototype.md +21 -0
  96. package/plugins/devos/skills/spec/references/question-craft.md +47 -0
  97. package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
  98. package/plugins/devos/skills/spec/references/write-spec.md +128 -0
  99. package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
  100. package/plugins/devos/skills/status/SKILL.md +67 -0
  101. package/plugins/devos/skills/status/references/cost.md +38 -0
  102. package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
  103. package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
  104. package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
  105. package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
  106. package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
  107. package/plugins/devos/skills/status/scripts/quality-correlation.sh +259 -0
  108. package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
  109. package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
@@ -0,0 +1,461 @@
1
+ #!/usr/bin/env python3
2
+ """detect-archetype: file-and-manifest archetype detection for init.
3
+
4
+ Deterministic, no model calls, no runtime dependencies beyond the standard
5
+ library. Prints one JSON object on stdout, or a markdown facts report with
6
+ --facts.
7
+
8
+ detect-archetype.py [--facts] [repo-dir]
9
+
10
+ The table below is deliberately long and deliberately dumb: one row per signal,
11
+ each a filename, a glob, a package.json key, or a text match. Adding a stack is
12
+ a one-line change and costs zero prompt tokens, which is why archetype breadth
13
+ is cheap here and a plugin per stack is not.
14
+
15
+ Rewritten in 0.8.4. The first version was ticked complete without being run
16
+ against a fixture, and three things were wrong at once: quoted globs
17
+ (`[[ -e '*.tf' ]]`) never expand, so Terraform, Sass, notebooks, C/C++, Nix
18
+ and Xcode were undetectable; every @scoped package was interpolated into a
19
+ JS property path (`p.devDependencies.@storybook/react`), a syntax error that
20
+ silently reported "absent", so Storybook, Radix, MUI, Chakra, Mantine, Redux,
21
+ Emotion, oclif, SvelteKit, Remix, Qwik, Angular, Headless UI and clack could
22
+ never be found; and the script was never invoked by init at all. Detection now
23
+ needs no node, so it works on repos that have none.
24
+
25
+ Why Python: the shell version ran `find . -maxdepth 4` once per glob row, so a
26
+ 112-row table meant up to 30 full tree walks, and a grep per package row. This
27
+ walks the tree once into a set of paths and basenames and reads package.json
28
+ once, so every row is a membership test or one regex over a string already in
29
+ memory. Sixty forks and 1.37s became zero forks.
30
+ """
31
+ from __future__ import annotations
32
+
33
+ import json
34
+ import os
35
+ import re
36
+ import sys
37
+ from pathlib import Path
38
+
39
+ # tag, kind, arg, arg2. kind: path | glob | pkg | grep (arg=regex, arg2=file)
40
+ TABLE = [('ui:react', 'pkg', 'react', ''), ('ui:vue', 'pkg', 'vue', ''), ('ui:svelte', 'pkg', 'svelte', ''), ('ui:solid', 'pkg', 'solid-js', ''), ('ui:angular', 'pkg', '@angular/core', ''), ('ui:next', 'pkg', 'next', ''), ('ui:nuxt', 'pkg', 'nuxt', ''), ('ui:sveltekit', 'pkg', '@sveltejs/kit', ''), ('ui:remix', 'pkg', '@remix-run/react', ''), ('ui:astro', 'pkg', 'astro', ''), ('ui:qwik', 'pkg', '@builder.io/qwik', ''), ('design:storybook', 'pkg', 'storybook', ''), ('design:storybook', 'path', '.storybook', ''), ('design:shadcn', 'path', 'components.json', ''), ('design:radix', 'pkg', '@radix-ui/react-dialog', ''), ('design:radix', 'pkg', '@radix-ui/react-dropdown-menu', ''), ('design:headless-ui', 'pkg', '@headlessui/react', ''), ('design:headless-ui', 'pkg', '@headlessui/vue', ''), ('design:mui', 'pkg', '@mui/material', ''), ('design:chakra', 'pkg', '@chakra-ui/react', ''), ('design:antd', 'pkg', 'antd', ''), ('design:mantine', 'pkg', '@mantine/core', ''), ('style:tailwind', 'pkg', 'tailwindcss', ''), ('style:tailwind', 'glob', 'tailwind.config.*', ''), ('style:css-modules', 'glob', '*.module.css', ''), ('style:css-modules', 'glob', '*.module.scss', ''), ('style:styled-components', 'pkg', 'styled-components', ''), ('style:emotion', 'pkg', '@emotion/react', ''), ('style:panda', 'glob', 'panda.config.*', ''), ('style:vanilla-extract', 'pkg', '@vanilla-extract/css', ''), ('style:sass', 'glob', '*.scss', ''), ('style:sass', 'glob', '*.sass', ''), ('state:redux', 'pkg', '@reduxjs/toolkit', ''), ('state:redux', 'pkg', 'react-redux', ''), ('state:zustand', 'pkg', 'zustand', ''), ('state:jotai', 'pkg', 'jotai', ''), ('state:xstate', 'pkg', 'xstate', ''), ('state:pinia', 'pkg', 'pinia', ''), ('state:mobx', 'pkg', 'mobx', ''), ('state:signals', 'pkg', '@preact/signals', ''), ('mobile:react-native', 'pkg', 'react-native', ''), ('mobile:expo', 'pkg', 'expo', ''), ('mobile:flutter', 'grep', 'flutter', 'pubspec.yaml'), ('mobile:swift', 'glob', '*.xcodeproj', ''), ('mobile:swift', 'glob', '*.xcworkspace', ''), ('mobile:swift', 'path', 'Package.swift', ''), ('mobile:kotlin-compose', 'grep', 'android', 'build.gradle.kts'), ('mobile:kotlin-compose', 'grep', 'android', 'build.gradle'), ('mobile:capacitor', 'glob', 'capacitor.config.*', ''), ('mobile:tauri', 'path', 'src-tauri', ''), ('cli:commander', 'pkg', 'commander', ''), ('cli:commander', 'pkg', 'yargs', ''), ('cli:oclif', 'pkg', '@oclif/core', ''), ('cli:clack', 'pkg', '@clack/prompts', ''), ('cli:ink', 'pkg', 'ink', ''), ('cli:go', 'path', 'go.mod', ''), ('cli:cargo', 'grep', '\\[\\[bin\\]\\]', 'Cargo.toml'), ('cli:python', 'grep', 'click', 'pyproject.toml'), ('cli:python', 'grep', 'typer', 'pyproject.toml'), ('cli:cobra', 'grep', 'spf13/cobra', 'go.mod'), ('data:dbt', 'path', 'dbt_project.yml', ''), ('data:airflow', 'path', 'dags', ''), ('data:airflow', 'path', 'airflow.cfg', ''), ('data:dagster', 'path', 'dagster.yaml', ''), ('data:notebooks', 'glob', '*.ipynb', ''), ('data:spark', 'grep', 'pyspark', 'requirements.txt'), ('data:pytorch', 'grep', 'torch', 'requirements.txt'), ('data:pytorch', 'grep', 'torch', 'pyproject.toml'), ('data:sklearn', 'grep', 'scikit-learn', 'requirements.txt'), ('data:mlflow', 'grep', 'mlflow', 'requirements.txt'), ('container:docker', 'path', 'Dockerfile', ''), ('container:compose', 'glob', 'docker-compose*.y*ml', ''), ('container:compose', 'glob', 'compose.y*ml', ''), ('container:podman', 'path', 'Containerfile', ''), ('container:devcontainer', 'path', '.devcontainer/devcontainer.json', ''), ('container:skaffold', 'path', 'skaffold.yaml', ''), ('container:tilt', 'path', 'Tiltfile', ''), ('monorepo:go-work', 'path', 'go.work', ''), ('monorepo:rush', 'path', 'rush.json', ''), ('monorepo:moon', 'path', '.moon/workspace.yml', ''), ('ci:gitlab', 'path', '.gitlab-ci.yml', ''), ('ci:github-actions', 'glob', '.github/workflows/*.y*ml', ''), ('ci:jenkins', 'path', 'Jenkinsfile', ''), ('ci:circleci', 'path', '.circleci/config.yml', ''), ('ci:azure-pipelines', 'path', 'azure-pipelines.yml', ''), ('ci:drone', 'path', '.drone.yml', ''), ('infra:terraform', 'glob', '*.tf', ''), ('infra:terraform', 'glob', '*.tfvars', ''), ('infra:pulumi', 'path', 'Pulumi.yaml', ''), ('infra:cdk', 'path', 'cdk.json', ''), ('infra:helm', 'path', 'Chart.yaml', ''), ('infra:kustomize', 'glob', 'kustomization.y*ml', ''), ('infra:ansible', 'glob', 'playbook*.y*ml', ''), ('infra:nix', 'glob', '*.nix', ''), ('systems:cargo', 'path', 'Cargo.toml', ''), ('systems:cmake', 'path', 'CMakeLists.txt', ''), ('systems:make', 'path', 'Makefile', ''), ('systems:make', 'path', 'GNUmakefile', ''), ('systems:zephyr', 'path', 'prj.conf', ''), ('systems:platformio', 'path', 'platformio.ini', ''), ('systems:c-cpp', 'glob', '*.c', ''), ('systems:c-cpp', 'glob', '*.cpp', ''), ('monorepo:workspace', 'pkg', 'workspaces', ''), ('monorepo:workspace', 'path', 'pnpm-workspace.yaml', ''), ('monorepo:workspace', 'path', 'lerna.json', ''), ('monorepo:nx', 'path', 'nx.json', ''), ('monorepo:turborepo', 'path', 'turbo.json', ''), ('monorepo:bazel', 'path', 'WORKSPACE', ''), ('monorepo:bazel', 'path', 'MODULE.bazel', ''), ('monorepo:cargo-workspace', 'grep', '\\[workspace\\]', 'Cargo.toml'), ('monorepo:gradle', 'grep', '^include', 'settings.gradle.kts'), ('monorepo:gradle', 'grep', '^include', 'settings.gradle')]
41
+
42
+ PRUNE = {"node_modules", ".git", "vendor", "target", "dist", "build",
43
+ ".venv", "venv"}
44
+ MAX_DEPTH = 4
45
+ DEP_OBJECTS = ("dependencies", "devDependencies", "peerDependencies",
46
+ "optionalDependencies", "scripts")
47
+ # The four dependency maps. A scripts entry is an equally good signal, and
48
+ # p_pkg counts it, but a version must never be read out of a script command.
49
+ DEP_MAPS = DEP_OBJECTS[:4]
50
+ PREVIEW = re.compile(r"^(dev|start|serve|preview)([:-][A-Za-z0-9:_-]+)?$")
51
+
52
+
53
+ class Repo:
54
+ """One tree walk, then every signal row is a test against it."""
55
+
56
+ def __init__(self, root: Path) -> None:
57
+ self.root = root
58
+ self.paths: set[str] = set()
59
+ self.names: set[str] = set()
60
+ self._walk()
61
+ self._pkg_text: str | None = None
62
+ self._pairs: list[tuple[str, str, str]] | None = None
63
+
64
+ def _walk(self) -> None:
65
+ for dirpath, dirnames, filenames in os.walk(self.root):
66
+ rel_dir = Path(dirpath).relative_to(self.root)
67
+ depth = len(rel_dir.parts)
68
+ if depth >= MAX_DEPTH:
69
+ dirnames[:] = []
70
+ else:
71
+ dirnames[:] = sorted(
72
+ d for d in dirnames if d not in PRUNE)
73
+ # find . prints every path with a leading ./, and that prefix is
74
+ # load-bearing: a -path pattern of */dir/* needs the slash before
75
+ # the directory name to have anything to match in front of it.
76
+ rel = "" if str(rel_dir) == "." else str(rel_dir)
77
+ for n in filenames:
78
+ self.names.add(n)
79
+ self.paths.add(f"./{rel}/{n}" if rel else f"./{n}")
80
+ for d in dirnames:
81
+ self.names.add(d)
82
+ self.paths.add(f"./{rel}/{d}" if rel else f"./{d}")
83
+
84
+ def p_path(self, arg: str) -> bool:
85
+ return (self.root / arg).exists()
86
+
87
+ def p_glob(self, arg: str) -> bool:
88
+ """A basename glob, or a path glob, matched to a bounded depth.
89
+
90
+ A pattern carrying a directory cannot go through -name: that matches a
91
+ basename, so `.github/workflows/*.y*ml` compared the whole path against
92
+ a basename pattern, matched nothing for any repository, and the one CI
93
+ signal in the table was undetectable. -path matches the path relative
94
+ to the search root, which is what those rows mean.
95
+ """
96
+ if "/" in arg:
97
+ # find was given -path "*/$1", so the pattern is anchored to any
98
+ # depth. Without the prefix a nested .github/workflows/ci.yml never
99
+ # matches, which is the one CI signal the table exists to catch.
100
+ return any(fnmatch_rel(p, "*/" + arg) for p in self.paths)
101
+ return any(fnmatch_rel(n, arg) for n in self.names)
102
+
103
+ def pkg_text(self) -> str:
104
+ if self._pkg_text is None:
105
+ f = self.root / "package.json"
106
+ try:
107
+ self._pkg_text = f.read_text(errors="replace")
108
+ except OSError:
109
+ self._pkg_text = ""
110
+ return self._pkg_text
111
+
112
+ def p_pkg(self, arg: str) -> bool:
113
+ """A key exists in package.json, matched as a JSON key ("name":).
114
+
115
+ This deliberately does not distinguish dependencies from
116
+ devDependencies: every call site checked both anyway, and a scripts
117
+ entry is an equally good signal.
118
+ """
119
+ if not (self.root / "package.json").is_file():
120
+ return False
121
+ return bool(re.search(rf'"{re.escape(arg)}"\s*:', self.pkg_text()))
122
+
123
+ def read(self, rel: str) -> str | None:
124
+ f = self.root / rel
125
+ if not f.is_file():
126
+ return None
127
+ try:
128
+ return f.read_text(errors="replace")
129
+ except OSError:
130
+ return None
131
+
132
+ def p_grep(self, regex: str, rel: str) -> bool:
133
+ text = self.read(rel)
134
+ return text is not None and bool(re.search(regex, text))
135
+
136
+ def pairs(self) -> list[tuple[str, str, str]]:
137
+ """(object, key, value) for the four dependency maps and scripts.
138
+
139
+ Scoping by object is what makes both consumers correct: p_pkg counts a
140
+ scripts entry as a signal, so an unscoped search for a version finds
141
+ `"storybook": "storybook dev"` and reports a shell command as a
142
+ version. The shell did this in awk with a hand-rolled brace walker that
143
+ also survived a truncated file; json.loads is used when it can be, and
144
+ the same brace walk is the fallback so a malformed manifest does not
145
+ silently change the answer.
146
+ """
147
+ if self._pairs is not None:
148
+ return self._pairs
149
+ text = self.pkg_text()
150
+ if not text:
151
+ self._pairs = []
152
+ return self._pairs
153
+ try:
154
+ doc = json.loads(text)
155
+ out = []
156
+ if isinstance(doc, dict):
157
+ for obj in DEP_OBJECTS:
158
+ block = doc.get(obj)
159
+ if isinstance(block, dict):
160
+ for k, v in block.items():
161
+ if isinstance(v, str):
162
+ out.append((obj, k, v))
163
+ self._pairs = out
164
+ return out
165
+ except ValueError:
166
+ self._pairs = brace_scan(text)
167
+ return self._pairs
168
+
169
+
170
+ def fnmatch_rel(name: str, pattern: str) -> bool:
171
+ """POSIX shell glob on one path component sequence.
172
+
173
+ find's -name and -path both take shell globs where * does not cross a /,
174
+ so a pattern with a slash is matched component by component.
175
+ """
176
+ import fnmatch
177
+ return fnmatch.fnmatchcase(name, pattern)
178
+
179
+
180
+ def brace_scan(text: str) -> list[tuple[str, str, str]]:
181
+ """Brace walker for a package.json json.loads could not read.
182
+
183
+ Deliberately the same shape as the awk it replaces: locate one of the
184
+ dependency objects, take pairs out of its body, and stop at the closing
185
+ brace of that object. A truncated file yields the pairs before the cut,
186
+ which is what the awk did and what a partially written manifest deserves.
187
+ """
188
+ out: list[tuple[str, str, str]] = []
189
+ for m in re.finditer(r'"(' + "|".join(DEP_OBJECTS) + r')"\s*:\s*\{', text):
190
+ obj = m.group(1)
191
+ i = m.end()
192
+ depth = 1
193
+ body_start = i
194
+ while i < len(text) and depth:
195
+ c = text[i]
196
+ if c == "{":
197
+ depth += 1
198
+ elif c == "}":
199
+ depth -= 1
200
+ if depth == 0:
201
+ break
202
+ i += 1
203
+ body = text[body_start:i]
204
+ for pair in re.finditer(r'"([^"]+)"\s*:\s*"([^"]*)"', body):
205
+ out.append((obj, pair.group(1), pair.group(2)))
206
+ return out
207
+
208
+
209
+ CHECK_VERBS = re.compile(
210
+ r"^(tests?|typecheck|types|tsc|lint|format|fmt|checks?|validate|verify|audit"
211
+ r"|coverage|cov|unit|func|functional|integration|e2e|a11y|accessibility|smoke"
212
+ r"|perf|bench|build|storybook|spell)([:._-][A-Za-z0-9:._-]+)?$")
213
+ # Language/toolchain pins: one regex each, same rule as the shell version.
214
+ LANGS = [
215
+ ("go (toolchain)", "go.mod", r"^go\s+[0-9]", r"^go\s+([0-9.]+).*"),
216
+ ("rust (toolchain)", "Cargo.toml", r"^rust-version", r'.*"([^"]+)".*'),
217
+ ("python", "pyproject.toml", r"^requires-python", r'.*"([^"]+)".*'),
218
+ ("node (engine)", ".nvmrc", ".", r"[\s]*(.+[^\s]).*"),
219
+ ]
220
+ COMPOSE_FILES = ("docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml")
221
+ JUSTFILES = ("justfile", "Justfile", ".justfile")
222
+ MAKEFILES = ("Makefile", "GNUmakefile", "makefile")
223
+ # Recipe name at column 0, which is what both just and make use for a recipe
224
+ # and never for a variable assignment or a body line. just's parameterised
225
+ # `verify target="x":` is covered by the optional argument group.
226
+ RECIPE = re.compile(r"^([A-Za-z_][A-Za-z0-9_.-]*)([ \t][^:]*)?:")
227
+
228
+
229
+ def evaluate(repo: "Repo") -> tuple[list[str], list[str]]:
230
+ """The signal table, in order. First row per tag wins, on purpose."""
231
+ found: list[str] = []
232
+ pkgs: list[str] = []
233
+ seen: set[str] = set()
234
+ for tag, kind, arg, arg2 in TABLE:
235
+ if not tag or tag in seen:
236
+ continue
237
+ if kind == "path":
238
+ hit = repo.p_path(arg)
239
+ elif kind == "glob":
240
+ hit = repo.p_glob(arg)
241
+ elif kind == "pkg":
242
+ hit = repo.p_pkg(arg)
243
+ elif kind == "grep":
244
+ hit = repo.p_grep(arg, arg2)
245
+ else:
246
+ continue
247
+ if not hit:
248
+ continue
249
+ seen.add(tag)
250
+ found.append(tag)
251
+ # The package name behind a pkg-kind hit is the only thing worth
252
+ # resolving a version for; path/glob/grep signals name no package.
253
+ if kind == "pkg":
254
+ pkgs.append(arg)
255
+ return found, pkgs
256
+
257
+
258
+ def version_rows(repo: "Repo", pkgs: list[str]) -> list[str]:
259
+ rows: list[str] = []
260
+ pairs = repo.pairs()
261
+ for p in pkgs:
262
+ v = src = ""
263
+ installed = repo.root / "node_modules" / p / "package.json"
264
+ text = repo.read(str(installed.relative_to(repo.root))) if installed.is_file() else None
265
+ if text:
266
+ m = re.search(r'"version"\s*:\s*"([^"]+)"', text)
267
+ if m:
268
+ v, src = m.group(1), "node_modules (installed)"
269
+ if not v:
270
+ for obj, k, val in pairs:
271
+ if obj in DEP_MAPS and k == p:
272
+ v, src = val, "package.json (range, NOT resolved)"
273
+ break
274
+ # No version either way means the hit was a manifest key or a script
275
+ # name, not a dependency. Nothing to state, so state nothing.
276
+ if v:
277
+ rows.append(f"| {p} | {v} | {src} |")
278
+ for label, fname, find_re, sub in LANGS:
279
+ text = repo.read(fname)
280
+ if not text:
281
+ continue
282
+ line = next((l for l in text.splitlines() if re.search(find_re, l)), None)
283
+ if line is None:
284
+ continue
285
+ g = re.search(sub, line)
286
+ if g:
287
+ rows.append(f"| {label} | {g.group(1)} | {fname} |")
288
+ return rows
289
+
290
+
291
+ def declared_checks(repo: "Repo") -> list[str]:
292
+ """The project's own statement of what proves it works.
293
+
294
+ A key the project defines is a check the verifier can run; the name filter
295
+ only keeps the ones that prove something (a `dev` script starts a server, it
296
+ does not pass or fail, and `deploy-prod` is not a check).
297
+
298
+ The verb list is wide on purpose. init copies this table into
299
+ conventions.md "verbatim and without triage" precisely so no one decides
300
+ which of a project's checks are the important ones, and a narrow list makes
301
+ that decision here instead, invisibly.
302
+ """
303
+ # The lockfile names the runner. conventions.md copies this table verbatim
304
+ # and the verifier runs what it says, so `npm run` on a pnpm repo is a
305
+ # command the project does not use. Bun writes bun.lock, the text lockfile
306
+ # that has been its default since v1.2, so both spellings count: a repo
307
+ # pinned to the old binary format still has bun.lockb and nothing else.
308
+ pm = "npm run"
309
+ if repo.p_path("pnpm-lock.yaml"):
310
+ pm = "pnpm"
311
+ if repo.p_path("yarn.lock"):
312
+ pm = "yarn"
313
+ if repo.p_path("bun.lock") or repo.p_path("bun.lockb"):
314
+ pm = "bun run"
315
+
316
+ out: list[str] = []
317
+ for obj, k, v in repo.pairs():
318
+ if obj == "scripts" and CHECK_VERBS.match(k) and "watch" not in k:
319
+ out.append(f"| package.json | `{pm} {k}` | {v} |")
320
+ # A task runner is a manifest too. Reading only package.json reports "no
321
+ # declared checks" for every Make/just/Task project, including this one:
322
+ # DevOS's own quality gate is `just verify` and its own script could not see
323
+ # it. First spelling that exists wins: darwin's filesystem is
324
+ # case-insensitive, so `justfile` and `Justfile` are one file and listing
325
+ # both reports every recipe twice.
326
+ for group, runner in ((JUSTFILES, "just"), (MAKEFILES, "make")):
327
+ for fname in group:
328
+ text = repo.read(fname)
329
+ if text is None:
330
+ continue
331
+ seen: set[str] = set()
332
+ for line in text.splitlines():
333
+ m = RECIPE.match(line)
334
+ if not m:
335
+ continue
336
+ name = m.group(1)
337
+ if name.startswith(".") or not CHECK_VERBS.match(name) or name in seen:
338
+ continue
339
+ seen.add(name)
340
+ out.append(f"| {fname} | `{runner} {name}` | (recipe) |")
341
+ break
342
+ return [r for r in out if r.strip()]
343
+
344
+
345
+ def compose_services(repo: "Repo") -> tuple[str, list[str]]:
346
+ for cf in COMPOSE_FILES:
347
+ text = repo.read(cf)
348
+ if text is None:
349
+ continue
350
+ svcs: list[str] = []
351
+ in_services = False
352
+ for line in text.splitlines():
353
+ if re.match(r"^services:\s*$", line):
354
+ in_services = True
355
+ continue
356
+ if re.match(r"^[A-Za-z_]", line):
357
+ in_services = False
358
+ # Service names are the keys indented exactly one level under
359
+ # `services:`.
360
+ if in_services:
361
+ m = re.match(r"^ ([A-Za-z0-9_.-]+):\s*$", line)
362
+ if m:
363
+ svcs.append(m.group(1))
364
+ return cf, svcs
365
+ return "", []
366
+
367
+
368
+ def facts(repo: "Repo", found: list[str], pkgs: list[str]) -> None:
369
+ """Detection answers *what*; this answers *which*.
370
+
371
+ The difference is the whole point: a version supplied from training recall
372
+ carries no marker saying so. Output is markdown because both consumers
373
+ paste it, the plan embeds the version table into the capsule and init writes
374
+ it into codebase-map.md.
375
+ """
376
+ print("### Stack facts")
377
+ print()
378
+ print("""<!-- detect-archetype.py --facts: read from disk, never recalled -->""")
379
+ print()
380
+ print(f"Archetypes: {','.join(found) if found else 'none detected'}")
381
+ print()
382
+
383
+ rows = version_rows(repo, pkgs)
384
+ if rows:
385
+ print("| Package | Version | Source |")
386
+ print("|---|---|---|")
387
+ for r in rows:
388
+ print(r)
389
+ else:
390
+ print("""No resolvable versions found (no manifest, or nothing installed and no ranges declared).""")
391
+ print()
392
+
393
+ checks = declared_checks(repo)
394
+ if checks:
395
+ print("""Declared checks (every one gets run and reported by name):""")
396
+ print()
397
+ print("| Source | Command | Runs |")
398
+ print("|---|---|---|")
399
+ for c in checks:
400
+ print(c)
401
+ else:
402
+ print("""Declared checks: none found in package.json, justfile or Makefile (ask the project what proves it works).""")
403
+
404
+ # Where a command runs is part of the command. A suite that only passes
405
+ # inside the app container fails on the host for reasons that have nothing
406
+ # to do with the code, and a verifier reporting that as a failure blames the
407
+ # diff for the environment.
408
+ compose_file, svcs = compose_services(repo)
409
+ if compose_file:
410
+ if svcs:
411
+ print("Execution context: " + compose_file + " defines services "
412
+ + ", ".join(svcs) + ". " + """A check that only passes inside one of them is recorded in conventions.md with the wrapper it needs (`docker compose exec <service> <command>`), never as the bare command.""")
413
+ else:
414
+ print("""Execution context: $compose_file present. Record for each check whether it runs on the host or inside a service.""")
415
+ elif repo.p_path(".devcontainer/devcontainer.json"):
416
+ print("""Execution context: a devcontainer is declared. Record whether the checks assume it, so a host run that fails for a missing toolchain is not read as a failing test.""")
417
+ print()
418
+
419
+ # Preview candidates: the scripts that start the thing so a human or a
420
+ # browser tool can look at it. Excluded from the checks table above on
421
+ # purpose (a dev server never exits, so it can never pass), and needed here
422
+ # for exactly the same reason, looking at it is the only check that sees a
423
+ # layout.
424
+ preview = [f"`{k}` (`{v}`)"
425
+ for obj, k, v in repo.pairs() if obj == "scripts" and PREVIEW.match(k)]
426
+ if preview:
427
+ print("Preview candidates: " + ", ".join(preview) + " — pick the "
428
+ "one that serves the app and record it with its URL as "
429
+ "`Preview command` in conventions.md.")
430
+ else:
431
+ print("Preview candidates: none found. If this project has a UI, ask "
432
+ "what starts it; if it has none, record `Preview command: none`.")
433
+
434
+
435
+ def main(argv: list[str]) -> int:
436
+ want_facts = False
437
+ repo_dir = "."
438
+ for a in argv:
439
+ if a == "--facts":
440
+ want_facts = True
441
+ else:
442
+ repo_dir = a
443
+ root = Path(repo_dir)
444
+ if not root.is_dir():
445
+ print(f"FAIL detect-archetype: no such directory: {repo_dir}", file=sys.stderr)
446
+ return 1
447
+ repo = Repo(root)
448
+ found, pkgs = evaluate(repo)
449
+ if want_facts:
450
+ facts(repo, found, pkgs)
451
+ return 0
452
+ if not found:
453
+ print('{"archetypes":[],"detected":false}')
454
+ return 0
455
+ joined = ",".join(f'"{a}"' for a in found)
456
+ print(f'{{"archetypes":[{joined}],"detected":true}}')
457
+ return 0
458
+
459
+
460
+ if __name__ == "__main__":
461
+ sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,114 @@
1
+ #!/usr/bin/env python3
2
+ """render-rule: canonical rule files into every other tool's native surface.
3
+
4
+ render-rule.py <canonical-rule.md> [more files or directories...]
5
+ render-rule.py devos/standards/rules/<NN>-<category>/<slug>.md [...]
6
+
7
+ Renders canonical rule files (Claude Code's own globs-frontmatter format, see
8
+ references/rule-format.md) into every other tool's native rules surface, for
9
+ whichever tools are actually installed in the current project (rule 21/22).
10
+ Zero model calls. A directory argument expands to its *.md files, which is how
11
+ a preset pack applies in one command.
12
+
13
+ Detected by directory presence, same convention as the framework's own install
14
+ scripts: .github/ -> Copilot CLI. Codex, OpenCode and Pi have no native rules
15
+ surface; nothing is written for them here, init folds the rule into AGENTS.md
16
+ instead.
17
+
18
+ Exit 0 = rendered (or nothing to render), 1 = malformed input, 2 = usage.
19
+
20
+ Why Python: the shell version read each rule through cat, three awk passes and
21
+ four grep/sed/cut calls, roughly a dozen processes and a subshell each, to
22
+ split one file on its frontmatter fences. A twenty-rule preset pack paid that
23
+ two hundred and forty times. This reads the file once.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import re
28
+ import sys
29
+ from pathlib import Path
30
+
31
+ FENCE = "---"
32
+ SUPERSEDED = re.compile(r"^superseded-by:[ \t]*(.*)$", re.M)
33
+ GLOBS = re.compile(r"^globs:[ \t]*(.*)$", re.M)
34
+
35
+ NO_COPILOT = ("render-rule: no Copilot install detected here; nothing to render "
36
+ "(Codex/OpenCode/Pi fold rules into AGENTS.md via init instead).")
37
+
38
+
39
+ def render_one(src: Path) -> int:
40
+ if not src.is_file():
41
+ print(f"FAIL render-rule: canonical rule file not found: '{src}'", file=sys.stderr)
42
+ print(" fix: pass a devos/standards/rules/<NN>-<category>/<slug>.md path",
43
+ file=sys.stderr)
44
+ return 2
45
+
46
+ slug = src.stem
47
+ category_dir = src.parent.name
48
+ content = src.read_text()
49
+
50
+ if not content.startswith(FENCE + "\n"):
51
+ print(f"FAIL render-rule: '{src}' has no frontmatter", file=sys.stderr)
52
+ return 1
53
+
54
+ # The opener alone is not frontmatter. Without a closing fence the body
55
+ # comes out empty and the tool would write a frontmatter-only instruction
56
+ # file that drops the rule text.
57
+ lines = content.split("\n")
58
+ close = next((i for i, l in enumerate(lines[1:], 1) if l == FENCE), None)
59
+ if close is None:
60
+ print(f"FAIL render-rule: '{src}' has an unterminated frontmatter block "
61
+ f"(no closing ---)", file=sys.stderr)
62
+ return 1
63
+
64
+ fm = "\n".join(lines[1:close])
65
+ sup = SUPERSEDED.search(fm)
66
+ if sup:
67
+ print(f"skip {src}: superseded ({sup.group(1).strip()}) - kept as audit "
68
+ f"trail, no longer enforced")
69
+ return 0
70
+ # Everything after the second fence, trailing blank lines dropped so the
71
+ # write below controls its own ending. Fence lines inside the body are kept:
72
+ # the shell's awk had `next` on /^---$/ and so silently dropped a markdown
73
+ # horizontal rule from the rendered instruction file.
74
+ body = "\n".join(lines[close + 1:]).rstrip("\n")
75
+
76
+ m = GLOBS.search(fm)
77
+ apply_to = m.group(1).replace(" ", "") if m else "**"
78
+
79
+ if not Path(".github").is_dir():
80
+ print(NO_COPILOT)
81
+ return 0
82
+
83
+ out = Path(".github/instructions") / f"{category_dir.split('-', 1)[-1]}-{slug}.instructions.md"
84
+ out.parent.mkdir(parents=True, exist_ok=True)
85
+ out.write_text(f'---\napplyTo: "{apply_to}"\n---\n\n{body}\n')
86
+ print(f"wrote {out}")
87
+ return 0
88
+
89
+
90
+ def main(argv: list[str]) -> int:
91
+ if not argv:
92
+ print("usage: render-rule.py <rule.md> [more.md|dir ...]", file=sys.stderr)
93
+ return 2
94
+
95
+ rc_total = 0
96
+ for arg in argv:
97
+ p = Path(arg)
98
+ if p.is_dir():
99
+ members = sorted((f for f in p.rglob("*.md") if f.is_file()),
100
+ key=lambda f: str(f))
101
+ for f in members:
102
+ # A malformed file reports itself; everything else in the pack
103
+ # still renders, so a directory member never propagates 2.
104
+ if render_one(f) != 0:
105
+ rc_total = 1
106
+ else:
107
+ rc = render_one(p)
108
+ if rc != 0:
109
+ rc_total = rc
110
+ return rc_total
111
+
112
+
113
+ if __name__ == "__main__":
114
+ sys.exit(main(sys.argv[1:]))