@tduyng/pi-devos 0.0.0-stage → 0.13.6

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 (138) hide show
  1. package/CHANGELOG.md +1398 -0
  2. package/LICENSE +201 -0
  3. package/README.md +213 -2
  4. package/package.json +45 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +181 -0
  7. package/plugins/devos/pi/extension/devos.ts +615 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +134 -0
  9. package/plugins/devos/scripts/evidence-router.py +252 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +283 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-handoff.sh +215 -0
  13. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  14. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  15. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  16. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +102 -0
  17. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  18. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  19. package/plugins/devos/scripts/gates/plan-template-check.py +147 -0
  20. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +165 -0
  22. package/plugins/devos/scripts/gates/test-gates.sh +4306 -0
  23. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  24. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  25. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  26. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  27. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  28. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  29. package/plugins/devos/skills/build/SKILL.md +71 -0
  30. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  31. package/plugins/devos/skills/build/references/defect.md +17 -0
  32. package/plugins/devos/skills/build/references/exposure.md +28 -0
  33. package/plugins/devos/skills/build/references/hard.md +39 -0
  34. package/plugins/devos/skills/build/references/refactor.md +66 -0
  35. package/plugins/devos/skills/build/references/routes.md +56 -0
  36. package/plugins/devos/skills/build/references/scale.md +84 -0
  37. package/plugins/devos/skills/build/references/spike.md +19 -0
  38. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  39. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  40. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  41. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  42. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  43. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  44. package/plugins/devos/skills/design-taste/SKILL.md +55 -0
  45. package/plugins/devos/skills/design-taste/references/tells.md +85 -0
  46. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +305 -0
  47. package/plugins/devos/skills/docs/SKILL.md +22 -0
  48. package/plugins/devos/skills/docs/references/backfill.md +54 -0
  49. package/plugins/devos/skills/docs/references/init.md +43 -0
  50. package/plugins/devos/skills/docs/references/status.md +71 -0
  51. package/plugins/devos/skills/docs/references/update.md +80 -0
  52. package/plugins/devos/skills/explain/SKILL.md +45 -0
  53. package/plugins/devos/skills/explain/references/quiz.md +21 -0
  54. package/plugins/devos/skills/frame/SKILL.md +71 -0
  55. package/plugins/devos/skills/frame/references/boundaries.md +53 -0
  56. package/plugins/devos/skills/frame/references/decompose.md +96 -0
  57. package/plugins/devos/skills/frame/references/impact.md +43 -0
  58. package/plugins/devos/skills/frame/references/interrogate.md +68 -0
  59. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  60. package/plugins/devos/skills/implement/SKILL.md +36 -0
  61. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  62. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  63. package/plugins/devos/skills/implement/references/dod.md +32 -0
  64. package/plugins/devos/skills/implement/references/implement.md +52 -0
  65. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  66. package/plugins/devos/skills/implement/references/plan.md +160 -0
  67. package/plugins/devos/skills/implement/references/resume.md +9 -0
  68. package/plugins/devos/skills/implement/references/scale.md +86 -0
  69. package/plugins/devos/skills/implement/references/verify-close.md +61 -0
  70. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  71. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  72. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  73. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  74. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  75. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  76. package/plugins/devos/skills/implement/scripts/validate-spec.sh +268 -0
  77. package/plugins/devos/skills/init/SKILL.md +100 -0
  78. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  79. package/plugins/devos/skills/init/references/context.md +42 -0
  80. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  81. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  82. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  83. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  84. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  85. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  86. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  87. package/plugins/devos/skills/learn/SKILL.md +29 -0
  88. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  89. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  90. package/plugins/devos/skills/product/SKILL.md +40 -0
  91. package/plugins/devos/skills/product/references/planner.md +54 -0
  92. package/plugins/devos/skills/review/SKILL.md +77 -0
  93. package/plugins/devos/skills/review/references/gaps.md +26 -0
  94. package/plugins/devos/skills/spec/SKILL.md +58 -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 +143 -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 +282 -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
  110. package/plugins/devos/skills/surgical-diff/SKILL.md +23 -0
  111. package/plugins/devos/skills/test-integrity/SKILL.md +26 -0
  112. package/plugins/devos/skills/verification-evidence/SKILL.md +17 -0
  113. package/plugins/devos/workflows/common/backlog-file-structure.md +44 -0
  114. package/plugins/devos/workflows/common/category-file-structure.md +41 -0
  115. package/plugins/devos/workflows/common/feature-line-format.md +10 -0
  116. package/plugins/devos/workflows/common/roadmap-file-structure.md +51 -0
  117. package/plugins/devos/workflows/common/suggest-categories.md +76 -0
  118. package/plugins/devos/workflows/common/suggest-milestones.md +92 -0
  119. package/plugins/devos/workflows/doc/doc-health.md +137 -0
  120. package/plugins/devos/workflows/doc/doc-writer.md +44 -0
  121. package/plugins/devos/workflows/doc/init-documentation.md +196 -0
  122. package/plugins/devos/workflows/doc/retro-documentation.md +304 -0
  123. package/plugins/devos/workflows/doc/templates/library.md +58 -0
  124. package/plugins/devos/workflows/doc/templates/service.md +61 -0
  125. package/plugins/devos/workflows/doc/update-documentation.md +194 -0
  126. package/plugins/devos/workflows/doc/write-documentation.md +137 -0
  127. package/plugins/devos/workflows/product/create-product-mission.md +45 -0
  128. package/plugins/devos/workflows/product/create-product-roadmap.md +106 -0
  129. package/plugins/devos/workflows/product/create-product-tech-stack.md +19 -0
  130. package/plugins/devos/workflows/product/gather-product-info.md +25 -0
  131. package/plugins/devos/workflows/product/resume-detection.md +70 -0
  132. package/plugins/devos/workflows/product/reverse-backlog.md +118 -0
  133. package/plugins/devos/workflows/product/reverse-domain-model.md +86 -0
  134. package/plugins/devos/workflows/product/reverse-product-plan.md +81 -0
  135. package/plugins/devos/workflows/product/reverse-tech-stack.md +73 -0
  136. package/plugins/devos/workflows/product/scan-deep.md +113 -0
  137. package/plugins/devos/workflows/product/scan-git.md +122 -0
  138. package/plugins/devos/workflows/product/scan-light.md +154 -0
