devrites 4.0.12 → 4.1.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 +8 -0
- package/README.md +3 -3
- package/docs/architecture.md +4 -4
- package/docs/command-map.md +4 -3
- package/docs/flow.md +2 -1
- package/docs/orchestration.md +45 -4
- package/docs/skills.md +4 -3
- package/engine/internal/devritespaths/paths.go +5 -4
- package/engine/internal/hostpack/hostpack.go +9 -4
- package/engine/internal/hostpack/hostpack_test.go +16 -7
- package/engine/internal/install/install_test.go +5 -0
- package/pack/.claude/agents/devrites-code-reviewer.md +6 -1
- package/pack/.claude/agents/devrites-plan-drafter.md +5 -0
- package/pack/.claude/agents/devrites-plan-reviewer.md +6 -0
- package/pack/.claude/agents/devrites-proof-runner.md +7 -1
- package/pack/.claude/agents/devrites-retrospector.md +21 -25
- package/pack/.claude/agents/devrites-security-auditor.md +7 -3
- package/pack/.claude/agents/devrites-slice-wright.md +30 -4
- package/pack/.claude/agents/devrites-spec-reviewer.md +5 -0
- package/pack/.claude/agents/devrites-strategy-reviewer.md +3 -4
- package/pack/.claude/agents/devrites-test-analyst.md +5 -0
- package/pack/.claude/skills/devrites-debug-recovery/SKILL.md +12 -16
- package/pack/.claude/skills/devrites-debug-recovery/reference/build-the-loop.md +11 -14
- package/pack/.claude/skills/devrites-doubt/SKILL.md +3 -4
- package/pack/.claude/skills/devrites-frontend-craft/reference/reuse-first.md +3 -4
- package/pack/.claude/skills/devrites-lib/reference/standards/README.md +5 -1
- package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md +33 -8
- package/pack/.claude/skills/devrites-lib/reference/standards/agents.md +11 -3
- package/pack/.claude/skills/devrites-lib/reference/standards/ci-cd.md +19 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/code-review.md +1 -1
- package/pack/.claude/skills/devrites-lib/reference/standards/core.md +5 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/data-integrity.md +95 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/developer-experience.md +5 -5
- package/pack/.claude/skills/devrites-lib/reference/standards/documentation.md +28 -29
- package/pack/.claude/skills/devrites-lib/reference/standards/edge-case-trace.md +70 -10
- package/pack/.claude/skills/devrites-lib/reference/standards/integration-reliability.md +79 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/loop-operations.md +85 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/observability.md +10 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/patterns.md +20 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/repository-topology.md +73 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/security-checklist.md +6 -2
- package/pack/.claude/skills/devrites-lib/reference/standards/security.md +51 -16
- package/pack/.claude/skills/devrites-lib/reference/standards/skill-authoring.md +35 -40
- package/pack/.claude/skills/devrites-lib/reference/standards/test-proof-checklist.md +4 -0
- package/pack/.claude/skills/devrites-lib/reference/standards/testing.md +51 -6
- package/pack/.claude/skills/rite/SKILL.md +2 -0
- package/pack/.claude/skills/rite-adopt/SKILL.md +8 -10
- package/pack/.claude/skills/rite-adopt/reference/adoption.md +13 -15
- package/pack/.claude/skills/rite-autocomplete/SKILL.md +18 -11
- package/pack/.claude/skills/rite-autocomplete/reference/loop.md +29 -6
- package/pack/.claude/skills/rite-autocomplete/reference/stop-conditions.md +7 -0
- package/pack/.claude/skills/rite-build/SKILL.md +7 -1
- package/pack/.claude/skills/rite-build/reference/phase-contract.md +6 -1
- package/pack/.claude/skills/rite-build/reference/wright-dispatch.md +37 -4
- package/pack/.claude/skills/rite-clarify/SKILL.md +3 -2
- package/pack/.claude/skills/rite-converge/SKILL.md +4 -2
- package/pack/.claude/skills/rite-converge/reference/convergence-assessment.md +8 -4
- package/pack/.claude/skills/rite-customize/SKILL.md +16 -18
- package/pack/.claude/skills/rite-define/SKILL.md +60 -62
- package/pack/.claude/skills/rite-define/reference/plan-template.md +88 -71
- package/pack/.claude/skills/rite-explain/SKILL.md +2 -1
- package/pack/.claude/skills/rite-learn/SKILL.md +28 -32
- package/pack/.claude/skills/rite-plan/SKILL.md +42 -45
- package/pack/.claude/skills/rite-plan/reference/dependency-graph.md +11 -2
- package/pack/.claude/skills/rite-plan/reference/task-breakdown.md +2 -0
- package/pack/.claude/skills/rite-polish/reference/adr-promotion.md +7 -7
- package/pack/.claude/skills/rite-pressure-test/SKILL.md +24 -31
- package/pack/.claude/skills/rite-prove/SKILL.md +12 -15
- package/pack/.claude/skills/rite-prove/reference/acceptance-proof.md +28 -0
- package/pack/.claude/skills/rite-review/SKILL.md +5 -4
- package/pack/.claude/skills/rite-review/reference/five-axis-review.md +6 -0
- package/pack/.claude/skills/rite-review/reference/security-review.md +7 -2
- package/pack/.claude/skills/rite-seal/reference/final-evidence.md +3 -0
- package/pack/.claude/skills/rite-seal/reference/risk-and-rollback.md +19 -4
- package/pack/.claude/skills/rite-ship/reference/rollout.md +62 -43
- package/pack/.claude/skills/rite-spec/SKILL.md +8 -1
- package/pack/.claude/skills/rite-spec/reference/ai-spec-template.md +13 -6
- package/pack/.claude/skills/rite-spec/reference/spec-checklists.md +14 -2
- package/pack/.claude/skills/rite-spec/reference/spec-template.md +33 -4
- package/pack/.claude/skills/rite-temper/SKILL.md +5 -1
- package/pack/.claude/skills/rite-vet/SKILL.md +8 -8
- package/pack/.claude/skills/rite-vet/reference/artifacts.md +5 -3
- package/pack/.claude/skills/rite-vet/reference/review-axes.md +67 -77
- package/pack/.claude/skills/rite-watch-pr/SKILL.md +85 -0
- package/pack/.claude/skills/rite-zoom-out/SKILL.md +4 -5
- package/pack/.claude/workflows/devrites-readonly-review.js +194 -0
- package/pack/generated/README.md +1 -1
- package/pack/generated/claude/agents/devrites-code-reviewer.md +6 -1
- package/pack/generated/claude/agents/devrites-plan-drafter.md +5 -0
- package/pack/generated/claude/agents/devrites-plan-reviewer.md +6 -0
- package/pack/generated/claude/agents/devrites-proof-runner.md +7 -1
- package/pack/generated/claude/agents/devrites-retrospector.md +21 -25
- package/pack/generated/claude/agents/devrites-security-auditor.md +7 -3
- package/pack/generated/claude/agents/devrites-slice-wright.md +30 -4
- package/pack/generated/claude/agents/devrites-spec-reviewer.md +5 -0
- package/pack/generated/claude/agents/devrites-strategy-reviewer.md +3 -4
- package/pack/generated/claude/agents/devrites-test-analyst.md +5 -0
- package/pack/generated/claude/skills/devrites-debug-recovery/SKILL.md +12 -16
- package/pack/generated/claude/skills/devrites-debug-recovery/reference/build-the-loop.md +11 -14
- package/pack/generated/claude/skills/devrites-doubt/SKILL.md +3 -4
- package/pack/generated/claude/skills/devrites-frontend-craft/reference/reuse-first.md +3 -4
- package/pack/generated/claude/skills/devrites-lib/reference/standards/README.md +5 -1
- package/pack/generated/claude/skills/devrites-lib/reference/standards/afk-hitl.md +33 -8
- package/pack/generated/claude/skills/devrites-lib/reference/standards/agents.md +11 -3
- package/pack/generated/claude/skills/devrites-lib/reference/standards/ci-cd.md +19 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/code-review.md +1 -1
- package/pack/generated/claude/skills/devrites-lib/reference/standards/core.md +5 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/data-integrity.md +95 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/developer-experience.md +5 -5
- package/pack/generated/claude/skills/devrites-lib/reference/standards/documentation.md +28 -29
- package/pack/generated/claude/skills/devrites-lib/reference/standards/edge-case-trace.md +70 -10
- package/pack/generated/claude/skills/devrites-lib/reference/standards/integration-reliability.md +79 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/loop-operations.md +85 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/observability.md +10 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/patterns.md +20 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/repository-topology.md +73 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/security-checklist.md +6 -2
- package/pack/generated/claude/skills/devrites-lib/reference/standards/security.md +51 -16
- package/pack/generated/claude/skills/devrites-lib/reference/standards/skill-authoring.md +35 -40
- package/pack/generated/claude/skills/devrites-lib/reference/standards/test-proof-checklist.md +4 -0
- package/pack/generated/claude/skills/devrites-lib/reference/standards/testing.md +51 -6
- package/pack/generated/claude/skills/rite/SKILL.md +2 -0
- package/pack/generated/claude/skills/rite-adopt/SKILL.md +8 -10
- package/pack/generated/claude/skills/rite-adopt/reference/adoption.md +13 -15
- package/pack/generated/claude/skills/rite-autocomplete/SKILL.md +18 -11
- package/pack/generated/claude/skills/rite-autocomplete/reference/loop.md +29 -6
- package/pack/generated/claude/skills/rite-autocomplete/reference/stop-conditions.md +7 -0
- package/pack/generated/claude/skills/rite-build/SKILL.md +7 -1
- package/pack/generated/claude/skills/rite-build/reference/phase-contract.md +6 -1
- package/pack/generated/claude/skills/rite-build/reference/wright-dispatch.md +37 -4
- package/pack/generated/claude/skills/rite-clarify/SKILL.md +3 -2
- package/pack/generated/claude/skills/rite-converge/SKILL.md +4 -2
- package/pack/generated/claude/skills/rite-converge/reference/convergence-assessment.md +8 -4
- package/pack/generated/claude/skills/rite-customize/SKILL.md +16 -18
- package/pack/generated/claude/skills/rite-define/SKILL.md +60 -62
- package/pack/generated/claude/skills/rite-define/reference/plan-template.md +88 -71
- package/pack/generated/claude/skills/rite-explain/SKILL.md +2 -1
- package/pack/generated/claude/skills/rite-learn/SKILL.md +28 -32
- package/pack/generated/claude/skills/rite-plan/SKILL.md +42 -45
- package/pack/generated/claude/skills/rite-plan/reference/dependency-graph.md +11 -2
- package/pack/generated/claude/skills/rite-plan/reference/task-breakdown.md +2 -0
- package/pack/generated/claude/skills/rite-polish/reference/adr-promotion.md +7 -7
- package/pack/generated/claude/skills/rite-pressure-test/SKILL.md +24 -31
- package/pack/generated/claude/skills/rite-prove/SKILL.md +12 -15
- package/pack/generated/claude/skills/rite-prove/reference/acceptance-proof.md +28 -0
- package/pack/generated/claude/skills/rite-review/SKILL.md +5 -4
- package/pack/generated/claude/skills/rite-review/reference/five-axis-review.md +6 -0
- package/pack/generated/claude/skills/rite-review/reference/security-review.md +7 -2
- package/pack/generated/claude/skills/rite-seal/reference/final-evidence.md +3 -0
- package/pack/generated/claude/skills/rite-seal/reference/risk-and-rollback.md +19 -4
- package/pack/generated/claude/skills/rite-ship/reference/rollout.md +62 -43
- package/pack/generated/claude/skills/rite-spec/SKILL.md +8 -1
- package/pack/generated/claude/skills/rite-spec/reference/ai-spec-template.md +13 -6
- package/pack/generated/claude/skills/rite-spec/reference/spec-checklists.md +14 -2
- package/pack/generated/claude/skills/rite-spec/reference/spec-template.md +33 -4
- package/pack/generated/claude/skills/rite-temper/SKILL.md +5 -1
- package/pack/generated/claude/skills/rite-vet/SKILL.md +8 -8
- package/pack/generated/claude/skills/rite-vet/reference/artifacts.md +5 -3
- package/pack/generated/claude/skills/rite-vet/reference/review-axes.md +67 -77
- package/pack/generated/claude/skills/rite-watch-pr/SKILL.md +85 -0
- package/pack/generated/claude/skills/rite-zoom-out/SKILL.md +4 -5
- package/pack/generated/claude/workflows/devrites-readonly-review.js +194 -0
- package/pack/generated/codex/agents/devrites-code-reviewer.toml +6 -1
- package/pack/generated/codex/agents/devrites-plan-drafter.toml +5 -0
- package/pack/generated/codex/agents/devrites-plan-reviewer.toml +6 -0
- package/pack/generated/codex/agents/devrites-proof-runner.toml +7 -1
- package/pack/generated/codex/agents/devrites-retrospector.toml +21 -25
- package/pack/generated/codex/agents/devrites-security-auditor.toml +7 -3
- package/pack/generated/codex/agents/devrites-slice-wright.toml +30 -4
- package/pack/generated/codex/agents/devrites-spec-reviewer.toml +5 -0
- package/pack/generated/codex/agents/devrites-strategy-reviewer.toml +3 -4
- package/pack/generated/codex/agents/devrites-test-analyst.toml +5 -0
- package/pack/generated/codex/skills/devrites-debug-recovery/SKILL.md +12 -16
- package/pack/generated/codex/skills/devrites-debug-recovery/reference/build-the-loop.md +11 -14
- package/pack/generated/codex/skills/devrites-doubt/SKILL.md +3 -4
- package/pack/generated/codex/skills/devrites-frontend-craft/reference/reuse-first.md +3 -4
- package/pack/generated/codex/skills/devrites-lib/reference/standards/README.md +5 -1
- package/pack/generated/codex/skills/devrites-lib/reference/standards/afk-hitl.md +33 -8
- package/pack/generated/codex/skills/devrites-lib/reference/standards/agents.md +11 -3
- package/pack/generated/codex/skills/devrites-lib/reference/standards/ci-cd.md +19 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/code-review.md +1 -1
- package/pack/generated/codex/skills/devrites-lib/reference/standards/core.md +5 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/data-integrity.md +95 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/developer-experience.md +5 -5
- package/pack/generated/codex/skills/devrites-lib/reference/standards/documentation.md +28 -29
- package/pack/generated/codex/skills/devrites-lib/reference/standards/edge-case-trace.md +70 -10
- package/pack/generated/codex/skills/devrites-lib/reference/standards/integration-reliability.md +79 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/loop-operations.md +85 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/observability.md +10 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/patterns.md +20 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/repository-topology.md +73 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/security-checklist.md +6 -2
- package/pack/generated/codex/skills/devrites-lib/reference/standards/security.md +51 -16
- package/pack/generated/codex/skills/devrites-lib/reference/standards/skill-authoring.md +35 -40
- package/pack/generated/codex/skills/devrites-lib/reference/standards/test-proof-checklist.md +4 -0
- package/pack/generated/codex/skills/devrites-lib/reference/standards/testing.md +51 -6
- package/pack/generated/codex/skills/rite/SKILL.md +2 -0
- package/pack/generated/codex/skills/rite-adopt/SKILL.md +8 -10
- package/pack/generated/codex/skills/rite-adopt/reference/adoption.md +13 -15
- package/pack/generated/codex/skills/rite-autocomplete/SKILL.md +18 -11
- package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md +29 -6
- package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md +7 -0
- package/pack/generated/codex/skills/rite-build/SKILL.md +7 -1
- package/pack/generated/codex/skills/rite-build/reference/phase-contract.md +6 -1
- package/pack/generated/codex/skills/rite-build/reference/wright-dispatch.md +37 -4
- package/pack/generated/codex/skills/rite-clarify/SKILL.md +3 -2
- package/pack/generated/codex/skills/rite-converge/SKILL.md +4 -2
- package/pack/generated/codex/skills/rite-converge/reference/convergence-assessment.md +8 -4
- package/pack/generated/codex/skills/rite-customize/SKILL.md +16 -18
- package/pack/generated/codex/skills/rite-define/SKILL.md +60 -62
- package/pack/generated/codex/skills/rite-define/reference/plan-template.md +88 -71
- package/pack/generated/codex/skills/rite-explain/SKILL.md +2 -1
- package/pack/generated/codex/skills/rite-learn/SKILL.md +28 -32
- package/pack/generated/codex/skills/rite-plan/SKILL.md +42 -45
- package/pack/generated/codex/skills/rite-plan/reference/dependency-graph.md +11 -2
- package/pack/generated/codex/skills/rite-plan/reference/task-breakdown.md +2 -0
- package/pack/generated/codex/skills/rite-polish/reference/adr-promotion.md +7 -7
- package/pack/generated/codex/skills/rite-pressure-test/SKILL.md +24 -31
- package/pack/generated/codex/skills/rite-prove/SKILL.md +12 -15
- package/pack/generated/codex/skills/rite-prove/reference/acceptance-proof.md +28 -0
- package/pack/generated/codex/skills/rite-review/SKILL.md +5 -4
- package/pack/generated/codex/skills/rite-review/reference/five-axis-review.md +6 -0
- package/pack/generated/codex/skills/rite-review/reference/security-review.md +7 -2
- package/pack/generated/codex/skills/rite-seal/reference/final-evidence.md +3 -0
- package/pack/generated/codex/skills/rite-seal/reference/risk-and-rollback.md +19 -4
- package/pack/generated/codex/skills/rite-ship/reference/rollout.md +62 -43
- package/pack/generated/codex/skills/rite-spec/SKILL.md +8 -1
- package/pack/generated/codex/skills/rite-spec/reference/ai-spec-template.md +13 -6
- package/pack/generated/codex/skills/rite-spec/reference/spec-checklists.md +14 -2
- package/pack/generated/codex/skills/rite-spec/reference/spec-template.md +33 -4
- package/pack/generated/codex/skills/rite-temper/SKILL.md +5 -1
- package/pack/generated/codex/skills/rite-vet/SKILL.md +8 -8
- package/pack/generated/codex/skills/rite-vet/reference/artifacts.md +5 -3
- package/pack/generated/codex/skills/rite-vet/reference/review-axes.md +67 -77
- package/pack/generated/codex/skills/rite-watch-pr/SKILL.md +85 -0
- package/pack/generated/codex/skills/rite-zoom-out/SKILL.md +4 -5
- package/package.json +1 -1
- package/scripts/build-host-artifacts.sh +3 -1
|
@@ -1,43 +1,62 @@
|
|
|
1
|
-
# Staged rollout
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
##
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
1
|
+
# Staged rollout and recovery: live deploys only
|
|
2
|
+
|
|
3
|
+
Load this only when `/rite-ship` itself is explicitly authorized to drive a live
|
|
4
|
+
deployment. Git-only Ship stops before rollout; CI-owned deployment follows the pipeline's
|
|
5
|
+
runbook. A Seal GO or AFK setting never authorizes production action.
|
|
6
|
+
|
|
7
|
+
## Preconditions before exposure
|
|
8
|
+
|
|
9
|
+
Record one rollout sheet in `ship.md`/`evidence.md`:
|
|
10
|
+
|
|
11
|
+
| Item | Required decision/evidence |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| Units and order | Repository/deployable, schema, config, application, worker, contract, and flag order; safe old/new combinations. |
|
|
14
|
+
| Exposure stages | Project-native internal/canary/cohort/percentage/region stages and hold window. |
|
|
15
|
+
| Advance/hold/abort signals | Project baseline or SLO, measurement window, minimum sample, exact threshold, and owner. |
|
|
16
|
+
| Recovery | Fastest safe mechanism, steps, owner, measured/rehearsed time, and data/external-effect reconciliation. |
|
|
17
|
+
| Observability | Watched dashboard/query/alert, failure signal, and executable first action. |
|
|
18
|
+
| Authorization | Exact target/action approved for this attempt; no inferred retry permission. |
|
|
19
|
+
|
|
20
|
+
Do not import generic percentage, latency, error-rate, or time-to-rollback numbers. Use
|
|
21
|
+
accepted product risk, current baseline/SLO, traffic volume, and platform capability. If the
|
|
22
|
+
project has no defensible threshold or signal, the monitoring gap blocks live exposure.
|
|
23
|
+
|
|
24
|
+
## Choose the smallest reversible mechanism
|
|
25
|
+
|
|
26
|
+
- A feature flag is useful only when the off path preserves current behavior, both states
|
|
27
|
+
are tested, disabling it stops the risky effect, and it has an owner/removal trigger.
|
|
28
|
+
Do not add a flag to a change already reversible by a safe atomic deploy.
|
|
29
|
+
- A flag cannot reverse destructive data/schema effects. Apply
|
|
30
|
+
[`data-integrity.md`](../../devrites-lib/reference/standards/data-integrity.md) and prove
|
|
31
|
+
restore or forward recovery separately.
|
|
32
|
+
- External APIs, webhooks, queues, jobs, and caches apply
|
|
33
|
+
[`integration-reliability.md`](../../devrites-lib/reference/standards/integration-reliability.md):
|
|
34
|
+
reconcile unknown outcomes, drain/quarantine/replay safely, and protect downstream capacity.
|
|
35
|
+
- Multi-root/service rollout follows
|
|
36
|
+
[`repository-topology.md`](../../devrites-lib/reference/standards/repository-topology.md);
|
|
37
|
+
references to another repository never grant write/deploy authority there.
|
|
38
|
+
|
|
39
|
+
## Stage, observe, decide
|
|
40
|
+
|
|
41
|
+
At each authorized stage:
|
|
42
|
+
|
|
43
|
+
1. Verify the intended versions/config/schema and candidate identity on the exact target.
|
|
44
|
+
2. Exercise one critical success path and the declared degradation/recovery signal.
|
|
45
|
+
3. Observe for the recorded window and sample; bind results to the stage and baseline.
|
|
46
|
+
4. **Advance** only when every advance condition holds. **Hold** on ambiguous or
|
|
47
|
+
insufficient evidence. **Abort/recover** immediately on an abort condition, security or
|
|
48
|
+
tenant breach, data-integrity violation, unreconciled duplicate/unknown effect, or loss of
|
|
49
|
+
observability.
|
|
50
|
+
5. Re-verify after recovery; record partial effects and reconciliation. A rollback command
|
|
51
|
+
exiting zero is not proof the prior state or data was restored.
|
|
52
|
+
|
|
53
|
+
Never compress stages because an early sample "looks fine," continue through a monitoring
|
|
54
|
+
gap, or retry a failed live action without fresh authorization when the attempt/target changes.
|
|
55
|
+
|
|
56
|
+
## Completion
|
|
57
|
+
|
|
58
|
+
Rollout is complete only when full intended exposure meets the recorded window/signals,
|
|
59
|
+
telemetry is still watched, migrations/backfills and queues/reconciliation are settled,
|
|
60
|
+
documentation matches deployed behavior, and temporary flags/compatibility paths have a
|
|
61
|
+
dated removal owner. Otherwise report the exact current stage and remaining risk; do not call
|
|
62
|
+
the launch done.
|
|
@@ -19,6 +19,10 @@ declared invariants; an unavoidable principle violation is blocking.
|
|
|
19
19
|
For behavioral/high-risk acceptance, use `spec-grammar.md` plus workspace schema;
|
|
20
20
|
simple criteria stay flat `AC-###`. Apply
|
|
21
21
|
[`acceptance-criteria.md`](reference/acceptance-criteria.md) so each is binary and observable.
|
|
22
|
+
Use [`edge-case-trace.md`](../devrites-lib/reference/standards/edge-case-trace.md)
|
|
23
|
+
to populate only relevant edge/prohibition rows. The spec's applicability map routes
|
|
24
|
+
topology, data, integration, security, and delivery concerns to their focused standard;
|
|
25
|
+
load a routed standard to discover required behavior, not to prescribe implementation.
|
|
22
26
|
|
|
23
27
|
## Operating rules (DevRites core)
|
|
24
28
|
- No silent assumptions or guessing; prefer conventions; ask on scope,
|
|
@@ -65,6 +69,8 @@ simple criteria stay flat `AC-###`. Apply
|
|
|
65
69
|
template's specific justification.
|
|
66
70
|
Identify proof constraints now: human-only credentials, unavailable environments, approval
|
|
67
71
|
windows, or acceptance not observable through existing test/runtime/browser surfaces.
|
|
72
|
+
An unfamiliar framework/version routes to `devrites-source-driven`; missing or
|
|
73
|
+
contradictory documentation is evidence to reconcile, never a license to guess.
|
|
68
74
|
Split independent placement, blast-radius, and external-fact questions into at most three
|
|
69
75
|
bounded `devrites-evidence-scout` tasks on one frozen candidate. Wait for and reconcile every
|
|
70
76
|
cited dossier before step 4. The scout supplies facts only; it never asks the human or writes
|
|
@@ -102,7 +108,8 @@ simple criteria stay flat `AC-###`. Apply
|
|
|
102
108
|
unrelated settled content. Write every required artifact and conditional
|
|
103
109
|
annex exactly from [spec-template](reference/spec-template.md), including its
|
|
104
110
|
capability impact, existing-behavior preservation, grammar/delta,
|
|
105
|
-
|
|
111
|
+
stakeholder/constraint/invariant, failure/recovery, applicability, coverage-seed,
|
|
112
|
+
qualified backstop, edge/prohibition, UI, and AI rules. Native
|
|
106
113
|
hierarchical instructions remain stable; do not rewrite `AGENTS.md` or
|
|
107
114
|
`CLAUDE.md` for the active workspace.
|
|
108
115
|
5a. **Check the spec prose** with [spec-checklists](reference/spec-checklists.md).
|
|
@@ -17,17 +17,24 @@ or LLM output.
|
|
|
17
17
|
- Fallback/degradation: <what users see when AI is unavailable>
|
|
18
18
|
|
|
19
19
|
## Domain evals
|
|
20
|
-
| Eval ID | Scenario | Expected signal | Gate |
|
|
21
|
-
| --- | --- | --- | --- |
|
|
22
|
-
| EVAL-001 | <
|
|
20
|
+
| Eval ID | Scenario / slice | Dataset provenance | Expected signal + threshold | Gate |
|
|
21
|
+
| --- | --- | --- | --- | --- |
|
|
22
|
+
| EVAL-001 | <representative/adversarial/empty-context case> | <held-out source/version> | <pass condition and baseline delta> | build/seal |
|
|
23
|
+
|
|
24
|
+
For RAG, cover retrieval relevance/context recall, context precision, answer
|
|
25
|
+
faithfulness, citation support, tenant/ACL isolation, poisoned or conflicting documents,
|
|
26
|
+
and insufficient-context fallback as applicable. A single polished example is not an eval.
|
|
23
27
|
|
|
24
28
|
## Guardrails
|
|
25
29
|
- Inputs: <validation, prompt-injection boundaries, tenant/data limits>
|
|
26
|
-
-
|
|
30
|
+
- Retrieval: <source provenance, indexing validation, tenant/ACL filter, freshness/deletion>
|
|
31
|
+
- Outputs: <schema checks, refusals, human review, citations only to supporting retrieved sources>
|
|
27
32
|
- Privacy/security: <data sent to model, retention, secrets policy>
|
|
33
|
+
- Unknown/insufficient context: <abstain, clarify, or bounded fallback; never fabricate>
|
|
28
34
|
|
|
29
35
|
## Monitoring
|
|
30
|
-
- Runtime metrics/logs: <latency, cost, quality, refusal/error rates>
|
|
36
|
+
- Runtime metrics/logs: <latency, cost, retrieval/quality, refusal/error/fallback rates>
|
|
31
37
|
- Alerts or manual review: <trigger>
|
|
32
|
-
- Rollback/kill switch: <mechanism>
|
|
38
|
+
- Rollback/kill switch: <prompt/model/index version and reversible mechanism>
|
|
39
|
+
- Drift evaluation: <reference set, schedule/trigger, regression threshold, owner>
|
|
33
40
|
```
|
|
@@ -15,8 +15,8 @@ Emit `.devrites/work/<slug>/checklists/<domain>.md` per covered domain; skip
|
|
|
15
15
|
| `functional.md` | Functional requirements + scenarios: is each capability stated, bounded, testable? |
|
|
16
16
|
| `data-model.md` | Key entities / data model: shapes, fields, lifecycle, relationships (skip if "none"). |
|
|
17
17
|
| `interaction.md` | API / UI impact + UX states: every screen state and contract named (skip if no UI/API). |
|
|
18
|
-
| `non-functional.md` |
|
|
19
|
-
| `edge-cases.md` | Empty
|
|
18
|
+
| `non-functional.md` | Invariants; security/privacy/accessibility, latency/scale, compatibility, operations, and human-only proof prerequisites. |
|
|
19
|
+
| `edge-cases.md` | Empty/boundary/invalid/concurrent/failure/recovery paths plus the spec's applicability map. |
|
|
20
20
|
|
|
21
21
|
## Each item: a question, a verdict, the line it interrogates
|
|
22
22
|
|
|
@@ -46,9 +46,21 @@ Each question checks one requirement-prose failure mode:
|
|
|
46
46
|
names its empty / error / boundary behaviour.
|
|
47
47
|
- **Clarity:** one entity, one name (no `user`/`customer`/`account` drift); no requirement two
|
|
48
48
|
readers would implement differently; no "should" where "MUST" is meant.
|
|
49
|
+
- **Assumptions:** no material behavior, scope, data, security, or proof fact survives as a
|
|
50
|
+
hidden assumption; verify it or record an owned/deadlined assumption or blocking question.
|
|
49
51
|
- **Testability:** each acceptance criterion is binary and names (or clearly implies) its evidence.
|
|
50
52
|
A criterion only provable by reading code is a fail.
|
|
51
53
|
- **Consistency:** no requirement contradicts another, the data model, or a non-goal.
|
|
54
|
+
- **Stakeholders:** affected actors/operators are named; conflicting outcomes have an
|
|
55
|
+
explicit priority or decision owner rather than two simultaneously impossible promises.
|
|
56
|
+
- **Applicability:** topology, data, integration, security, UI/i18n/time zone, and
|
|
57
|
+
compatibility/delivery rows are `applies` with IDs or specifically justified `not applicable`.
|
|
58
|
+
- **Failure/recovery:** each partial, timeout, invalid, interrupted, or unavailable state
|
|
59
|
+
implied by an applicable row has a user outcome, system state, and safe retry/recovery rule.
|
|
60
|
+
- **Data:** schema/backfill/concurrency/tenant/retention implications state invariants and
|
|
61
|
+
prohibited loss/leakage; implementation detail stays for Define.
|
|
62
|
+
- **Integration:** timeout, invalid/partial response, auth/rate-limit/outage, duplicate,
|
|
63
|
+
ordering, and version-change behavior is specified when the boundary can produce it.
|
|
52
64
|
- **Preservation:** each material brownfield outcome appears in `Existing behavior
|
|
53
65
|
to preserve` with preserving REQ/AC and current evidence. Missing/vague “no
|
|
54
66
|
regressions” or unjustified `none` is CRITICAL.
|
|
@@ -33,10 +33,15 @@ No implementation detail. True greenfield: `none — no existing behavior in the
|
|
|
33
33
|
| --- | --- | --- |
|
|
34
34
|
| <outcome that must not regress> | REQ-001 / AC-001 | <current evidence> |
|
|
35
35
|
|
|
36
|
-
##
|
|
37
|
-
| Actor |
|
|
38
|
-
| --- | --- |
|
|
39
|
-
| <actor> | <goal> |
|
|
36
|
+
## Stakeholders and priorities
|
|
37
|
+
| Actor/stakeholder | Observable outcome | Conflict / priority rule |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| <actor or affected owner> | <goal, protection, or operational need> | <none or how competing goals resolve> |
|
|
40
|
+
|
|
41
|
+
## Constraints and invariants
|
|
42
|
+
- INV-001: <fact that MUST remain true across success, failure, retry, and recovery>.
|
|
43
|
+
- <security/privacy/accessibility/performance/compatibility/data/operational constraint,
|
|
44
|
+
or `none — <specific reason>` for a materially relevant category>.
|
|
40
45
|
|
|
41
46
|
## Requirements
|
|
42
47
|
- REQ-001: The system MUST <observable product behavior>.
|
|
@@ -74,6 +79,24 @@ Bespoke only; generic security/privacy stays in standards. Status:
|
|
|
74
79
|
| --- | --- | --- | --- |
|
|
75
80
|
| PROH-001 | REQ-002 | resolved/test | <test/evidence link> |
|
|
76
81
|
|
|
82
|
+
## Failure and recovery behavior
|
|
83
|
+
| Trigger / partial state | User-visible outcome | System state | Recovery / retry rule | Requirement/AC |
|
|
84
|
+
| --- | --- | --- | --- | --- |
|
|
85
|
+
| <timeout, invalid input, interruption, dependency loss> | <clear bounded outcome> | <unchanged/pending/reconciling> | <who/what can safely recover> | <REQ/AC> |
|
|
86
|
+
|
|
87
|
+
## Applicability map
|
|
88
|
+
Use `applies | not applicable`; a non-applicable row needs a specific reason. The
|
|
89
|
+
status routes Define/Vet/Build/Prove to the named standard without copying it here.
|
|
90
|
+
|
|
91
|
+
| Concern | Status and trigger | Affected REQ/AC/invariant |
|
|
92
|
+
| --- | --- | --- |
|
|
93
|
+
| Repository topology (nested/mono/multi-repo, languages, services, generated/vendor) | <status + reason> | <ids> |
|
|
94
|
+
| Data integrity (writes, schema/migration, concurrency, tenant, retention/privacy) | <status + reason> | <ids> |
|
|
95
|
+
| Integration reliability (API/webhook/queue/job/cache/cross-service) | <status + reason> | <ids> |
|
|
96
|
+
| Security boundary (authn/authz, hostile input/files, secrets, privilege) | <status + reason> | <ids> |
|
|
97
|
+
| UI/accessibility/i18n/time-zone behavior | <status + reason> | <ids> |
|
|
98
|
+
| Compatibility/delivery (old/new versions, config, flag, rollout/rollback) | <status + reason> | <ids> |
|
|
99
|
+
|
|
77
100
|
## Edge cases
|
|
78
101
|
- <Boundary note not captured above.>
|
|
79
102
|
|
|
@@ -106,9 +129,15 @@ Bespoke only; generic security/privacy stays in standards. Status:
|
|
|
106
129
|
|
|
107
130
|
## Readiness gate
|
|
108
131
|
- [ ] No blocking clarification; REQ/AC IDs are valid and ACs independently provable.
|
|
132
|
+
- [ ] Stakeholder conflicts/priority rules, constraints, and invariants are explicit;
|
|
133
|
+
implementation preferences are not disguised as requirements.
|
|
109
134
|
- [ ] Existing affected behavior maps to preserving REQ/AC + current evidence, or uses the exact justified greenfield `none`.
|
|
110
135
|
- [ ] Edge rows target REQ/AC or justify dismissal; every backstop names independent discriminating evidence, else `unresolved`.
|
|
111
136
|
- [ ] Prohibitions resolve/dismiss; `resolved/test` links evidence.
|
|
137
|
+
- [ ] Each material failure/partial state names user outcome, system state, recovery,
|
|
138
|
+
and REQ/AC; no silent success or blind retry remains.
|
|
139
|
+
- [ ] Every applicability row is `applies` with affected IDs or has a specific
|
|
140
|
+
evidence-backed `not applicable` reason.
|
|
112
141
|
- [ ] AI has `ai-spec.md` and UI has `design-brief.md`; out-of-scope work states not applicable.
|
|
113
142
|
- [ ] Non-goals/scope are explicit; capability impact is singular/specific and matches ledger deltas.
|
|
114
143
|
- [ ] Architecture/flows/decisions are linked, not duplicated; Coverage seed names Clarify surfaces.
|
|
@@ -20,7 +20,9 @@ Pull on demand: `patterns.md` +
|
|
|
20
20
|
`coding-style.md` (the over-engineering / YAGNI rubric (reuse the pack's standard, don't
|
|
21
21
|
invent one), `documentation.md` (ADR-style `decisions.md` entries), `afk-hitl.md`
|
|
22
22
|
(irreversible-risk list + gate ceiling), `elicitation.md` (the move-set to deepen a section
|
|
23
|
-
that needs more than the default pre-mortem) selected by the section's risk).
|
|
23
|
+
that needs more than the default pre-mortem) selected by the section's risk). Load
|
|
24
|
+
`repository-topology.md`, `data-integrity.md`, or `integration-reliability.md` only when
|
|
25
|
+
the spec applicability map triggers that risk family.
|
|
24
26
|
|
|
25
27
|
## Operating rules
|
|
26
28
|
- **Raise outcome ambition without expanding the solution unnecessarily.** Solve the
|
|
@@ -67,6 +69,8 @@ that needs more than the default pre-mortem) selected by the section's risk).
|
|
|
67
69
|
**Interruption pre-mortem:** audit the spec forecast and assumptions for unresolved behavior,
|
|
68
70
|
proof prerequisites, approvals, access, and irreversible gates. Resolve facts and reversible
|
|
69
71
|
details now; retain only unavailable-pre-code or mandatory action-time checkpoints.
|
|
72
|
+
Challenge each `not applicable` decision against live evidence and each applicable
|
|
73
|
+
topology/data/integration row against its worst credible partial-state/recovery case.
|
|
70
74
|
- **Deepen on demand.** When a scope decision, requirement, or risk needs more analysis
|
|
71
75
|
than the default pre-mortem provides, choose 3-5 techniques from
|
|
72
76
|
[`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) whose *when-to-reach-for-it* matches that
|
|
@@ -21,7 +21,8 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
|
|
|
21
21
|
`coding-style.md`, `testing.md`, `spec-grammar.md`, `performance.md`,
|
|
22
22
|
`error-handling.md`, `development-workflow.md`, `afk-hitl.md`,
|
|
23
23
|
`one-shot-actions.md`, `developer-experience.md`, `elicitation.md`, and
|
|
24
|
-
`definition-of-done.md`.
|
|
24
|
+
`definition-of-done.md`. Load `repository-topology.md`, `data-integrity.md`, and
|
|
25
|
+
`integration-reliability.md` only when the spec applicability map or live plan triggers them.
|
|
25
26
|
|
|
26
27
|
|
|
27
28
|
## Operating rules
|
|
@@ -85,14 +86,13 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
|
|
|
85
86
|
[`reference/review-axes.md`](reference/review-axes.md). Search accepted ADRs and
|
|
86
87
|
relevant workspace `decisions.md` files directly. Harden to the smallest
|
|
87
88
|
behavior-preserving plan; ask only when that changes acceptance or explicit architecture policy.
|
|
88
|
-
2a. **Cross-artifact/project gates.**
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
conventions. Critical blocks; principle exceptions are human-owned. Recheck
|
|
92
|
-
after hardening and write `analysis.md`.
|
|
89
|
+
2a. **Cross-artifact/project gates.** Check spec/tasks/traceability: every AC/REQ maps by
|
|
90
|
+
ID/meaning to slice/proof and back. Check terms, conflicts, principles, anti-slop, conventions;
|
|
91
|
+
Critical blocks and principle exceptions are human-owned. Recheck, then write `analysis.md`.
|
|
93
92
|
2b. **Build-entry preflight.** Using [`reference/artifacts.md`](reference/artifacts.md), verify
|
|
94
|
-
|
|
95
|
-
|
|
93
|
+
exact command/cwd/tool/version/prerequisite; output filters must preserve upstream failure or
|
|
94
|
+
check producer status separately. Verify packages against authoritative source and nearest
|
|
95
|
+
manifest/lockfile; parser-sensitive syntax in an isolated fixture;
|
|
96
96
|
applicable UI/browser harnesses. Remeasure decision-bearing counts/versions/state
|
|
97
97
|
claims read-only: live facts win; conflicts mark stale artifacts;
|
|
98
98
|
unmeasurable conflict = gap. Record complete SHA-256 provenance inputs. Require
|
|
@@ -47,9 +47,9 @@ One-shot evidence completeness: <n/a | pass: action + retained artifact + bounds
|
|
|
47
47
|
Suppressed (confidence ≤4, unverified): <count — one line each>
|
|
48
48
|
|
|
49
49
|
## 4. Failure modes
|
|
50
|
-
| New codepath | Realistic failure |
|
|
51
|
-
|
|
52
|
-
| <path> | timeout /
|
|
50
|
+
| New codepath/boundary | Realistic failure | Partial/unknown effect | Recovery owner/path | Proof? | Silent? | Verdict |
|
|
51
|
+
|---|---|---|---|---|---|---|
|
|
52
|
+
| <path> | timeout / duplicate / race / stale | <state/effect> | <owner/action> | y/n | y/n | ok / **CRITICAL gap** |
|
|
53
53
|
|
|
54
54
|
## 5. Dependency safety
|
|
55
55
|
<declared order is safe | exact dependency/order correction>
|
|
@@ -152,6 +152,8 @@ acceptance/behavior changes route through the **Spec Drift Guard**.
|
|
|
152
152
|
- **Write directly into `plan.md` / `tasks.md`** (single canonical writer: you, not the reviewer):
|
|
153
153
|
- `plan.md` §Scope boundaries ← "NOT in scope" items.
|
|
154
154
|
- `plan.md` §Architecture decisions ← reuse-over-rebuild calls + named failure scenarios.
|
|
155
|
+
- `plan.md` §Applicability and system ownership ← corrected topology/data/integration
|
|
156
|
+
routing and each triggered standard's feature-specific output.
|
|
155
157
|
- `plan.md` §Dependency graph / §Implementation order ← any dependency or ordering fix
|
|
156
158
|
(e.g. refactor-before-feature split).
|
|
157
159
|
- `plan.md` §Complexity & deviations gate ← any deviation the §0 challenge surfaced + its justification.
|
|
@@ -1,9 +1,7 @@
|
|
|
1
1
|
# Vet review: scope, four axes, and outputs
|
|
2
2
|
|
|
3
|
-
Run §0
|
|
4
|
-
|
|
5
|
-
throughout rather than as a separate checklist. Calibrate every finding through the
|
|
6
|
-
confidence and verification gate before presenting it.
|
|
3
|
+
Run blocking §0, then the four axes and required outputs. Apply
|
|
4
|
+
[`eng-lenses.md`](eng-lenses.md) throughout; calibrate every finding before presenting it.
|
|
7
5
|
|
|
8
6
|
---
|
|
9
7
|
|
|
@@ -12,29 +10,33 @@ confidence and verification gate before presenting it.
|
|
|
12
10
|
Before reviewing implementation details, check whether the plan includes more work than
|
|
13
11
|
the settled spec requires.
|
|
14
12
|
|
|
15
|
-
1. **What
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
introduces, verify a framework/runtime built-in doesn't already do it, and that the choice is
|
|
29
|
-
current best practice with no known footgun: dispatch `devrites-source-driven` to confirm at
|
|
30
|
-
the source and record the citation. A custom roll where a built-in exists is a scope-reduction
|
|
31
|
-
finding.
|
|
32
|
-
5. **Completeness check.** Identify shortcuts in edge-case handling, error paths, and
|
|
33
|
-
test coverage. Prefer the complete option when AI-assisted implementation makes the
|
|
34
|
-
additional work small. Flag shortcuts that save little time but leave known gaps.
|
|
13
|
+
1. **What exists?** Find existing code/flows for each sub-problem (use the index per
|
|
14
|
+
[`tooling.md`](../../devrites-lib/reference/standards/tooling.md)). Can the plan capture their outputs instead of building parallel work?
|
|
15
|
+
Reuse → extend → build new; list missed reuse.
|
|
16
|
+
2. **Minimum diff.** Find the smallest acceptance-complete change. Flag non-blocking work;
|
|
17
|
+
cutting acceptance requires Drift Guard.
|
|
18
|
+
3. **Complexity smell.** **>8 files** or **>2 new services/modules/classes** needs a justified
|
|
19
|
+
complexity gate; otherwise harden to the smallest acceptance-preserving plan. Ask only if
|
|
20
|
+
reduction changes acceptance or architecture policy.
|
|
21
|
+
4. **Built-in check.** For each new pattern/infra/concurrency approach, dispatch
|
|
22
|
+
`devrites-source-driven` to verify current framework/runtime support and cite it. Custom
|
|
23
|
+
work where a built-in suffices is a scope-reduction finding.
|
|
24
|
+
5. **Completeness.** Find edge/error/test shortcuts; prefer the complete option when the
|
|
25
|
+
extra work is small, and flag small savings that leave known gaps.
|
|
35
26
|
6. **Distribution check.** If the plan introduces a new artifact (CLI binary, package, container,
|
|
36
27
|
deployable), does it include how it gets built / published / installed? If distribution is
|
|
37
28
|
deferred, say so explicitly in "NOT in scope": don't let it silently drop.
|
|
29
|
+
7. **Applicability check.** Compare `spec.md`'s topology/data/integration/security/delivery
|
|
30
|
+
decisions with live seams. A false `not applicable` or an `applies` row without the
|
|
31
|
+
focused standard's owner, failure/recovery, deployment order, and proof output is `broken`.
|
|
32
|
+
8. **Decision horizons.** Independently apply
|
|
33
|
+
[`plan-template.md`](../../rite-define/reference/plan-template.md#decision-horizons) to the
|
|
34
|
+
plan, questions, assumptions, decisions, and checkpoints; no known item may disappear.
|
|
35
|
+
Reject `local` for blockers or public contracts, security/data invariants, acceptance,
|
|
36
|
+
migration/rollback, dependencies, or cross-slice interfaces. Local/checkpoint deferral
|
|
37
|
+
needs bounded owner, evidence trigger, fallback, and resolution proof; a risk spike needs
|
|
38
|
+
necessary executable evidence, discriminating criteria, and fallback branches. Any defect is
|
|
39
|
+
`broken`; unresolved human blockers return to Clarify.
|
|
38
40
|
|
|
39
41
|
> **STOP discipline.** Fold technical reduction into the plan; ask and stop only for a
|
|
40
42
|
> human-owned choice.
|
|
@@ -45,46 +47,43 @@ If the smell does not trip, present the §0 findings and proceed to Axis 1.
|
|
|
45
47
|
|
|
46
48
|
## Four axes (one at a time, at most 8 findings each)
|
|
47
49
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
50
|
+
Fold verified technical findings into the plan; present each human-owned decision in one
|
|
51
|
+
`AskUserQuestion` packet. Combine support only for one owner/trade-off. HITL pauses; AFK
|
|
52
|
+
uses `depth.md`. Never invent findings.
|
|
51
53
|
|
|
52
54
|
### 1. Architecture
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
+
- Boundaries, coupling, data flow, single points of failure. Record invariants, not
|
|
56
|
+
scaffolding; medium+ decisions state `Binds:`/`Prevents:`.
|
|
57
|
+
- Repository/deployable roots, canonical contract and mutable-state ownership, shared
|
|
58
|
+
resources, dependency cycles, and old/new deployment combinations when applicable.
|
|
59
|
+
- Scaling ceiling under real load.
|
|
55
60
|
- Security architecture at the seams (auth, data access, API boundaries): does the plan name
|
|
56
61
|
the trust boundary for each untrusted input?
|
|
57
|
-
-
|
|
58
|
-
whether the plan accounts for it (feeds the failure-mode table).
|
|
62
|
+
- One realistic production failure per new codepath/integration (feeds failure-mode table).
|
|
59
63
|
- Does any key flow deserve an ASCII diagram in the plan or an inline comment in the code the
|
|
60
64
|
build will write? Name the files that should carry one.
|
|
61
65
|
|
|
62
66
|
### 2. Plan code-quality
|
|
63
|
-
-
|
|
67
|
+
- Implied modules and planned cross-slice repetition.
|
|
64
68
|
- Error-handling + edge cases the plan names, and the ones it doesn't (call those out explicitly).
|
|
65
69
|
- Over-engineering (premature abstraction, an extension point with no second caller) vs
|
|
66
70
|
under-engineering (fragile / hacky) relative to `patterns.md` + `coding-style.md`.
|
|
67
|
-
- Tech-debt hotspots
|
|
68
|
-
change will make stale.
|
|
71
|
+
- Tech-debt hotspots and diagrams the change makes stale.
|
|
69
72
|
|
|
70
73
|
### 3. Test-coverage design
|
|
71
|
-
Design tests before code
|
|
72
|
-
- **Framework
|
|
73
|
-
|
|
74
|
-
- **Map
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
- **Regression rule (mandatory, no question):** when the plan modifies existing behavior and the
|
|
85
|
-
current suite doesn't cover the changed path, a regression test is added to the plan as a
|
|
86
|
-
**Critical** requirement: no `AskUserQuestion`, no skipping. Regressions are the highest-priority
|
|
87
|
-
test because they prove something broke. When unsure whether a change is a regression, write the test.
|
|
74
|
+
Design tests before code.
|
|
75
|
+
- **Framework:** match the existing runner/conventions; never add a runner for one change.
|
|
76
|
+
- **Acceptance → tests.** Every AC maps to a planned surface assertion, not an internal proxy.
|
|
77
|
+
- **Map applicable risk → tests.** Data and integration rows cover their relevant
|
|
78
|
+
duplicate/retry/concurrency/interruption/tenant/timeout/partial/outage/order/rollback cases,
|
|
79
|
+
or record an evidence-backed dismissal. A mock that cannot exhibit the named risk is a GAP.
|
|
80
|
+
- **Tool per path:** unit for pure logic; integration/E2E for 3+ components,
|
|
81
|
+
auth/payment/data-loss, or mock-hidden failure; eval for LLM/prompt quality.
|
|
82
|
+
- **UI inventory:** list every interactive element/flow in `test-plan.md`; assign
|
|
83
|
+
elements/fields a unit/component assertion and critical journeys an E2E. Untested = GAP;
|
|
84
|
+
no one-E2E-per-field (`artifacts.md`).
|
|
85
|
+
- **Regression (mandatory):** changed behavior without path coverage adds a **Critical**
|
|
86
|
+
regression test—no question or skip. If uncertain, write it.
|
|
88
87
|
- Produce the **coverage diagram** (shape below) and add a specific test requirement per GAP.
|
|
89
88
|
|
|
90
89
|
#### Coverage diagram (write to `test-plan.md`)
|
|
@@ -119,45 +118,36 @@ Tag each finding `[severity] (confidence: N/10) <plan/task/spec ref> — finding
|
|
|
119
118
|
- **5-6** moderate → report with "verify this is real".
|
|
120
119
|
- **≤4** speculative → **suppress from the walk-through**, appendix only.
|
|
121
120
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
`devrites-plan-reviewer` follows the same rule.
|
|
121
|
+
Quote supporting lines. Without them confidence is ≤4 and suppressed; never inflate it.
|
|
122
|
+
`devrites-plan-reviewer` follows this rule.
|
|
125
123
|
|
|
126
124
|
---
|
|
127
125
|
|
|
128
126
|
## Present human-owned decisions
|
|
129
|
-
Use `AskUserQuestion
|
|
127
|
+
Use standard `AskUserQuestion`:
|
|
130
128
|
- **One decision = one call.** Never ask about agent work or batch unrelated choices.
|
|
131
129
|
- Concrete: name the plan/task section + the quoted line.
|
|
132
130
|
- 2-3 options, including "do nothing / proceed as-is" where reasonable.
|
|
133
|
-
- Per option
|
|
134
|
-
|
|
135
|
-
recommend complete.
|
|
131
|
+
- Per option: **effort** (human/build agent), **risk**, **maintenance**; recommend complete
|
|
132
|
+
when marginally costlier than a shortcut.
|
|
136
133
|
- **Map to a rule.** One sentence tying the recommendation to a DevRites rule (reuse-first,
|
|
137
134
|
fail-fast, test-behavior, measure-first, minimum diff).
|
|
138
|
-
- **Coverage vs kind:**
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
- Every material call ends as a **recorded decision**: behavior-preserving technical hardening
|
|
143
|
-
goes to `decisions.md`; a human-owned HITL choice gets a resolved `questions.md` qid; AFK
|
|
144
|
-
records the allowed recommendation in `decisions.md`. The review must leave an auditable
|
|
145
|
-
trail without turning agent work into questions.
|
|
135
|
+
- **Coverage vs kind:** coverage options get `Completeness: N/10`; architecture/kind options
|
|
136
|
+
state “differ in kind” and get no fabricated score.
|
|
137
|
+
- Record every material call: technical hardening/AFK in `decisions.md`; HITL in a resolved
|
|
138
|
+
`questions.md` qid. Do not turn agent work into questions.
|
|
146
139
|
|
|
147
140
|
---
|
|
148
141
|
|
|
149
142
|
## Required outputs (after the axes)
|
|
150
|
-
1. **"NOT in scope":**
|
|
151
|
-
|
|
152
|
-
2. **"What
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
4. **Dependency safety:** verify the declared dependency graph, required execution order,
|
|
159
|
-
and conflicts where slices touch the same module. Correct unsafe or missing ordering in the
|
|
160
|
-
plan; do not create a lane/scheduler artifact—the native host schedules eligible work.
|
|
143
|
+
1. **"NOT in scope":** considered/deferred work + rationale, folded into plan boundaries and
|
|
144
|
+
spec Non-goals via the Guard.
|
|
145
|
+
2. **"What exists":** solving code/flows and reuse/rebuild disposition; missed reuse is §0.
|
|
146
|
+
3. **Failure-mode table:** per new codepath: realistic failure, partial/unknown effect,
|
|
147
|
+
recovery owner, test, handling, and user-visible/silent result. No test + no handling +
|
|
148
|
+
silent = **Critical** (`artifacts.md`).
|
|
149
|
+
4. **Dependency safety:** verify graph/order and shared file/state/contract/lock/port/queue/env
|
|
150
|
+
conflicts. Correct the plan; native host scheduling needs no lane artifact.
|
|
161
151
|
5. **Build-entry preflight:** commands/cwds, tools, package state, parser/browser smoke,
|
|
162
152
|
prerequisites, and provenance ([`artifacts.md`](artifacts.md)).
|
|
163
153
|
6. **Implementation readiness:** goal-backward coverage, wiring, dependency simulation,
|