@tduyng/pi-devos 0.0.0-stage → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1421 -0
- package/LICENSE +201 -0
- package/README.md +206 -2
- package/package.json +44 -4
- package/plugins/devos/agents/reader.md +27 -0
- package/plugins/devos/agents/verifier.md +155 -0
- package/plugins/devos/pi/extension/devos.ts +605 -0
- package/plugins/devos/scripts/check-evidence-router.sh +140 -0
- package/plugins/devos/scripts/evidence-router.py +254 -0
- package/plugins/devos/scripts/gates/check-dod-core.sh +285 -0
- package/plugins/devos/scripts/gates/check-dod.sh +38 -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 +104 -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 +141 -0
- package/plugins/devos/scripts/gates/run-gate.sh +148 -0
- package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
- package/plugins/devos/scripts/gates/spec-template-check.py +152 -0
- package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
- package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
- package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
- package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
- package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
- package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
- package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
- package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
- package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
- package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
- package/plugins/devos/scripts/gates/test-gates.sh +76 -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/frame/SKILL.md +54 -0
- package/plugins/devos/skills/frame/references/template.md +115 -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 +37 -0
- package/plugins/devos/skills/implement/references/implement.md +54 -0
- package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
- package/plugins/devos/skills/implement/references/plan.md +142 -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 +62 -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 +220 -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/review/SKILL.md +54 -0
- package/plugins/devos/skills/review/references/comments.md +13 -0
- package/plugins/devos/skills/review/references/gaps.md +26 -0
- package/plugins/devos/skills/review/references/reviewer.md +124 -0
- package/plugins/devos/skills/review/references/routing.md +35 -0
- package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
- package/plugins/devos/skills/review/scripts/prepare.py +763 -0
- package/plugins/devos/skills/spec/SKILL.md +57 -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 +128 -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 +259 -0
- package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
- package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
|
@@ -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,62 @@
|
|
|
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, inside the plan's scope (`references/implement.md` section 3).
|
|
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.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, git diff main...[spec-name] shows them`). 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
|
+
- **Pull request text**: when the work sits on a branch for review, write `devos/specs/archive/[spec-name]/pr.md` and show it. Fill the project's PR template when one exists (`.github/pull_request_template.md` or a `PULL_REQUEST_TEMPLATE` folder), else three short parts: what changed and why in the reviewer's words, how it was verified (the commands and counts from `verification.md`), and what is deliberately left out (the deferred lines). It is the reviewer's first read, so the output boundary applies: no `SC-n`, no spec path, no framework name.
|
|
60
|
+
- **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.
|
|
61
|
+
|
|
62
|
+
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
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# equivalence-check.sh: the judge for a behavior-preserving change.
|
|
3
|
+
#
|
|
4
|
+
# A behavior-preserving change is proven by running the same judgment against
|
|
5
|
+
# the before tree and the after tree and comparing what came back. This script
|
|
6
|
+
# is that comparison, so the proof is a command with an exit status rather than
|
|
7
|
+
# a claim in prose.
|
|
8
|
+
#
|
|
9
|
+
# Two rules make the verdict worth something:
|
|
10
|
+
#
|
|
11
|
+
# - A judge that errored proves nothing. A command that fails on the before
|
|
12
|
+
# tree makes the whole comparison unproven, not equivalent, and a red
|
|
13
|
+
# baseline is a finding of its own.
|
|
14
|
+
# - A judge that has never seen a break does not know what a break looks
|
|
15
|
+
# like. `--self-test` runs the judge against a tree that is deliberately
|
|
16
|
+
# broken and fails when the judge calls it equivalent.
|
|
17
|
+
#
|
|
18
|
+
# Usage:
|
|
19
|
+
# equivalence-check.sh --before DIR --after DIR [--cmd CMD]
|
|
20
|
+
# [--before-cmd CMD --after-cmd CMD] [--label NAME]
|
|
21
|
+
# equivalence-check.sh --self-test
|
|
22
|
+
#
|
|
23
|
+
# Diagnostic envelope (shared by DevOS check scripts):
|
|
24
|
+
# FAIL <check>: <message>
|
|
25
|
+
# fix: <one actionable line>
|
|
26
|
+
# Exit 0 = equivalent, 1 = not equivalent, 2 = usage or unproven.
|
|
27
|
+
set -u
|
|
28
|
+
|
|
29
|
+
die() { echo "FAIL equivalence-check: $1" >&2; echo " fix: $2" >&2; exit 2; }
|
|
30
|
+
|
|
31
|
+
before=""
|
|
32
|
+
after=""
|
|
33
|
+
before_cmd=""
|
|
34
|
+
after_cmd=""
|
|
35
|
+
label="comparison"
|
|
36
|
+
self_test=0
|
|
37
|
+
|
|
38
|
+
while [[ $# -gt 0 ]]; do
|
|
39
|
+
case "$1" in
|
|
40
|
+
--before) before="${2:-}"; shift 2 ;;
|
|
41
|
+
--after) after="${2:-}"; shift 2 ;;
|
|
42
|
+
--cmd) before_cmd="${2:-}"; after_cmd="${2:-}"; shift 2 ;;
|
|
43
|
+
--before-cmd) before_cmd="${2:-}"; shift 2 ;;
|
|
44
|
+
--after-cmd) after_cmd="${2:-}"; shift 2 ;;
|
|
45
|
+
--label) label="${2:-}"; shift 2 ;;
|
|
46
|
+
--self-test) self_test=1; shift ;;
|
|
47
|
+
-h|--help) sed -n '2,28p' "$0"; exit 0 ;;
|
|
48
|
+
*) die "unknown argument: $1" "use --before, --after, --cmd and --self-test as listed in the header" ;;
|
|
49
|
+
esac
|
|
50
|
+
done
|
|
51
|
+
|
|
52
|
+
SELF="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
|
|
53
|
+
|
|
54
|
+
# Run one command in one tree, capturing combined output and the exit status.
|
|
55
|
+
# The output file is left behind when the caller asked to see a diff.
|
|
56
|
+
run_side() {
|
|
57
|
+
local dir="$1" cmd="$2" out="$3"
|
|
58
|
+
( cd "$dir" && eval "$cmd" ) > "$out" 2>&1
|
|
59
|
+
echo $?
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
# $1 before dir, $2 after dir, $3 before cmd, $4 after cmd, $5 label.
|
|
63
|
+
# Prints the verdict, returns 0 equivalent, 1 not equivalent, 2 unproven.
|
|
64
|
+
judge() {
|
|
65
|
+
local bdir="$1" adir="$2" bcmd="$3" acmd="$4" lbl="$5"
|
|
66
|
+
local tmp bo ao brc arc
|
|
67
|
+
tmp="$(mktemp -d)"
|
|
68
|
+
bo="$tmp/before.out"; ao="$tmp/after.out"
|
|
69
|
+
brc="$(run_side "$bdir" "$bcmd" "$bo")"
|
|
70
|
+
arc="$(run_side "$adir" "$acmd" "$ao")"
|
|
71
|
+
local elapsed=$SECONDS
|
|
72
|
+
|
|
73
|
+
if [[ "$brc" != "0" ]]; then
|
|
74
|
+
echo "UNPROVEN equivalence-check: $lbl failed on the before tree (exit $brc), so the comparison proves nothing"
|
|
75
|
+
echo " fix: the before tree must be green before an equivalence claim is about anything"
|
|
76
|
+
tail -n 5 "$bo" | sed 's/^/ | /'
|
|
77
|
+
rm -rf "$tmp"
|
|
78
|
+
return 2
|
|
79
|
+
fi
|
|
80
|
+
if [[ "$arc" != "0" ]]; then
|
|
81
|
+
echo "FAIL equivalence-check: $lbl fails on the after tree (exit $arc) and passed on the before tree"
|
|
82
|
+
echo " fix: the change broke the judgment; fix the code, or the change is not behavior-preserving"
|
|
83
|
+
tail -n 5 "$ao" | sed 's/^/ | /'
|
|
84
|
+
rm -rf "$tmp"
|
|
85
|
+
return 1
|
|
86
|
+
fi
|
|
87
|
+
if ! cmp -s "$bo" "$ao"; then
|
|
88
|
+
echo "FAIL equivalence-check: $lbl output differs between the trees"
|
|
89
|
+
echo " fix: the difference below is the behavior that moved; restore it or declare the change"
|
|
90
|
+
diff -u "$bo" "$ao" 2>/dev/null | head -n 30 | sed 's/^/ | /'
|
|
91
|
+
rm -rf "$tmp"
|
|
92
|
+
return 1
|
|
93
|
+
fi
|
|
94
|
+
echo "PASS equivalence-check: $lbl is identical in both trees (judged in ${elapsed}s)"
|
|
95
|
+
rm -rf "$tmp"
|
|
96
|
+
return 0
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
if [[ "$self_test" -eq 1 ]]; then
|
|
100
|
+
tmp="$(mktemp -d)"
|
|
101
|
+
trap 'rm -rf "$tmp"' EXIT
|
|
102
|
+
mkdir -p "$tmp/good" "$tmp/broken" "$tmp/red"
|
|
103
|
+
printf '#!/bin/sh\necho "case: ok"\n' > "$tmp/good/judge.sh"
|
|
104
|
+
printf '#!/bin/sh\necho "case: broken"\n' > "$tmp/broken/judge.sh"
|
|
105
|
+
printf '#!/bin/sh\necho "case: boom"\nexit 1\n' > "$tmp/red/judge.sh"
|
|
106
|
+
chmod +x "$tmp"/*/judge.sh
|
|
107
|
+
bad=0
|
|
108
|
+
check() { # $1 expected rc, $2 label, rest: args
|
|
109
|
+
local want="$1" name="$2"; shift 2
|
|
110
|
+
local got=0
|
|
111
|
+
"$SELF" "$@" > "$tmp/out" 2>&1 || got=$?
|
|
112
|
+
if [[ "$got" != "$want" ]]; then
|
|
113
|
+
echo "FAIL equivalence-check: the judge called '$name' exit $got, expected $want"
|
|
114
|
+
echo " fix: a judge that misses a break cannot certify anything; fix the judge before trusting a verdict"
|
|
115
|
+
sed 's/^/ | /' "$tmp/out"
|
|
116
|
+
bad=1
|
|
117
|
+
else
|
|
118
|
+
echo "ok self-test: $name is judged exit $got"
|
|
119
|
+
fi
|
|
120
|
+
}
|
|
121
|
+
check 0 "two identical trees" --before "$tmp/good" --after "$tmp/good" --cmd "./judge.sh"
|
|
122
|
+
check 1 "a broken tree against a good one" --before "$tmp/good" --after "$tmp/broken" --cmd "./judge.sh"
|
|
123
|
+
check 1 "a tree that fails where the other passed" --before "$tmp/good" --after "$tmp/red" --cmd "./judge.sh"
|
|
124
|
+
check 2 "a red baseline on both sides" --before "$tmp/red" --after "$tmp/red" --cmd "./judge.sh"
|
|
125
|
+
if [[ "$bad" -ne 0 ]]; then
|
|
126
|
+
exit 1
|
|
127
|
+
fi
|
|
128
|
+
echo "PASS equivalence-check: the judge catches every break it was shown"
|
|
129
|
+
exit 0
|
|
130
|
+
fi
|
|
131
|
+
|
|
132
|
+
[[ -n "$before" && -n "$after" ]] \
|
|
133
|
+
|| die "--before and --after are required" "point them at the two trees the judgment runs in"
|
|
134
|
+
[[ -d "$before" ]] || die "before tree not found: $before" "give the directory holding the code before the change"
|
|
135
|
+
[[ -d "$after" ]] || die "after tree not found: $after" "give the directory holding the code after the change"
|
|
136
|
+
[[ -n "$before_cmd" && -n "$after_cmd" ]] \
|
|
137
|
+
|| die "no command to run" "pass --cmd for one command in both trees, or --before-cmd and --after-cmd when the two stacks differ"
|
|
138
|
+
|
|
139
|
+
judge "$before" "$after" "$before_cmd" "$after_cmd" "$label"
|
|
140
|
+
exit $?
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# manifest-queue.sh: the unit queue for a behavior-preserving change at scale.
|
|
3
|
+
#
|
|
4
|
+
# The manifest is the unit list, one row per unit: `source<TAB>target`. A unit
|
|
5
|
+
# is done when its target exists and carries content, so the filesystem holds
|
|
6
|
+
# the state and a run resumes for free after a crash, a halt, or a session
|
|
7
|
+
# ending. Nothing else tracks progress, so nothing else can disagree with it.
|
|
8
|
+
#
|
|
9
|
+
# Usage:
|
|
10
|
+
# manifest-queue.sh init --from-root DIR --to DIR --list FILE --out FILE
|
|
11
|
+
# manifest-queue.sh status --manifest FILE
|
|
12
|
+
# manifest-queue.sh next --manifest FILE [--batch N]
|
|
13
|
+
# manifest-queue.sh verify --manifest FILE
|
|
14
|
+
#
|
|
15
|
+
# Diagnostic envelope (shared by DevOS check scripts):
|
|
16
|
+
# FAIL <check>: <message>
|
|
17
|
+
# fix: <one actionable line>
|
|
18
|
+
# Exit 0 = ok, 1 = findings, 2 = usage.
|
|
19
|
+
set -u
|
|
20
|
+
fail=0
|
|
21
|
+
finding() { echo "FAIL manifest-queue: $1"; echo " fix: $2"; fail=1; }
|
|
22
|
+
|
|
23
|
+
die() { echo "FAIL manifest-queue: $1" >&2; echo " fix: $2" >&2; exit 2; }
|
|
24
|
+
|
|
25
|
+
cmd=""
|
|
26
|
+
manifest=""
|
|
27
|
+
from_root=""
|
|
28
|
+
to_root=""
|
|
29
|
+
list=""
|
|
30
|
+
out=""
|
|
31
|
+
batch=10
|
|
32
|
+
count=""
|
|
33
|
+
units=0
|
|
34
|
+
|
|
35
|
+
while [[ $# -gt 0 ]]; do
|
|
36
|
+
case "$1" in
|
|
37
|
+
init|status|next|verify|slice) cmd="$1"; shift ;;
|
|
38
|
+
--manifest) manifest="${2:-}"; shift 2 ;;
|
|
39
|
+
--from-root) from_root="${2:-}"; shift 2 ;;
|
|
40
|
+
--to) to_root="${2:-}"; shift 2 ;;
|
|
41
|
+
--list) list="${2:-}"; shift 2 ;;
|
|
42
|
+
--out) out="${2:-}"; shift 2 ;;
|
|
43
|
+
--batch) batch="${2:-}"; shift 2 ;;
|
|
44
|
+
--count) count="${2:-}"; shift 2 ;;
|
|
45
|
+
-h|--help) sed -n '2,20p' "$0"; exit 0 ;;
|
|
46
|
+
*) die "unknown argument: $1" "use init, status, next, verify or slice with the flags listed in the header" ;;
|
|
47
|
+
esac
|
|
48
|
+
done
|
|
49
|
+
[[ -n "$cmd" ]] || die "no command given" "pass one of: init, status, next, verify"
|
|
50
|
+
|
|
51
|
+
# A unit carries content when it is a non-empty file, or a directory with
|
|
52
|
+
# something in it. An empty target is the failure this queue exists to catch:
|
|
53
|
+
# a worker that touched the file and moved on.
|
|
54
|
+
carries_content() {
|
|
55
|
+
local p="$1"
|
|
56
|
+
[[ -e "$p" ]] || return 1
|
|
57
|
+
if [[ -d "$p" ]]; then
|
|
58
|
+
[[ -n "$(find "$p" -mindepth 1 -print -quit 2>/dev/null)" ]]
|
|
59
|
+
else
|
|
60
|
+
[[ -s "$p" ]]
|
|
61
|
+
fi
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
read_manifest() {
|
|
65
|
+
local f="$1"
|
|
66
|
+
[[ -f "$f" ]] || die "manifest not found: $f" "write it with: manifest-queue.sh init --from-root DIR --to DIR --list FILE --out $f"
|
|
67
|
+
local header
|
|
68
|
+
header="$(head -1 "$f" | tr -d '\r')"
|
|
69
|
+
[[ "$header" == "$(printf 'source\ttarget')" ]] \
|
|
70
|
+
|| die "manifest header must be 'source<TAB>target', got: $header" "the header is the contract: one source path and one target path per row"
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
case "$cmd" in
|
|
74
|
+
init)
|
|
75
|
+
[[ -n "$from_root" && -n "$to_root" && -n "$list" && -n "$out" ]] \
|
|
76
|
+
|| die "init needs --from-root, --to, --list and --out" "example: manifest-queue.sh init --from-root legacy --to modernized --list units.txt --out devos/specs/x/manifest.tsv"
|
|
77
|
+
[[ -f "$list" ]] || die "list not found: $list" "write one source path per line, relative to --from-root"
|
|
78
|
+
mkdir -p "$(dirname "$out")" || die "cannot create $(dirname "$out")" "create the spec folder first"
|
|
79
|
+
{
|
|
80
|
+
printf 'source\ttarget\n'
|
|
81
|
+
while IFS= read -r rel || [[ -n "$rel" ]]; do
|
|
82
|
+
rel="${rel%%$'\r'}"
|
|
83
|
+
[[ -n "$rel" ]] || continue
|
|
84
|
+
case "$rel" in \#*) continue ;; esac
|
|
85
|
+
printf '%s/%s\t%s/%s\n' "$from_root" "$rel" "$to_root" "$rel"
|
|
86
|
+
done < "$list"
|
|
87
|
+
} > "$out"
|
|
88
|
+
units=$(($(wc -l < "$out") - 1))
|
|
89
|
+
echo "wrote $out ($units units)"
|
|
90
|
+
;;
|
|
91
|
+
|
|
92
|
+
status)
|
|
93
|
+
[[ -n "$manifest" ]] || die "status needs --manifest" "pass the manifest path"
|
|
94
|
+
read_manifest "$manifest"
|
|
95
|
+
total=0; done=0
|
|
96
|
+
dirs="$(mktemp)"
|
|
97
|
+
while IFS=$'\t' read -r src tgt; do
|
|
98
|
+
[[ "$src" == "source" ]] && continue
|
|
99
|
+
[[ -n "$src" ]] || continue
|
|
100
|
+
total=$((total + 1))
|
|
101
|
+
if carries_content "$tgt"; then
|
|
102
|
+
done=$((done + 1))
|
|
103
|
+
else
|
|
104
|
+
d="$(dirname "$src")"
|
|
105
|
+
printf '%s\n' "$d" >> "$dirs"
|
|
106
|
+
fi
|
|
107
|
+
done < "$manifest"
|
|
108
|
+
pct=0
|
|
109
|
+
[[ "$total" -gt 0 ]] && pct=$((done * 100 / total))
|
|
110
|
+
echo "$done/$total done (${pct}%)"
|
|
111
|
+
if [[ -s "$dirs" ]]; then
|
|
112
|
+
sort "$dirs" | uniq -c | sort -rn | while read -r n d; do
|
|
113
|
+
echo " $d: $n pending"
|
|
114
|
+
done
|
|
115
|
+
fi
|
|
116
|
+
rm -f "$dirs"
|
|
117
|
+
;;
|
|
118
|
+
|
|
119
|
+
next)
|
|
120
|
+
[[ -n "$manifest" ]] || die "next needs --manifest" "pass the manifest path"
|
|
121
|
+
read_manifest "$manifest"
|
|
122
|
+
n=0
|
|
123
|
+
while IFS=$'\t' read -r src tgt; do
|
|
124
|
+
[[ "$src" == "source" ]] && continue
|
|
125
|
+
[[ -n "$src" ]] || continue
|
|
126
|
+
carries_content "$tgt" && continue
|
|
127
|
+
printf '%s\t%s\n' "$src" "$tgt"
|
|
128
|
+
n=$((n + 1))
|
|
129
|
+
[[ "$n" -ge "$batch" ]] && break
|
|
130
|
+
done < "$manifest"
|
|
131
|
+
;;
|
|
132
|
+
|
|
133
|
+
slice)
|
|
134
|
+
# A phase of a port takes the first units of the manifest, and the manifest
|
|
135
|
+
# is in dependency order, so a slice is closed under the dependencies: every
|
|
136
|
+
# unit a unit needs is in the slice or in an earlier phase.
|
|
137
|
+
[[ -n "$manifest" && -n "$out" && -n "$count" ]] \
|
|
138
|
+
|| die "slice needs --manifest, --count and --out" "example: manifest-queue.sh slice --manifest SPEC/manifest.tsv --count 40 --out SPEC/phase-1.tsv"
|
|
139
|
+
read_manifest "$manifest"
|
|
140
|
+
[[ "$count" =~ ^[0-9]+$ ]] || die "count must be a number, got: $count" "pass how many units the phase holds"
|
|
141
|
+
{
|
|
142
|
+
printf 'source\ttarget\n'
|
|
143
|
+
taken=0
|
|
144
|
+
while IFS=$'\t' read -r src tgt; do
|
|
145
|
+
[[ "$src" == "source" ]] && continue
|
|
146
|
+
[[ -n "$src" ]] || continue
|
|
147
|
+
if [[ "$taken" -ge "$count" ]]; then
|
|
148
|
+
break
|
|
149
|
+
fi
|
|
150
|
+
printf '%s\t%s\n' "$src" "$tgt"
|
|
151
|
+
taken=$((taken + 1))
|
|
152
|
+
done < "$manifest"
|
|
153
|
+
} > "$out"
|
|
154
|
+
units=$(($(wc -l < "$out") - 1))
|
|
155
|
+
echo "wrote $out ($units units of the first $count)"
|
|
156
|
+
;;
|
|
157
|
+
|
|
158
|
+
verify)
|
|
159
|
+
[[ -n "$manifest" ]] || die "verify needs --manifest" "pass the manifest path"
|
|
160
|
+
read_manifest "$manifest"
|
|
161
|
+
empty=0; missing=0
|
|
162
|
+
while IFS=$'\t' read -r src tgt; do
|
|
163
|
+
[[ "$src" == "source" ]] && continue
|
|
164
|
+
[[ -n "$src" ]] || continue
|
|
165
|
+
if [[ -z "$tgt" ]]; then
|
|
166
|
+
finding "a row names no target: $src" "every row names a source and a target"
|
|
167
|
+
missing=$((missing + 1))
|
|
168
|
+
continue
|
|
169
|
+
fi
|
|
170
|
+
if [[ -e "$tgt" ]] && ! carries_content "$tgt"; then
|
|
171
|
+
finding "target exists but carries nothing: $tgt" "write the unit, or drop the row from the manifest"
|
|
172
|
+
empty=$((empty + 1))
|
|
173
|
+
fi
|
|
174
|
+
if [[ ! -e "$src" ]]; then
|
|
175
|
+
finding "source is missing: $src" "the unit points at nothing; fix the row or drop it"
|
|
176
|
+
missing=$((missing + 1))
|
|
177
|
+
fi
|
|
178
|
+
done < "$manifest"
|
|
179
|
+
if [[ "$empty" -eq 0 && "$missing" -eq 0 ]]; then
|
|
180
|
+
echo "PASS manifest-queue: every unit has a source and a target that carries content"
|
|
181
|
+
fi
|
|
182
|
+
;;
|
|
183
|
+
esac
|
|
184
|
+
|
|
185
|
+
exit $fail
|