@@ -0,0 +1,58 @@
1
+ # The rule layer
2
+
3
+ A scoped rule is a small, project-specific convention that a host tool auto-attaches when an edit touches a matching file, instead of sitting in `conventions.md` where nothing re-reads it at edit time. Lives at `devos/standards/rules/<NN>-<category>/<slug>.md`.
4
+
5
+ ## Authoring budget
6
+
7
+ - One topic per file. Bullets, not prose: a handful of bullets, a few words each.
8
+ - One tiny example only if it removes real ambiguity.
9
+ - Project-specific only: a rule exists because the codebase exhibits the convention, or the user declared it. Never a curated per-stack default, never general engineering practice the model already knows.
10
+ - No enforcement surface (nothing to glob)? It's documentation, not a rule: it stays in `conventions.md`, or is marked all-files below.
11
+ - A rule that exists because something broke ends with one `Source:` bullet naming what broke, in a clause. A rule with no scar is the one a future cleanup pass deletes as unexplained, and the deletion looks like tidying. Skip it when the rule just states a convention the codebase already visibly follows.
12
+ - Optional lifecycle frontmatter: `promoted: YYYY-MM-DD` when learn promoted it, and `superseded-by: <new-slug> (<date>)` when a later lesson contradicted it. A superseded rule is dead: kept as audit trail so the contradiction stays visible, never rendered to any tool. Delete nothing.
13
+
14
+ ## The category taxonomy (fixed, numbered; the number is the sort order)
15
+
16
+ | # | Category | Covers |
17
+ |---|---|---|
18
+ | 00 | architecture | layering, module boundaries, API shape |
19
+ | 01 | standards | naming, imports/exports, formatting the linter doesn't own |
20
+ | 02 | languages | language-specific rules (strict mode, a banned pattern) |
21
+ | 03 | frameworks | framework/library-specific conventions |
22
+ | 04 | tooling | build, CI, git hooks |
23
+ | 05 | testing | fixtures, mocking, coverage rules beyond what's in `conventions.md` |
24
+ | 06 | patterns | design patterns this codebase actually uses |
25
+ | 07 | quality | perf and security rules specific to this project |
26
+ | 08 | domain | business-logic rules (money handling, a domain invariant) |
27
+ | 09 | other | anything that doesn't fit above |
28
+
29
+ Place a new rule in the lowest-numbered category it fits (a language-specific rule is `02`, not `09`); when two apply, the more specific number wins (`03` frameworks over `01` standards).
30
+
31
+ ## Canonical file format
32
+
33
+ The source format is Claude Code's own, since it needs no transform. **Use `globs:`, not `paths:`**: Claude Code's documented `paths:` frontmatter is a confirmed bug (silently ignored, no error) as of this writing; `globs:` is the field that actually loads (bare, comma-separated, not a YAML list). Cite this reasoning if a future Claude Code release fixes `paths:` and this needs revisiting.
34
+
35
+ ```markdown
36
+ ---
37
+ globs: src/billing/**/*.ts, src/billing/**/*.test.ts
38
+ ---
39
+ # Money handling
40
+ - All monetary amounts are integer cents, never floats
41
+ - Currency conversion happens only in `billing/convert.ts`
42
+ - Source: float rounding on a refund path shipped a 1-cent discrepancy to production
43
+ ```
44
+
45
+ `Source:` is a body bullet, not frontmatter, so it renders to every tool alongside the rule it explains.
46
+
47
+ An all-files rule (no glob to scope it) omits `globs:` entirely; a tool that requires the field for auto-attach falls back to loading it as part of the always-loaded context instead (documented per-tool below).
48
+
49
+ ## Rendering to other tools
50
+
51
+ `${CLAUDE_SKILL_DIR}/scripts/render-rule.py` (shipped with this skill) takes one canonical rule file and writes Copilot CLI's native equivalent when a `.github/` directory is present:
52
+
53
+ | Tool | Output | Format |
54
+ |---|---|---|
55
+ | Copilot CLI | `.github/instructions/<NN>-<slug>.instructions.md` | `applyTo: "pattern,pattern"` (quoted, comma-separated) |
56
+ | Claude Code, Codex CLI, OpenCode, Pi | no render step | the canonical file is read where it lives, or folded into `AGENTS.md` by `/devos:init` |
57
+
58
+ Codex/OpenCode/Pi's lack of a rules surface is a real, stated gap, not faked: `init` lists active rule files there so the convention is still visible, just always-loaded rather than glob-attached.
@@ -0,0 +1,29 @@
1
+ # Workflow: shape the domain model
2
+
3
+ **Output:** `devos/product/domain-model.md`. Sources and output rules are in `SKILL.md`; this file is the interaction and the format.
4
+
5
+ The one-page cap is a hard limit, not a style note: nearly every spec, plan, verification and doc prompt loads this file, so every line here is paid for on almost every command. Concretely, ~60 lines. Past it, cut descriptions; never split into a second file.
6
+
7
+ Run in the main agent. Every step below waits on the user.
8
+
9
+ 1. **Check for an existing model.** If `domain-model.md` exists, list its entities and ask whether to enrich it. Enrichment merges: existing entities keep their descriptions verbatim, new ones append. Recreating a validated model throws away wording the user already chose, which reads as progress and is a regression.
10
+ 2. **Propose.** Name the entities the sources show, one line each, then ask what to add, remove, or rename. **Wait.** Correcting a proposal is faster for the user than composing from a blank page, the same reason the spec interview attaches a guess to each question.
11
+ 3. **Refine.** One batched round of structured questions (use the harness's tool if it has one) for what the proposal left open: entities users create or manage that you missed, the two or three pieces of information that matter per entity, and how entities relate. **Wait.**
12
+ 4. **Confirm, then write.** Show entities and relationships, iterate until the user validates, then write:
13
+
14
+ ```markdown
15
+ # Domain Model
16
+
17
+ ## Entities
18
+
19
+ ### [EntityName]
20
+ [What it represents, in language a non-technical reader follows.]
21
+
22
+ ## Relationships
23
+
24
+ - [Entity1] has many [Entity2]
25
+ - [Entity2] belongs to [Entity1]
26
+ - [Entity3] links [Entity1] and [Entity4]
27
+ ```
28
+
29
+ Two rules from `SKILL.md` are worth their reason here. Entity names are **singular**: specs, plans, tests and review findings all quote these names exactly, so a plural propagates into every one of them and vocabulary drift becomes a review finding later. Relationships stay **conceptual** (`has many`, `belongs to`, `links X and Y`): the moment this file carries cardinalities or foreign keys it is a schema, and a schema goes stale against the database while a vocabulary does not.
@@ -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:]))