@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.
- package/CHANGELOG.md +1398 -0
- package/LICENSE +201 -0
- package/README.md +213 -2
- package/package.json +45 -4
- package/plugins/devos/agents/reader.md +27 -0
- package/plugins/devos/agents/verifier.md +181 -0
- package/plugins/devos/pi/extension/devos.ts +615 -0
- package/plugins/devos/scripts/check-evidence-router.sh +134 -0
- package/plugins/devos/scripts/evidence-router.py +252 -0
- package/plugins/devos/scripts/gates/check-dod-core.sh +283 -0
- package/plugins/devos/scripts/gates/check-dod.sh +38 -0
- package/plugins/devos/scripts/gates/check-handoff.sh +215 -0
- package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
- package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
- package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
- package/plugins/devos/scripts/gates/check-scenario-coverage.sh +102 -0
- package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
- package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
- package/plugins/devos/scripts/gates/plan-template-check.py +147 -0
- package/plugins/devos/scripts/gates/run-gate.sh +148 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +165 -0
- package/plugins/devos/scripts/gates/test-gates.sh +4306 -0
- package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
- package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
- package/plugins/devos/skills/absorb/SKILL.md +75 -0
- package/plugins/devos/skills/absorb/references/distill.md +67 -0
- package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
- package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
- package/plugins/devos/skills/build/SKILL.md +71 -0
- package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
- package/plugins/devos/skills/build/references/defect.md +17 -0
- package/plugins/devos/skills/build/references/exposure.md +28 -0
- package/plugins/devos/skills/build/references/hard.md +39 -0
- package/plugins/devos/skills/build/references/refactor.md +66 -0
- package/plugins/devos/skills/build/references/routes.md +56 -0
- package/plugins/devos/skills/build/references/scale.md +84 -0
- package/plugins/devos/skills/build/references/spike.md +19 -0
- package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
- package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
- package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
- package/plugins/devos/skills/build/scripts/route.sh +5 -0
- package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
- package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
- package/plugins/devos/skills/design-taste/SKILL.md +55 -0
- package/plugins/devos/skills/design-taste/references/tells.md +85 -0
- package/plugins/devos/skills/design-taste/scripts/slop-scan.py +305 -0
- package/plugins/devos/skills/docs/SKILL.md +22 -0
- package/plugins/devos/skills/docs/references/backfill.md +54 -0
- package/plugins/devos/skills/docs/references/init.md +43 -0
- package/plugins/devos/skills/docs/references/status.md +71 -0
- package/plugins/devos/skills/docs/references/update.md +80 -0
- package/plugins/devos/skills/explain/SKILL.md +45 -0
- package/plugins/devos/skills/explain/references/quiz.md +21 -0
- package/plugins/devos/skills/frame/SKILL.md +71 -0
- package/plugins/devos/skills/frame/references/boundaries.md +53 -0
- package/plugins/devos/skills/frame/references/decompose.md +96 -0
- package/plugins/devos/skills/frame/references/impact.md +43 -0
- package/plugins/devos/skills/frame/references/interrogate.md +68 -0
- package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
- package/plugins/devos/skills/implement/SKILL.md +36 -0
- package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
- package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
- package/plugins/devos/skills/implement/references/dod.md +32 -0
- package/plugins/devos/skills/implement/references/implement.md +52 -0
- package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
- package/plugins/devos/skills/implement/references/plan.md +160 -0
- package/plugins/devos/skills/implement/references/resume.md +9 -0
- package/plugins/devos/skills/implement/references/scale.md +86 -0
- package/plugins/devos/skills/implement/references/verify-close.md +61 -0
- package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
- package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
- package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
- package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
- package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
- package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
- package/plugins/devos/skills/implement/scripts/validate-spec.sh +268 -0
- package/plugins/devos/skills/init/SKILL.md +100 -0
- package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
- package/plugins/devos/skills/init/references/context.md +42 -0
- package/plugins/devos/skills/init/references/conventions-template.md +153 -0
- package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
- package/plugins/devos/skills/init/references/rule-format.md +58 -0
- package/plugins/devos/skills/init/references/shape-model.md +29 -0
- package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
- package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
- package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
- package/plugins/devos/skills/learn/SKILL.md +29 -0
- package/plugins/devos/skills/learn/references/destinations.md +43 -0
- package/plugins/devos/skills/learn/references/scoring.md +26 -0
- package/plugins/devos/skills/product/SKILL.md +40 -0
- package/plugins/devos/skills/product/references/planner.md +54 -0
- package/plugins/devos/skills/review/SKILL.md +77 -0
- package/plugins/devos/skills/review/references/gaps.md +26 -0
- package/plugins/devos/skills/spec/SKILL.md +58 -0
- package/plugins/devos/skills/spec/references/prototype.md +21 -0
- package/plugins/devos/skills/spec/references/question-craft.md +47 -0
- package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
- package/plugins/devos/skills/spec/references/write-spec.md +143 -0
- package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
- package/plugins/devos/skills/status/SKILL.md +67 -0
- package/plugins/devos/skills/status/references/cost.md +38 -0
- package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
- package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
- package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
- package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
- package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
- package/plugins/devos/skills/status/scripts/quality-correlation.sh +282 -0
- package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
- package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
- package/plugins/devos/skills/surgical-diff/SKILL.md +23 -0
- package/plugins/devos/skills/test-integrity/SKILL.md +26 -0
- package/plugins/devos/skills/verification-evidence/SKILL.md +17 -0
- package/plugins/devos/workflows/common/backlog-file-structure.md +44 -0
- package/plugins/devos/workflows/common/category-file-structure.md +41 -0
- package/plugins/devos/workflows/common/feature-line-format.md +10 -0
- package/plugins/devos/workflows/common/roadmap-file-structure.md +51 -0
- package/plugins/devos/workflows/common/suggest-categories.md +76 -0
- package/plugins/devos/workflows/common/suggest-milestones.md +92 -0
- package/plugins/devos/workflows/doc/doc-health.md +137 -0
- package/plugins/devos/workflows/doc/doc-writer.md +44 -0
- package/plugins/devos/workflows/doc/init-documentation.md +196 -0
- package/plugins/devos/workflows/doc/retro-documentation.md +304 -0
- package/plugins/devos/workflows/doc/templates/library.md +58 -0
- package/plugins/devos/workflows/doc/templates/service.md +61 -0
- package/plugins/devos/workflows/doc/update-documentation.md +194 -0
- package/plugins/devos/workflows/doc/write-documentation.md +137 -0
- package/plugins/devos/workflows/product/create-product-mission.md +45 -0
- package/plugins/devos/workflows/product/create-product-roadmap.md +106 -0
- package/plugins/devos/workflows/product/create-product-tech-stack.md +19 -0
- package/plugins/devos/workflows/product/gather-product-info.md +25 -0
- package/plugins/devos/workflows/product/resume-detection.md +70 -0
- package/plugins/devos/workflows/product/reverse-backlog.md +118 -0
- package/plugins/devos/workflows/product/reverse-domain-model.md +86 -0
- package/plugins/devos/workflows/product/reverse-product-plan.md +81 -0
- package/plugins/devos/workflows/product/reverse-tech-stack.md +73 -0
- package/plugins/devos/workflows/product/scan-deep.md +113 -0
- package/plugins/devos/workflows/product/scan-git.md +122 -0
- package/plugins/devos/workflows/product/scan-light.md +154 -0
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Definition of Done
|
|
2
|
+
|
|
3
|
+
Read this checklist before Phase C's final verdict. Verify every point and fix failures before closing.
|
|
4
|
+
|
|
5
|
+
1. No pending or in-progress tasks remain in the task list.
|
|
6
|
+
2. `SPEC_DIR/spec.md` matches the approved plan.
|
|
7
|
+
3. Local CI passes: lint, type-check, tests, and build where declared.
|
|
8
|
+
4. `verifications/verification.md` exists with Completeness = CLEAN and Quality = PASS, bound to the code it judged (`commit:` in its header), and records every `SC-n` the functional spec declares.
|
|
9
|
+
5. No TODO or FIXME was introduced by this implementation, and no `[DEBUG-xxxx]` instrumentation remains in tracked files.
|
|
10
|
+
|
|
11
|
+
A claim that tests pass needs a command and exit status from this session. A verifier report is required evidence, not an optional summary. Keep the checklist in the verdict when a gate is skipped or a human check remains.
|
|
12
|
+
|
|
13
|
+
## Final verdict
|
|
14
|
+
|
|
15
|
+
Present the checklist with ✓/✗. The DONE line must be exactly:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
Verdict: DONE: devos/specs/archive/[spec-name]
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The end-of-turn gate requires the verification report at that path and blocks one whose plan files have changed since the commit it names. Claude Code enforces this with a Stop hook that blocks the turn. Pi sends a correction at turn end and hard-blocks `ops-log.sh <spec> closed` until the report exists. A test-integrity hook gates weakened tests. Name the spec branch and commit range. Merging to the default branch and pushing remain human actions.
|
|
22
|
+
|
|
23
|
+
For a worktree run, name its path and cleanup after merge: `git worktree remove [path]`, then delete the branch. Never remove an unmerged worktree.
|
|
24
|
+
|
|
25
|
+
Finish with:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
📊 [spec-name]: [✅/🔄/⏳ per phase] → archived
|
|
29
|
+
🎯 Next: ✅ Done! Optional: /devos:review --gaps [spec-name]
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
On Pi, write `/skill:review --gaps`, because Pi skill names cannot carry the `devos:` prefix. Other adapters keep their namespace.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Phase B: Implementation (main agent)
|
|
2
|
+
|
|
3
|
+
Everything needed is in `spec.md`, which embedded the conventions, vocabulary, decisions, and Local Craft findings during planning. Do not re-read the product artifacts here, and do not re-search the codebase. If `spec.md` is missing something the code contradicts, that is a HALT, not a research trip.
|
|
4
|
+
|
|
5
|
+
**Treat `Local Craft` as a design constraint, not background reading.** Before the first edit, check the task group against its local syntax, helper reuse, data structure, algorithm, and installed-package findings. If the code cannot follow one, stop and amend the plan before writing. One pass is enough.
|
|
6
|
+
|
|
7
|
+
**Scale it to the change.** A single task group, run in place, where the tests decide the outcome, needs only the first three steps below: branch, one test red then green, one commit. Read `references/manual-gates.md` only when a test cannot decide, and the worktree steps only when conventions.md asks for one or the user does. Each of the three conditions below fires whatever the framing, including a resume instruction or a deadline.
|
|
8
|
+
|
|
9
|
+
## 1. Before the first edit
|
|
10
|
+
|
|
11
|
+
**Branch.** The default branch is the human's, and the pipeline never commits there. Detect it with `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `main` or `master`, else ask once. If the current branch is the default one, or conventions.md's Branching & workspace section lists it as protected, create and switch to a spec branch (`[spec-name]`, or the pattern that section declares) and say so in one line, before touching any file. Committing on a protected branch happens only when the user asks. Already on a feature branch means use it as-is.
|
|
12
|
+
|
|
13
|
+
**Workspace.** conventions.md's Branching & workspace section wins when it declares `Workspace: in-place` or `worktree`. Otherwise an L-route spec defaults to a **worktree** (announce it in one line, the user can decline) and S/M work stays in place. A dirty tree the user declines to clean, or an explicit "keep my checkout free", flips any size to worktree, because a long run is exactly when the human needs the checkout back.
|
|
14
|
+
|
|
15
|
+
Opening one: `git worktree add [path] [spec-name]` at the declared path (default `.worktrees/[spec-name]`, which `.gitignore` must list), or the harness's own isolation. Then, in the worktree, commit `devos/specs/[spec-name]/` as the branch's first commit (`docs(spec-name): functional spec`) and remove the now-duplicate copy from the main checkout, since the spec folder travels with its branch. Run the `Workspace setup:` command conventions.md declares and report its exit status, or say in one line that none is declared. Every later phase runs inside the worktree.
|
|
16
|
+
|
|
17
|
+
**Baseline.** Check `git status --porcelain`. A dirty tree gets one question (stash, commit, or proceed knowingly), because a dirty baseline makes "every changed line traces to the plan" unverifiable. Then run the commands conventions.md declares under **Verification commands**, once, and write one line each to `SPEC_DIR/verifications/baseline.md`: the command, its exit status, and the executed test count where it reports one (`node test.js` -> exit 1, 12 passed 2 failed). No declared commands, or one that cannot complete here, is itself the record. This is the only moment the pre-change result is cheap to get, and without it "those 2 failures are unrelated" is a claim nobody can check.
|
|
18
|
+
## 2. Per group
|
|
19
|
+
|
|
20
|
+
Respect the Overview's order. One group at a time: mark in progress, implement, test, run local CI, mark complete.
|
|
21
|
+
|
|
22
|
+
For each `SC-n` in the group's **Scenarios covered** list, write the failing test before the implementation code. Run it red, then green: confirm the stated behavior fails, implement, run it again. Keep the ID-to-test mapping in the internal plan and the verification report. A scenario the plan assigned to this group that genuinely cannot be tested here is a HALT, not a silent drop.
|
|
23
|
+
|
|
24
|
+
Commit when the group's CI is green (`feat(spec-name): task group N, [name]`), unless the user asked otherwise. A bad direction then costs one `git revert`, not a wholesale deletion. Stage files by name, never `git add -A` or `git add .`, because blanket staging is how an unrelated local file ends up in a feature commit.
|
|
25
|
+
|
|
26
|
+
**Challenge hard-to-reverse choices before building on them.** Before committing to a schema shape, a public interface signature, or anything on an auth or data-loss path, state the strongest argument against your choice. Proceed only if the argument fails, and record the kept choice in decisions.md. This is the counterpart to an Ask First boundary, for decisions inside your own lane, where the verifier would otherwise meet a mistake only after code is stacked on it.
|
|
27
|
+
|
|
28
|
+
**A failed command re-enters context as its failing assertion plus `file:line`, never its whole log.** The log stays on disk to re-read when the assertion is not enough. Every line pasted into the conversation is re-read from cache by all the turns that follow, and a 400-line stack trace buys one fact.
|
|
29
|
+
|
|
30
|
+
## 3. Rules that never bend
|
|
31
|
+
|
|
32
|
+
**Name each test after observable behavior**, in the project's concise style: `it('returns 401 for an expired token')`, `def test_returns_401_for_expired_token`. **Keep process metadata out of implementation files**: no `SC-n` ID, scenario label, spec path, framework rule, framework name, or process note in a test name, comment, string, fixture, or other implementation file. The edit gate checks this boundary when the harness supports it.
|
|
33
|
+
|
|
34
|
+
`surgical-diff` and `test-integrity` are their own skills and apply to every line you touch.
|
|
35
|
+
|
|
36
|
+
**HALT conditions.** Stop and ask. Plan approval does not cover these.
|
|
37
|
+
|
|
38
|
+
- An **Ask First** boundary is reached. Those entries are the human's named decisions, and plan approval explicitly did not pre-answer them.
|
|
39
|
+
- The codebase contradicts the plan (API doesn't exist, schema differs, pattern won't fit). State the conflict in 2-3 lines, propose the amendment, wait for OK. Never improvise silently past an approved plan.
|
|
40
|
+
- A new dependency not in the approved plan.
|
|
41
|
+
- 3 consecutive failures on the same task group.
|
|
42
|
+
- Destructive operations: dropping or altering DB tables with data, wholesale file deletion, git history rewrites, force-push.
|
|
43
|
+
- Pushing to any remote, or merging into the default or protected branch. Only on an explicit user request, never as part of finishing.
|
|
44
|
+
- A migration without its reverse. Migrations ship with the rollback path in their acceptance criteria and get tested on non-prod data first, and an irreversible migration is announced as such before it runs.
|
|
45
|
+
|
|
46
|
+
## 4. Record as you go
|
|
47
|
+
|
|
48
|
+
- **Decisions:** a non-obvious choice, a deviation from the plan, or a gotcha gets one line in `SPEC_DIR/decisions.md` with a stable ID, `- D-3: [decision], why`. Numbering continues from the file's last ID. Future plans cite these IDs instead of re-quoting.
|
|
49
|
+
- **Dead ends**, same file and format, prefixed `rejected:` so it reads as a closed door, `- D-4: rejected: [approach], [what happened]`. Only the ones a competent reader would otherwise retry, meaning a wrong turn that cost real work or an approach the codebase actively defeats. Not typos, not the ordinary first draft. Without these, only the surviving path is written down, so the next spec that reads these IDs pays the same dead end again.
|
|
50
|
+
- **Cross-cutting discoveries**, appended to the capsule's Implementation Notes the moment a group finds one, because a later group or a later session needs it. Every later group reads the block before starting, so a fact found by group 1 reaches groups 2-3 without anyone re-paying for the discovery.
|
|
51
|
+
|
|
52
|
+
**Phase B done when** every task group is marked complete, local CI's last run was green, no open HALT condition remains, and `SPEC_DIR/gates.md`, when it exists, was left with every box checked by gate-check.mjs or honestly abandoned. Log it: `bash ${CLAUDE_SKILL_DIR}/scripts/ops-log.sh SPEC_DIR implemented "[groups done]/[total]"`. All four must hold before Phase C.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Manual acceptance gates
|
|
2
|
+
|
|
3
|
+
Load this reference when a task group contains an outcome that project tests cannot decide, such as a browser-only visual state, a TTY message, or a number that determines the verdict.
|
|
4
|
+
|
|
5
|
+
Before the group starts, write one checkbox per outcome to `SPEC_DIR/gates.md`, with a runnable check where one exists:
|
|
6
|
+
|
|
7
|
+
```markdown
|
|
8
|
+
- [ ] G1: pricing toggle flips both price and label in the rendered page
|
|
9
|
+
CHECK: node scripts/check-toggle.js
|
|
10
|
+
EXPECT: toggle ok
|
|
11
|
+
EVIDENCE: pending
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/gate-check.mjs SPEC_DIR/gates.md` before Phase B is complete. The gate flips a box only when output matches `EXPECT` and records the deciding output. A checked box with `EVIDENCE: pending` is unmet.
|
|
15
|
+
|
|
16
|
+
If a gate becomes impossible, add `ABANDON: <id> <reason>` to `gates.md` and the matching entry to `devos/deferred.md`. Do not silently drop it. The DoD gate blocks DONE while any gate remains unmet on tools that enforce DoD.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Phase A: Planning
|
|
2
|
+
|
|
3
|
+
Four steps. Check the input, read the project, settle the design, write the capsule and get a go.
|
|
4
|
+
|
|
5
|
+
Phase A ends at a stop: present the plan, end your turn, and wait for the user's yes. No file outside `devos/` changes before it. The original request is not that yes. On Pi the extension blocks the edit.
|
|
6
|
+
|
|
7
|
+
`${CLAUDE_SKILL_DIR}` is this skill's directory and `${CLAUDE_PLUGIN_ROOT}` is the plugin root. Both expand in a shell command on every adapter, so every script path uses them.
|
|
8
|
+
|
|
9
|
+
## 1. Check the input
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
bash ${CLAUDE_SKILL_DIR}/scripts/validate-spec.sh SPEC_DIR
|
|
13
|
+
python3 ${CLAUDE_PLUGIN_ROOT}/skills/status/scripts/check-requires.py --verify SPEC_DIR
|
|
14
|
+
bash ${CLAUDE_PLUGIN_ROOT}/skills/spec/scripts/clarify.sh SPEC_DIR
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
A FAIL from `validate-spec.sh` stops here. Relay each line and its fix, get it corrected, continue. Under `devos/specs/archive/`, `spec.md` is a historical record, so the current plan gates do not apply to it and functional-spec validation is the whole check.
|
|
18
|
+
|
|
19
|
+
`check-requires.py` and `clarify.sh` never block. Surface each `INFO` line in one line, then continue. The engineer proceeds knowingly and the verifier repeats the same INFO.
|
|
20
|
+
|
|
21
|
+
Read `references/conditional-plan.md` only for a prototype, an `## Invariant` route, or a published API or event change.
|
|
22
|
+
|
|
23
|
+
## 2. Read the project
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
python3 ${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/detect-archetype.py --facts .
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
No model calls, under a second. Its output goes into the capsule verbatim as `### Stack facts`, and its archetype tags pick the **Specialist skills** line, where a `design:*` or `style:*` hit names expertise this workflow does not carry. A row marked `range, NOT resolved` means nothing is installed yet, so the range is the honest answer and recall risk is higher. Where a version's shape matters, read the installed package's own files (`node_modules/<pkg>/`) rather than recalling them, since recalled API carries no marker saying it was recalled.
|
|
30
|
+
|
|
31
|
+
Then read `spec-functional.md` first, and the product files this change actually touches, skipping any that do not exist:
|
|
32
|
+
|
|
33
|
+
- `devos/product/tech-stack.md`
|
|
34
|
+
- `codebase-map.md`, as the module list to start the search from. If its `commit:` header is 30 or more commits behind HEAD per `git rev-list --count`, say so in one line and continue.
|
|
35
|
+
- `domain-model.md`, whose entity names are the vocabulary.
|
|
36
|
+
- `glossary.md`, `capabilities.md`, `personas.md`, `constraints.md` and `decisions.md`, so the plan uses the product's words, knows which capability already exists, and does not reopen a settled question.
|
|
37
|
+
- `knowledge/<page>.md` for the page whose subject this change touches, when the workspace has absorbed product documentation. One page, read for the rule it states, never the whole folder.
|
|
38
|
+
- `behaviors/<capability>.md` for each capability the Behavior delta names. A conflict between code and a behavior file is a finding to surface, not to resolve silently.
|
|
39
|
+
|
|
40
|
+
In a monorepo, scope the search to the affected packages. Read `decisions.md` in related specs, under `devos/specs/` first, and into `archive/` only when the task names that spec.
|
|
41
|
+
|
|
42
|
+
**Prior art over invention.** For a new instance of an artifact class this workspace already has (CI pipeline, Dockerfile, deploy manifest, scaffold, test harness, service client), open the nearest existing instance and read the file. `conventions.md` saying a pipeline does blue/green is not imitable, because the pipeline says which branch selects which environment and what the stage order is. Search this repo, then sibling checkouts beside it when `devos/` sits above several repos (list the parent directory, no clone, no network). Embed the exemplar's structure in the capsule, not just its path. Finding nothing is a result worth one line, since an invented structure and a recalled one look identical there and neither carries a marker.
|
|
43
|
+
|
|
44
|
+
**Conventions.** Read `devos/standards/conventions.md`, plus any `devos/standards/rules/` file scoped to a directory this plan touches. `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/evidence-router.py --task "<the change in one line>" --files <the files this plan touches>` lists the sections to embed when that file is long, and it stays a reading list: embed any line the plan needs even when the router left it out. Those bullets are load-bearing. A violation is either fixed to comply, or recorded in `SPEC_DIR/decisions.md` as one line, `- D-n: [decision], why`, quoting the convention line and the reason. Numbering continues from the file's last ID. Rule-file bullets are never excepted this way. If the conflict is the spec's own stated goal, so no compliant version of the request exists, that is not a plan-adjustment case: surface it as a spec-level conflict before planning further, because "the spec asked for it" rubber-stamps the violation the convention exists to prevent.
|
|
45
|
+
|
|
46
|
+
**Local craft.** Propose candidates from general engineering knowledge, then resolve each project fact in this order:
|
|
47
|
+
|
|
48
|
+
1. The spec, behavior files, and conventions define the intended contract.
|
|
49
|
+
2. Current code and tests show present behavior and local syntax.
|
|
50
|
+
3. The nearest sibling implementation and its tests show style, helper reuse, data structure, and algorithm shape.
|
|
51
|
+
4. The installed package's types or source settle version-specific syntax.
|
|
52
|
+
5. Authoritative external documentation answer what the project leaves open.
|
|
53
|
+
|
|
54
|
+
Record `file:line` or a URL beside anything non-obvious. **Model recall never outranks project evidence.** Explicit contract anchors in the functional spec are binding inputs: verify each against current code and tests before designing, and surface a mismatch rather than changing the contract silently.
|
|
55
|
+
|
|
56
|
+
Three to six implementation-critical findings go under **Local Craft**, or `None` when the task is conventional. They cover local syntax and style, reusable helpers or data structures, version-specific API shape, and algorithm choice, each only when it applies. General coding advice does not belong here. The smallest algorithm the constraints allow wins, so a join, filter, or lookup does not become an algorithm exercise.
|
|
57
|
+
|
|
58
|
+
## 3. Settle the design
|
|
59
|
+
|
|
60
|
+
Zero questions when the architecture is clear. Otherwise one batched round, shaped by the spec skill's `references/question-craft.md`, and **wait** for the answers. Record each answer in `decisions.md` as an override with its cost accepted.
|
|
61
|
+
|
|
62
|
+
Then four steps in order, recorded in the capsule's **Design Convergence** section:
|
|
63
|
+
|
|
64
|
+
- **Direct MVP**: the simplest end-to-end design that delivers the Goal with what step 2 found. The spec's MUSTs and the engineer's confirmed answers are binding, and so is anything under **Engineer overrides**, since that choice was already challenged once and paid for. A mechanism the spec merely suggests is a candidate, not a constraint. An **Open assumptions** entry is a question, so it goes in the round above rather than into the design as a fact. When the MVP bolts the requirement on (a flag, a special case, a second path), sketch the design you would have built had the requirement existed from the start. If that one is smaller to keep, it becomes the MVP, delivered in steps that keep the checks green.
|
|
65
|
+
- **Failed Items**: what the MVP fails against the spec's scenarios, its constraints, and step 2's conventions, each with the evidence it fails. `None` is the normal answer on M-sized work, and it means the MVP is the plan.
|
|
66
|
+
- **Adopted Additions**: at most one per Failed Item, and only after reuse, deriving from existing data, computing on demand, and handling it at the caller have each failed. Record `addition → the Failed Item it answers → why nothing smaller resolves it`. An addition with no Failed Item does not enter the plan.
|
|
67
|
+
- **Rejected Additions**: candidates the Subtraction Check dropped, one line each, so a later session does not re-propose them. Each was removed on paper and its Failed Item re-tested, and it stays only if the item fails again.
|
|
68
|
+
|
|
69
|
+
This is `surgical-diff` one level up. That skill keeps the diff inside the plan, this keeps the plan inside the goal. An abstraction with one caller, a config value that never varies, a layer built for a requirement nobody stated: each reads as reasonable at approval time and each fails the Subtraction Check.
|
|
70
|
+
|
|
71
|
+
## 4. Write the capsule, then get the go
|
|
72
|
+
|
|
73
|
+
Into `SPEC_DIR/spec.md`, never as chat text.
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
---
|
|
77
|
+
devos-contract: 1
|
|
78
|
+
---
|
|
79
|
+
# [Feature Name]
|
|
80
|
+
<!-- Capsule budget: ≤ 300 lines, and that is a ceiling rather than a target. An M-sized plan is one page with `None` where a section does not apply. Overflow means the spec splits. Never compress the plan to fit. -->
|
|
81
|
+
|
|
82
|
+
<!-- Human-owned, frozen after approval: Goal, Boundaries, acceptance criteria, amend only via Change Log + re-approval. Agent-owned, living: Code Map, task checklists, Implementation Notes, Change Log. -->
|
|
83
|
+
|
|
84
|
+
## Goal / Technical Context / Architecture / Technical Requirements / Existing Code to Leverage
|
|
85
|
+
[Concise sections. Project anchors only.]
|
|
86
|
+
|
|
87
|
+
## Local Craft
|
|
88
|
+
[Three to six findings from step 2, or `None`. Every non-obvious fact names `file:line` or a URL.]
|
|
89
|
+
|
|
90
|
+
### Stack facts
|
|
91
|
+
[From step 2, verbatim.]
|
|
92
|
+
|
|
93
|
+
## Design Convergence
|
|
94
|
+
[From step 3. One line each, `None` where it applies.]
|
|
95
|
+
- **Direct MVP**: [the simplest design that delivers the Goal with what exists]
|
|
96
|
+
- **Failed Items**: [what the MVP fails → the evidence it fails, or `None`]
|
|
97
|
+
- **Adopted Additions**: [addition → its Failed Item → why nothing smaller resolves it]
|
|
98
|
+
- **Rejected Additions**: [candidate → why not]
|
|
99
|
+
|
|
100
|
+
## Specialist skills
|
|
101
|
+
[What the installed skills from step 2 contribute, one clause each, or `none`.]
|
|
102
|
+
|
|
103
|
+
## Boundaries
|
|
104
|
+
- **Always** (in scope): [the change itself]
|
|
105
|
+
- **Ask First** (named decisions that HALT for the human if reached)
|
|
106
|
+
- **Never** (out of scope): [what this spec deliberately doesn't do]
|
|
107
|
+
|
|
108
|
+
## Code Map
|
|
109
|
+
[One line per file the plan touches: `path: role in this change`. Implementation starts from this map, not from a fresh search.]
|
|
110
|
+
|
|
111
|
+
## Implementation Plan
|
|
112
|
+
|
|
113
|
+
### Overview
|
|
114
|
+
Total: [N] task groups. [Sequence them in dependency order and number the groups the same way here and in the headings, since the count and the headings are checked against each other.]
|
|
115
|
+
|
|
116
|
+
### Task Group 1: [Name]
|
|
117
|
+
**Files:** `path/one`, `path/two`
|
|
118
|
+
**Complexity:** Simple | Medium | Complex
|
|
119
|
+
- Objective, sub-tasks, tests to write
|
|
120
|
+
**Scenarios covered:** [the `SC-n` IDs this group's tests exercise, e.g. `SC-1, SC-4`. Every scenario appears in exactly one group's list, in acceptance criteria, or is marked `[human-check]`, because a scenario covered nowhere is a planning gap you fix before presenting. Tests use behavior-facing names.]
|
|
121
|
+
**Acceptance Criteria:** [only what tests don't cover. Use `[human-check]` and `[visual-check]` under `references/conditional-plan.md`.]
|
|
122
|
+
|
|
123
|
+
## Implementation Notes
|
|
124
|
+
[Append-only, one line per cross-cutting fact a later task group must know. Write it the moment a group discovers it. Decisions and dead ends belong in decisions.md.]
|
|
125
|
+
|
|
126
|
+
## Change Log
|
|
127
|
+
[Append-only, one line per post-approval amendment: what changed, why, which triage branch caused it. Never rewrite history above.]
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
**spec.md is a context capsule.** Implementation, this session or a future one, reads this file and nothing else. That is what survives bigger context windows, a worktree, and months from now against a file that has since moved. A reference resolves to current truth only while the file is still there to resolve.
|
|
131
|
+
|
|
132
|
+
**Implementation output boundary:** process metadata lives in this capsule or another `devos/` artifact. Files outside `devos/` carry project behavior only. No `SC-n` ID, scenario label, framework name, framework rule, spec path, or process note goes into source, tests, comments, strings, fixtures, or generated assets, and the edit gate checks it when the harness supports that.
|
|
133
|
+
|
|
134
|
+
- **Embed** the conventions rules this feature touches, copying the lines rather than citing the file, including archetype-specific sections. Embed the domain-model entities involved (names plus one-line meanings), relevant `decisions.md` extracts by ID ("per D-4"), and the exact integration points exploration found.
|
|
135
|
+
- **Preserve explicit contract anchors in Technical Requirements** when they constrain behavior and **in Code Map when they name files**. Do not silently rename or relocate them.
|
|
136
|
+
- **Exclude** what any competent agent already knows: code blocks, framework how-tos, time estimates, "run tests" sub-tasks. The Exclude rule is what keeps the capsule small, not fewer embeds.
|
|
137
|
+
- **Deletion test**: a proposed wrapper, helper, or indirection layer must state the complexity it concentrates. If deleting it removes the complexity, the plan drops it and calls the underlying thing directly. One caller is never a seam.
|
|
138
|
+
- Each task group is roughly 1-4h. **Whole plan ≤ 300 lines**, and an M-sized plan is well under a page. A capsule that does not fit means the spec is too big, so split it.
|
|
139
|
+
|
|
140
|
+
Then run `bash ${CLAUDE_SKILL_DIR}/scripts/validate-spec.sh SPEC_DIR` again now that `spec.md` exists. Fix every FAIL before presenting. One missing scenario costs one edit here against a re-derivation later.
|
|
141
|
+
|
|
142
|
+
**What those two scripts reject, so you do not need to open them.** A FAIL from either is a shape problem, never a judgement call:
|
|
143
|
+
|
|
144
|
+
- The capsule is over 300 lines.
|
|
145
|
+
- `## Local Craft` is missing, or its body has no `file:line` or URL and is not `None`.
|
|
146
|
+
- `## Design Convergence` is missing, or it adopts an addition while `Failed Items` is `None`.
|
|
147
|
+
- A task group has no `**Files:**` line.
|
|
148
|
+
- The `Total:` count in `### Overview` does not match the number of `### Task Group` headings.
|
|
149
|
+
- An `SC-n` the functional spec declares is cited nowhere in the capsule, or the capsule cites an `SC-n` the spec never declared.
|
|
150
|
+
- An explicit contract anchor is missing from Technical Requirements or Code Map, and the notes supplied one.
|
|
151
|
+
|
|
152
|
+
The gate scripts have only run at verification time otherwise, after code was written against the defective plan.
|
|
153
|
+
|
|
154
|
+
**Read it as a stranger.** Before the gate, hand `SPEC_DIR/spec.md` to the `reader` at `${CLAUDE_PLUGIN_ROOT}/agents/reader.md` in a fresh context: a subagent given that persona and the spec path as its whole input, with no history, no summary of this conversation, and no repository tour, because a reader who can ask you what the plan meant will ask instead of reporting the gap. Fill in the decisions it names, run it once more, then present the plan naming anything still open, so the yes covers the plan as written rather than as you meant it. Where the harness has no isolated context, write `unreviewed plan` on that line and present anyway, since the approval is still the human's to give.
|
|
155
|
+
|
|
156
|
+
**The approval gate.** Present the plan in a few plain lines, using the structured-question tool if the harness has one, saying what will change and why it matters rather than narrating the process. A hedged answer ("looks reasonable", "sure, whatever") is not approval, so ask one clarifying question. Only an unambiguous affirmative opens the gate. In a headless run (`-p`, CI), where no human can reply, the requester's go is the original ask: show the plan and proceed. Nowhere else. Do not stop at an approval that cannot arrive.
|
|
157
|
+
|
|
158
|
+
**After the go**: track one task per task group with the harness's task-list tool if it has one (description carries the group's content, dependencies marked), else spec.md's own checklist. Then log `bash ${CLAUDE_SKILL_DIR}/scripts/ops-log.sh SPEC_DIR plan-approved "[N] groups"`.
|
|
159
|
+
|
|
160
|
+
**Phase A done when** `SPEC_DIR/spec.md` exists carrying the plan you presented, `validate-spec.sh` passes on it, and every group has a task-list entry (or checklist line). All three must hold before Phase B.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Phase 0: Resume detection
|
|
2
|
+
|
|
3
|
+
Use this reference only when `SPEC_DIR/spec.md` exists.
|
|
4
|
+
|
|
5
|
+
1. Log `started` with the point this run resumes. If `spec-functional.md` changed after the plan, show its diff and wait for **re-plan** or **continue anyway**.
|
|
6
|
+
2. When `verifications/verification.md` exists, run Completion for an active spec. For an archived spec, wait for **re-plan** or **stop**.
|
|
7
|
+
3. Otherwise compare task groups with the code, show done and pending groups, and wait for **resume**, **re-plan**, or **review**. On resume, recreate the task list with the harness tool, or use the spec checklist if unavailable, then start Phase B at Branch/Workspace/Baseline. Re-plan starts Phase A.
|
|
8
|
+
|
|
9
|
+
A mid-session interruption may use the harness checkpoint or resume tool. Across sessions, `spec.md`, `decisions.md`, and `git log` are the durable state.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# A behavior-preserving change across many units: the rules, the work, the judgment
|
|
2
|
+
|
|
3
|
+
Load this when the spec folder holds a `manifest.tsv`, which is the build skill's signal that the change spans many units. Without that file this profile does not apply, and the default path stands.
|
|
4
|
+
|
|
5
|
+
The setup half (the verdict, the units) lives in the build skill's `references/scale.md`.
|
|
6
|
+
|
|
7
|
+
The plan holds one task group for the whole change, and the units live in the manifest. A plan that lists the units in its task groups puts four hundred files in the capsule, and every unit reads the capsule. The group's files are the target tree, so the convergence check sees the change landed.
|
|
8
|
+
|
|
9
|
+
## Step 3: the decisions, decided once
|
|
10
|
+
|
|
11
|
+
Every unit faces the same handful of questions: what does this source construct become, what does a null become, where does the ownership live. Each is answered once, in the project's own rule files, so the answer reaches the worker that needs it and no other.
|
|
12
|
+
|
|
13
|
+
Those rules are written before the work starts, from the census the build half's Step 3 ran, one rule per construct the census found. This step is how a worker reads them.
|
|
14
|
+
|
|
15
|
+
The rule files are `devos/standards/rules/<NN>-<category>/<slug>.md`, scoped by glob to the files they govern, exactly like any other scoped rule. Two properties make that the translation rulebook:
|
|
16
|
+
|
|
17
|
+
- The meta-rule: if two workers could answer a question differently, the answer goes in a rule file. A question answered twice is a question the port gets two answers to.
|
|
18
|
+
- Amendments queue for the human: a worker that meets a case the rules do not cover records the question in `SPEC_DIR/decisions.md`, takes the most conservative translation, and keeps moving.
|
|
19
|
+
|
|
20
|
+
The rules reach a worker two ways. The capsule embeds the rules for the files the plan touched, so a worker that reads the capsule has them. A harness with a rules surface attaches each rule to the files it governs as well, so a worker reads the rules for the files it edits and nothing else.
|
|
21
|
+
|
|
22
|
+
## Step 4: the work
|
|
23
|
+
|
|
24
|
+
Work the queue, not the tree:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
bash ${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/manifest-queue.sh status --manifest SPEC_DIR/manifest.tsv
|
|
28
|
+
bash ${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/manifest-queue.sh next --manifest SPEC_DIR/manifest.tsv --batch 10
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`next` lists the pending units, ten at a time. Each unit is one pass carrying the capsule, the rules for its files, and nothing else. One unit at a time, with disjoint file sets and no shared staging. A conflict between two units means the manifest split is wrong, so fix the split before porting either.
|
|
32
|
+
|
|
33
|
+
Done-ness is the filesystem: a unit is done when its target exists and carries content. `verify` catches the two ways a unit looks done and is not, a target that exists and is empty, and a unit whose source is missing:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
bash ${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/manifest-queue.sh verify --manifest SPEC_DIR/manifest.tsv
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Each unit ports its test before its code. The legacy unit's test is translated into the target, and the ported code has to pass it, so the comparison in Step 5 is the behavior and not a claim about it. A legacy unit with no test of its own gets one, written from what the legacy code does and put in the target tree, before anything is ported. A test written after the port describes the port rather than the behavior it replaced, which is worth nothing as a comparison.
|
|
40
|
+
|
|
41
|
+
Port the first three units before the rest, then read the three side by side. The rules decide every unit after them, so a rule that is wrong shows up in the first three files and costs three units to fix instead of four hundred. A construct that came out two different ways in three files is a rule that is missing or vague. Amend it in the rule files, queue the amendment, and go on.
|
|
42
|
+
|
|
43
|
+
The disagreement is found by the machine, not by a second translator:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
python3 ${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/pilot-consistency.py --manifest SPEC_DIR/manifest.tsv --root PROJECT_ROOT
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
It reduces each unit's source and target to the same handful of structural roles and compares the units against each other. A site the source had is kept in one unit and gone in another, and that is a rule that is missing or vague. The script names the two files to read side by side. A second translator would cost a second full pass over the pilot and would still only disagree by accident, so it is not used.
|
|
50
|
+
|
|
51
|
+
A port that writes a new tree leaves the tree it read alone, and the tree it read may be running in production. That is why the characterization test lands in the target tree and not next to the legacy code. The DoD gate enforces the rest. A DONE claim on a spec folder holding a `manifest.tsv` is checked against the manifest's sources, and an edit to one of them blocks the claim. It compares the branch against the commit that introduced the spec, so the whole port counts, not only the working tree.
|
|
52
|
+
|
|
53
|
+
## Step 5: the judgment
|
|
54
|
+
|
|
55
|
+
The judgment is a command run against both trees, and it is a script so the claim carries an exit status:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
bash ${CLAUDE_PLUGIN_ROOT}/skills/implement/scripts/equivalence-check.sh \
|
|
59
|
+
--before legacy --after modernized \
|
|
60
|
+
--before-cmd "make -C legacy test" --after-cmd "npm test" --label "parity"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The before tree is wherever the old code is: the legacy directory, or a worktree of the base commit when the port replaces the code in place. The judgment does not need the old code to still be there.
|
|
64
|
+
|
|
65
|
+
One property makes the verdict worth something:
|
|
66
|
+
|
|
67
|
+
- A red baseline is unproven, not equivalent: a command that fails on the before tree proves nothing about the after tree. That is a finding about the baseline, and it is the build skill's red-baseline stop, arriving late.
|
|
68
|
+
|
|
69
|
+
The two commands may differ when the two stacks differ, and their output has to be comparable: the before and after commands print the same shape, so a difference in the output is a difference in behavior. Where the two stacks cannot print the same shape, the judgment is a parity script driving both through the public surface, and that script is the artifact the rules govern.
|
|
70
|
+
|
|
71
|
+
The old tests judge the port only while they survive it. A test that imports the internals of the old language dies with that language, and then the judge is a script you write: one that calls the same scenarios on both sides and diffs the results. Keep it running for the whole port, because a judge that stops answering the question it was built for is a green light for a broken port.
|
|
72
|
+
|
|
73
|
+
The judge has to have seen a break before its verdict is worth anything. `equivalence-check.sh --self-test` proves the script sees a difference. It cannot prove the project's own command does, so run the judge once against code that is deliberately broken and read what it says. A judge that calls a broken tree equivalent is not evidence, and every verdict after it inherits that.
|
|
74
|
+
|
|
75
|
+
Judge a unit before the next one lands, rather than the tree at the end. The judgment for a unit is that unit's own behavior: the legacy unit's test against the ported unit's test, both printing the same shape. A port judged only at the end reports at the end, which is the week the errors were available.
|
|
76
|
+
|
|
77
|
+
## Step 6: the close
|
|
78
|
+
|
|
79
|
+
The port is done when the queue says every unit is done, the judgment passes, and the DoD gate is green. The queue's `verify` is the one that knows about the units, and it is the one that catches a unit that looks done and is not. The verification report says how many units were ported, what the judgment compared, and what the tree still carries.
|
|
80
|
+
|
|
81
|
+
The port's rules are the new project's rules, so restate them in the new tree's terms: a rule that said what the legacy construct became says what the new code does now. A port that was a rehearsal keeps its rules with the spec, because they say nothing about the code that is there.
|
|
82
|
+
|
|
83
|
+
## What this profile does not do
|
|
84
|
+
|
|
85
|
+
- It does not replace the test suite. The judgment is the suite, run on both sides.
|
|
86
|
+
- It does not cost an amendment. A rule that changes how a construct is translated leaves the units that used it stale, and the census says how many those are. Revisiting them or shipping two styles is the human's call.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Phase C: Verify, close, and say what changed
|
|
2
|
+
|
|
3
|
+
`${CLAUDE_SKILL_DIR}` is this skill's directory and `${CLAUDE_PLUGIN_ROOT}` is the plugin root.
|
|
4
|
+
|
|
5
|
+
## 1. Verify
|
|
6
|
+
|
|
7
|
+
Load `references/dod.md` before the final verdict. If the spec has visual or interactive criteria and the project declares a Preview command, load `references/visual-verification.md` and complete its browser walk first.
|
|
8
|
+
|
|
9
|
+
Verify with the `verifier` rubric at `${CLAUDE_PLUGIN_ROOT}/agents/verifier.md`, both lenses: completeness and quality. Run it in a fresh context where the harness exposes one: a verifier that can read this conversation inherits the claims it exists to test. Where it cannot, say so in the verdict message, so nobody reads it as independent. Give it `SPEC_DIR`, the path to spec.md, and the list of files changed during implementation, never your own summary or claim of success. The verifier judges the artifact, not your account of it.
|
|
10
|
+
|
|
11
|
+
Confirm `SPEC_DIR/verifications/verification.md` exists and carries its `commit:` header, rerunning the verifier if it is missing or bound to an older commit, then log it: `bash ${CLAUDE_SKILL_DIR}/scripts/ops-log.sh SPEC_DIR verified "[Completeness]/[Quality]"`.
|
|
12
|
+
|
|
13
|
+
## 2. Triage every finding to exactly one destination
|
|
14
|
+
|
|
15
|
+
Severity is yours to assign, not the verifier's.
|
|
16
|
+
|
|
17
|
+
- **intent gap**: the code matches the plan but not what the user meant. Stop and go back to the user, and **preserve the attempted work**. It already lives on the spec branch, so name that branch and the last green commit in the halt message (stash only for uncommitted work). Never discard it, because the user judges faster with the artifact in hand and a wrong guess costs a branch delete instead of a rebuild.
|
|
18
|
+
- **spec error**: the plan itself was wrong. One Change Log line in spec.md, amend the plan section (re-approval if a frozen section changed), re-derive the affected code.
|
|
19
|
+
- **patch**: an implementation bug. Fix now, within surgical-diff discipline.
|
|
20
|
+
- **defer**: real but out of scope. One append-only line in `devos/deferred.md` (`[spec-name]: summary: file:line`).
|
|
21
|
+
- **reject**: refuted on inspection. Drop it.
|
|
22
|
+
|
|
23
|
+
After patches or spec amendments, re-run the verifier. At the second completed round with open findings, debug before patching again: read `references/debug-loop.md`. HALT at the fifth triage loop.
|
|
24
|
+
|
|
25
|
+
## 3. Close
|
|
26
|
+
|
|
27
|
+
**Merge the Behavior delta.** For each capability the delta names, update `devos/product/behaviors/<capability>.md`, creating it on first touch. **Added** appends the behavior with its scenarios, **Modified** replaces the quoted block, **Removed** deletes it and leaves one tombstone line under `## History` (`- removed [behavior]: [reason], per [spec-name]`). File format: title, a `> updated: [date] | last spec: [spec-name]` header, and short requirement statements each with their scenarios and the spec name that last touched it. **Budget: one page per capability.** Overflow means the capability should split. The truth layer updates as a by-product of shipping, never as a separate documentation chore.
|
|
28
|
+
|
|
29
|
+
On conflict, append one line to `devos/product/behaviors/<capability>.conflicts.log`, creating it on first conflict: `$(date +%Y-%m-%d) [spec-name] [conflict-type]`, where the type is `section-overlap` (both specs modified the same requirement block) or `semantics` (changes are semantically incompatible). The log is append-only, because git history cannot express *why* a merge conflicted, only that the content changed.
|
|
30
|
+
|
|
31
|
+
A C route (the spec has an `## Invariant` section) skips the merge and says so in one line. There is no delta, and that is the contract rather than an omission, because the behavior files are already correct precisely because the work preserved what they describe.
|
|
32
|
+
|
|
33
|
+
**Archive the folder.** `git mv devos/specs/[spec-name] devos/specs/archive/[spec-name]`, log `closed` via `ops-log.sh` so the trail travels with the folder it describes, then commit the move: `chore(spec): complete [spec-name], merge behavior delta`, or on a C route where nothing was merged, `chore(spec): complete [spec-name], archive`, since the message should not claim it was.
|
|
34
|
+
|
|
35
|
+
## 4. Record
|
|
36
|
+
|
|
37
|
+
**Scale it to the change.** A single-task-group change that verified clean on the first pass has no finding to log, no understanding debt, and nothing to promote, so this section writes exactly one line: the quality row. Everything else below fires only when it has something to record, and a step with nothing to record says nothing rather than writing a note that says there was nothing.
|
|
38
|
+
|
|
39
|
+
**The quality row.** One tab-separated line to `devos/specs/archive/[spec-name].quality.md`, six columns: spec name, route, first-run validate-spec pass, finding count, highest severity (none/suggestion/warning/critical), first-run DoD pass. Every value is a parse of a file already on disk, so no model call is needed.
|
|
40
|
+
|
|
41
|
+
Three columns were dropped: triage loops, audit hits, and understanding. Across every row this repo has ever written, triage loops was `?` every time, audit hits was `-/0` or the `?/N` "predates the column" form, and understanding was absent from all of them. A column nobody fills is a column nobody reads. `quality-correlation.sh` still computes statistics over the three, so rows written before this change keep being counted.
|
|
42
|
+
|
|
43
|
+
Route is **C** when `spec-functional.md` has an `## Invariant` section, checked first since a C spec can have reached here by either the notes or the inline path, otherwise **L** when `planning/notes.md` exists, otherwise **M**. S and R never reach this step.
|
|
44
|
+
|
|
45
|
+
**Resolved findings.** For every finding resolved this session (patched, spec-amended, or rejected), append one line to `devos/deferred.md`, creating it if absent: `[spec-name] [severity] [resolution]: [one-line summary]`, where resolution is `patch`, `spec-amendment`, or `reject`. Findings routed back to the user or deferred as out of scope are not logged here.
|
|
46
|
+
|
|
47
|
+
**Say what the engineer did not see.** This run generated understanding debt if the work ran in a worktree. That means the code exists and the person accountable for it watched a one-line summary go by. Where it fired, add one line before the verdict naming what they missed and the way back (`3 groups ran in a worktree; /devos:explain [spec-name] walks the diff`). Where it did not, say nothing. This was the understanding column, and no row in this repo has ever carried a value for it, so the sentence to the engineer is the whole of it.
|
|
48
|
+
|
|
49
|
+
**Promote what would recur.** Read back the resolved findings just logged, the `rejected:` entries this run added to `decisions.md` (a dead end that cost real work is exactly what a sibling spec would re-pay for), and any line appended to a `devos/product/behaviors/*.conflicts.log` (a semantic conflict is usually a vocabulary gap wearing a merge hat).
|
|
50
|
+
|
|
51
|
+
Ask one question per candidate: is the root cause specific to this spec, or would the same mistake land in a sibling file? Where it would recur, invoke `/devos:learn` with it now, before the verdict, because `learn` is the only thing that stops it happening again and the ledger alone just records that it did. Its scoring pass drops whatever is not durable, which makes a wrong guess cost one line rather than an artifact. Nothing to promote is the normal answer and needs no comment.
|
|
52
|
+
|
|
53
|
+
## 5. Communicate the delta
|
|
54
|
+
|
|
55
|
+
Verification proves the work. This step makes it legible to everyone who was not in the session.
|
|
56
|
+
|
|
57
|
+
- **Changelog**: the project carries one (`CHANGELOG.md`, release notes, a per-spec log). Append the user-visible delta there now, in that file's format, because a completed spec that never reaches the changelog is finished work the next session cannot find.
|
|
58
|
+
- **Roadmap or planning docs**: the spec maps to a roadmap tier or planning item. Tick it here, never earlier in the run, and only when its artifact has run against real or fixture input and the output has been read. Otherwise leave it unticked and say so in the verdict.
|
|
59
|
+
- **The verdict itself is the user-facing summary**. Lead with what changed and why it matters, not with process narration. The human reading only this message should be able to judge the work.
|
|
60
|
+
|
|
61
|
+
Skip what does not apply and say so in one line. Silence reads as skipped work, a stated skip reads as a decision. Then present the Definition of Done checklist and the verdict, following `references/dod.md`.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Visual verification
|
|
2
|
+
|
|
3
|
+
Load this reference when the spec has `[visual-check]` criteria or criteria that name UI states, widths, or console cleanliness, and `conventions.md` declares a Preview command.
|
|
4
|
+
|
|
5
|
+
Before dispatching the verifier, start the declared preview and use the harness browser to reach every named state. Write `SPEC_DIR/verifications/visual.md` with the states reached, console errors and warnings quoted, keyboard reachability, widths checked, and any design token that differs from the declared value. Pass that path to the verifier.
|
|
6
|
+
|
|
7
|
+
The verifier has no browser of its own, so this orchestrator walk is the only first-hand visual evidence. If the harness has no browser, say so. The verifier then tries the project's visual-regression configuration, then an installed browser driver, and reports `UNVERIFIED` with the missing input if neither exists.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# check-converge.sh <spec-dir>: the converge pass, made mechanical (spec-kit's
|
|
3
|
+
# analyze/converge idea). After implementation, every task group's declared
|
|
4
|
+
# Files must have been touched somewhere on the spec branch since it diverged
|
|
5
|
+
# from the default branch. A group whose files never moved is done-drift: work
|
|
6
|
+
# marked complete that never landed, or that quietly became obsolete without a
|
|
7
|
+
# defer entry saying so.
|
|
8
|
+
#
|
|
9
|
+
# Deterministic, zero model calls. Same diagnostic envelope as
|
|
10
|
+
# validate-spec.sh:
|
|
11
|
+
# FAIL check-converge: <message>
|
|
12
|
+
# fix: <one actionable line>
|
|
13
|
+
# Exit 0 = converged (or nothing to check), 1 = findings, 2 = usage.
|
|
14
|
+
#
|
|
15
|
+
# Fails open when git context is missing (no repo, no default branch): an
|
|
16
|
+
# advisory convergence check must not brick closes on bare or detached setups
|
|
17
|
+
# (fail-open posture).
|
|
18
|
+
set -uo pipefail
|
|
19
|
+
|
|
20
|
+
arg="${1:-}"
|
|
21
|
+
if [[ -z "$arg" ]]; then
|
|
22
|
+
echo "Usage: $0 <spec-dir>" >&2
|
|
23
|
+
exit 2
|
|
24
|
+
fi
|
|
25
|
+
dir="$arg"
|
|
26
|
+
[[ -d "$dir" ]] || dir="$(dirname "$arg")"
|
|
27
|
+
# Resolve before any cd: the spec dir may be given relative to the caller.
|
|
28
|
+
plan="$(cd "$dir" 2>/dev/null && pwd)/spec.md"
|
|
29
|
+
if [[ ! -f "$plan" ]]; then
|
|
30
|
+
# No plan yet is not a finding: this runs at close, after Phase A wrote one.
|
|
31
|
+
exit 0
|
|
32
|
+
fi
|
|
33
|
+
|
|
34
|
+
cd "$dir" || exit 0
|
|
35
|
+
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
|
|
36
|
+
echo "note check-converge: not a git repository, convergence unverifiable here"
|
|
37
|
+
exit 0
|
|
38
|
+
fi
|
|
39
|
+
# All git queries anchor at the work-tree root: run from inside devos/specs/sx,
|
|
40
|
+
# `git ls-files --others` and `git diff` silently scope themselves to that
|
|
41
|
+
# subdirectory and report nothing for src/ work, which read as "group never
|
|
42
|
+
# touched" and false-failed every close.
|
|
43
|
+
top="$(git rev-parse --show-toplevel)"
|
|
44
|
+
|
|
45
|
+
base="$(git -C "$top" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')"
|
|
46
|
+
[[ -z "$base" ]] && for b in main master; do
|
|
47
|
+
git -C "$top" show-ref --verify --quiet "refs/heads/$b" && { base="$b"; break; }
|
|
48
|
+
done
|
|
49
|
+
if [[ -z "$base" ]] || ! git -C "$top" rev-parse --verify --quiet "$base" >/dev/null; then
|
|
50
|
+
echo "note check-converge: no default branch found, convergence unverifiable here"
|
|
51
|
+
exit 0
|
|
52
|
+
fi
|
|
53
|
+
|
|
54
|
+
tmp="$(mktemp)"
|
|
55
|
+
trap 'rm -f "$tmp"' EXIT
|
|
56
|
+
# Committed work on the branch, plus uncommitted/untracked state (a close can
|
|
57
|
+
# legitimately happen before the last commit). Paths come out work-tree-relative,
|
|
58
|
+
# which is exactly how the plan's **Files:** entries are written.
|
|
59
|
+
git -C "$top" diff --name-only "$base"...HEAD > "$tmp" 2>/dev/null || true
|
|
60
|
+
git -C "$top" ls-files --others --exclude-standard >> "$tmp" 2>/dev/null || true
|
|
61
|
+
git -C "$top" diff --name-only >> "$tmp" 2>/dev/null || true
|
|
62
|
+
|
|
63
|
+
# FILENAME, not FNR == NR: a branch that touched nothing leaves $tmp empty, awk
|
|
64
|
+
# never opens it, and FNR == NR would then match the plan and swallow it as the
|
|
65
|
+
# touched list, so the gate passes the one case it exists to catch.
|
|
66
|
+
findings=$(awk -v plan="$plan" '
|
|
67
|
+
# First file: one touched path per line.
|
|
68
|
+
FILENAME == ARGV[1] {
|
|
69
|
+
if ($0 != "") touched[$0] = 1
|
|
70
|
+
next
|
|
71
|
+
}
|
|
72
|
+
# Second file: the plan capsule.
|
|
73
|
+
function norm(t) {
|
|
74
|
+
if (t ~ /^[A-Z]$/) return index("ABCDEFGHIJKLMNOPQRSTUVWXYZ", t)
|
|
75
|
+
return t + 0
|
|
76
|
+
}
|
|
77
|
+
/^###[[:space:]]+Task[[:space:]]+Group([[:space:]]+|:)/ {
|
|
78
|
+
h = $0
|
|
79
|
+
# The separator may be whitespace or a colon. Requiring whitespace only meant
|
|
80
|
+
# "### Task Group: Parser" never matched this rule at all, so the group was
|
|
81
|
+
# not dropped after an identity lookup failed: it was never seen, and the
|
|
82
|
+
# gate exited 0 on a plan whose only group declared an untouched file.
|
|
83
|
+
sub(/^###[[:space:]]+Task[[:space:]]+Group([[:space:]]+|:)/, "", h)
|
|
84
|
+
sub(/^[[:space:]]*:/, "", h)
|
|
85
|
+
sub(/[^0-9A-Za-z].*$/, "", h)
|
|
86
|
+
cur = norm(h)
|
|
87
|
+
if (cur > 0) {
|
|
88
|
+
if (!(cur in known)) { known[cur] = 1; label[cur] = h }
|
|
89
|
+
} else if (!($0 in unnumbered)) {
|
|
90
|
+
# A header with no leading digit and not the pre-0.8.6 single-letter
|
|
91
|
+
# form has no identity, so there is no group to attribute declared
|
|
92
|
+
# files to. Record the header and report it rather than dropping it.
|
|
93
|
+
unnumbered[$0] = 1
|
|
94
|
+
unnumbered_list = unnumbered_list $0 "\n"
|
|
95
|
+
}
|
|
96
|
+
next
|
|
97
|
+
}
|
|
98
|
+
cur > 0 && /^\*\*Files:\*\*/ {
|
|
99
|
+
n = split($0, part, "`")
|
|
100
|
+
for (i = 2; i <= n; i += 2) if (part[i] != "") files[cur] = files[cur] part[i] "\n"
|
|
101
|
+
next
|
|
102
|
+
}
|
|
103
|
+
END {
|
|
104
|
+
n = split(unnumbered_list, uhdr, "\n")
|
|
105
|
+
for (i = 1; i <= n; i++) {
|
|
106
|
+
if (uhdr[i] == "") continue
|
|
107
|
+
printf "FAIL check-converge: task group '%s' has no resolvable group number, so its declared files were never checked\n", uhdr[i]
|
|
108
|
+
}
|
|
109
|
+
for (g in known) {
|
|
110
|
+
if (!(g in files)) continue
|
|
111
|
+
hit = 0
|
|
112
|
+
listed = ""
|
|
113
|
+
n = split(files[g], paths, "\n")
|
|
114
|
+
for (i = 1; i <= n; i++) {
|
|
115
|
+
p = paths[i]
|
|
116
|
+
gsub(/[[:space:]]/, "", p)
|
|
117
|
+
if (p == "") continue
|
|
118
|
+
listed = listed (listed == "" ? "" : ", ") p
|
|
119
|
+
if (p in touched) { hit = 1; break }
|
|
120
|
+
if (p ~ /\/$/ || p !~ /\./) {
|
|
121
|
+
# Directory entries match descendants, not arbitrary prefixes:
|
|
122
|
+
# `src` owns `src/file.ts`, but not `src2/file.ts`.
|
|
123
|
+
for (t in touched) {
|
|
124
|
+
if (t == p || (p ~ /\/$/ && index(t, p) == 1) || \
|
|
125
|
+
(p !~ /\/$/ && index(t, p "/") == 1)) {
|
|
126
|
+
hit = 1
|
|
127
|
+
break
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
if (!hit)
|
|
133
|
+
# The declared files are stored newline-joined, and the awk printf
|
|
134
|
+
# below does not translate a newline held in an argument, so
|
|
135
|
+
# interpolating that string broke the documented one-line envelope: a
|
|
136
|
+
# group with two files printed three lines with a bare ") declares
|
|
137
|
+
# files" tail. `listed` is the same set joined with a comma.
|
|
138
|
+
printf "FAIL check-converge: Task Group %s (%s) declares files but none were touched on this branch\n", label[g], listed
|
|
139
|
+
}
|
|
140
|
+
}' "$tmp" "$plan")
|
|
141
|
+
|
|
142
|
+
if [[ -n "$findings" ]]; then
|
|
143
|
+
echo "$findings"
|
|
144
|
+
echo " fix: land the group's work, or record why it died - ABANDON in gates.md plus one defer line in devos/deferred.md. Done-drift is not a close state."
|
|
145
|
+
exit 1
|
|
146
|
+
fi
|
|
147
|
+
exit 0
|