vaultspec-code-review ยท diff
git:20260908.ce86e08 to git:20260927.50639bc
43 added, 13 removed. Audit A to A.
---
name: vaultspec-code-review
- description: Audit planned work for safety, intent, and quality into a rolling audit record. Use at each point of the review cadence.
+ description: Review completed planned work for safety, intent, and quality using applicable verification evidence. Use at the system's review cadence.
---
# Code review (vaultspec-code-review)
Produces or extends an audit for work executed under a plan. Precondition: completed
Steps to review. A diff with no plan behind it is reviewed in the reply, not here. This
skill terminates within one run and never modifies the codebase; fixes go back to
`vaultspec-execute`.
## Steps
- - Read the plan's coverage assessment and any governing ADRs; list the files the
- reviewed Steps changed (their ledger rows name them).
+ - Establish the reviewed Steps, diff base and target (including uncommitted changes),
+ governing constraints, and unresolved risks. Reuse supplied grounding and verification
+ evidence; inspect the plan, relevant ADR sections, ledger, and code to fill gaps.
+ - When discovery yields competing supporting passages, optionally use
+ `vaultspec-core review context OBJECTIVE --base REF --candidate path:start-end`
+ (repeat `--candidate`; add `--head REF` for a committed target). The tool checks
+ TypeSafe enrollment and falls back locally. Share one selection across reviewers;
+ `--previous FILE` reuses judgments only for unchanged inputs. Read the full diff and
+ governing decisions, expanding context where needed. Selection adds no review gate and
+ establishes no verification result.
- Scaffold once per feature, `vaultspec-core vault add audit --feature {feature}` (or
the `create` tool); every later review appends to it. A separate audit (`--topic`)
only for a different purpose, such as curation, or when the user asks for one. Read
`.vaultspec/templates/audit.md`; its `## Findings` section is a rolling log, appended
- per review, never rewritten. Steps already reviewed with no commits since are not
- reviewed again unless changed interactions warrant it.
- - Review cohesive behavior across the affected workflow, not each file as a separate
- gate. For framework work, trace scenarios through rules, entry metadata, skills,
- personas, templates, executable checks, repair, and resume. Apply the system's
- tier-aware cadence; L1 needs no invented Phase.
+ per review, never rewritten. Reuse completed analysis while the reviewed behavior and
+ its interactions remain unchanged, including any uncommitted work.
+ - Trace affected workflows across interfaces. Apply the system's integrated review
+ contract and cadence; files are evidence, not separate approval units.
- Review in this run, or dispatch the `vaultspec-code-reviewer` persona (parallel
- reviewers only when the diff spans several subsystems), instructed to read the
- grounding documents and return findings for you to append.
+ reviewers only for independent scopes that benefit from it). Supply the scope,
+ grounding, evidence, and active check owners. Reviewers return findings for you to
+ append; independent judgment does not require duplicate test runs.
- Append findings as `### {topic} | {level} | {summary}` entries, the level lowercase
- (`low` to `critical`), and state the result: `PASS` (no critical or high),
- `REVISION REQUIRED`, or `FAIL`.
+ (`low` to `critical`). Report `FAIL` for critical findings, `REVISION REQUIRED` for
+ high findings, otherwise `PENDING` when required verification is unresolved, or `PASS`
+ when required checks have applicable passing evidence. Always report verification
+ coverage alongside the verdict.
- Report `critical` and `high` findings to the executor; they reopen the affected Steps.
Lower findings stay recorded. Fixes within approved scope return to approved Steps;
new scope or costly decisions require authorization under the system contract.
+
+ ## Verification evidence
+
+ Use existing CI results, ledger entries, or handoffs. Evidence identifies the command
+ and scope, checked revision or working-tree state, outcome, relevant environment, and
+ where to inspect results. Reuse it while relevant code, tests, dependencies, and check
+ conditions remain applicable; a commit identifier alone cannot establish freshness. Do
+ not introduce a separate evidence record or repeat checks just to sign the review.
+
+ Shared, expensive, or stateful checks have one owner, coordinated by the supervisor (the
+ reviewing agent when solo). Consult active check status before launching another run.
+ Continue code analysis while checks run. Cheap focused checks may run concurrently when
+ their resources are independent. Worktrees do not isolate machine capacity, services,
+ ports, or external quotas.
+
+ Run additional checks for a concrete coverage gap, changed relevant inputs, a suspected
+ defect, or an explicit project requirement. Choose the smallest useful check. Report
+ timeouts, unavailable infrastructure, and unfinished checks as evidence gaps, naming the
+ owner and next action; never silently skip required checks. Missing evidence alone does
+ not invent a defect or reopen a Step. Resume pending review with the missing results and
+ any changed interactions, without repeating completed analysis.