From 0cc0e82bbc380a3e5f2d8c689098ae9166d00302 Mon Sep 17 00:00:00 2001 From: JB Date: Wed, 7 Oct 2026 17:43:19 -0400 Subject: [PATCH] Make development workflow risk-based and verification proportionate --- ...kill-led-development-workflow-04SEP2026.md | 2 +- ...sk-based-development-workflow-07OCT2026.md | 11 +++ docs/todos.md | 2 +- .../skill-led-development-workflow-plan.md | 4 +- docs/workflow/workflow-automation-record.md | 80 ++++++++++++++++ skills/develop/code-review/SKILL.md | 83 +++++++---------- skills/develop/develop-workflow/SKILL.md | 93 +++++++++---------- .../assets/workflow-record.md | 22 +++-- .../references/data-policy.md | 24 +++++ .../references/evidence-and-recovery.md | 12 +-- .../references/git-and-integration.md | 37 +++----- .../references/review-and-remediation.md | 32 +------ .../references/verification.md | 36 +++++++ 13 files changed, 265 insertions(+), 173 deletions(-) create mode 100644 docs/adr/0008-risk-based-development-workflow-07OCT2026.md create mode 100644 docs/workflow/workflow-automation-record.md create mode 100644 skills/develop/develop-workflow/references/data-policy.md create mode 100644 skills/develop/develop-workflow/references/verification.md diff --git a/docs/adr/0006-skill-led-development-workflow-04SEP2026.md b/docs/adr/0006-skill-led-development-workflow-04SEP2026.md index 6022b36..ce8228e 100644 --- a/docs/adr/0006-skill-led-development-workflow-04SEP2026.md +++ b/docs/adr/0006-skill-led-development-workflow-04SEP2026.md @@ -8,7 +8,7 @@ supersedes: # Replace the custom workflow engine with a skill-led workflow -> The legacy-runtime retention and pilot-before-retirement prerequisite below are superseded by [ADR 0007](0007-archive-legacy-workflows-05SEP2026.md). The skill-led workflow and its outstanding validation requirements remain in force. +> The legacy-runtime retention and pilot-before-retirement prerequisite below are superseded by [ADR 0007](0007-archive-legacy-workflows-05SEP2026.md). The approval, disposable-data, review, verification, and record-commit policies are superseded by [ADR 0008](0008-risk-based-development-workflow-07OCT2026.md). The skill-led architecture and outstanding validation obligations remain in force; interpret scenario expectations under the current policy. ## Context diff --git a/docs/adr/0008-risk-based-development-workflow-07OCT2026.md b/docs/adr/0008-risk-based-development-workflow-07OCT2026.md new file mode 100644 index 0000000..8d3c4c2 --- /dev/null +++ b/docs/adr/0008-risk-based-development-workflow-07OCT2026.md @@ -0,0 +1,11 @@ +# Use risk-based development workflow gates + +On 07OCT2026, JB approved replacing routine plan-approval pauses and repeated full verification with risk-based automation. Clear work proceeds from a short recorded plan; unresolved product/design choices and meaningful risk retain human gates. This supersedes the categorical plan approval, migration approval, commit-per-gate, two-reviewer, and repeat-full-suite policies in [ADR 0006](0006-skill-led-development-workflow-04SEP2026.md) and its [implementation plan](../workflow/skill-led-development-workflow-plan.md). + +A standing repository policy may authorize schema changes and reset/reseed for named, verified disposable environments. Pre-production alone grants no authority; valuable/shared data, production access, external compatibility, and uncertain targets remain protected. Prefer direct changes over speculative compatibility or rollback machinery when the actual preservation contract permits rebuilding. + +Use focused checks while developing, one independent read-only reviewer covering standards and specification, targeted follow-up on bounded fixes, and one full required suite after remediation. Reuse evidence only while its inputs remain applicable; failures and broader changes still require appropriate reruns. Keep tests complete for meaningful behavior and credible failures rather than exhaustive permutations at every layer. Stricter repository/CI/hook requirements remain binding until explicitly revised. + +Preserve worktrees, scoped authorization, non-trivial UI direction approval, real interface validation, mutator exclusion, pinned review evidence, recoverable records, and safe local integration. Batch record updates into meaningful commits rather than requiring initial, per-gate, and closure commits. Keep the existing checkpoint heading contract and archived engines; add no replacement extension or hook runtime changes. + +The prior twelve-scenario and three-pilot validation obligation remains open in [todos](../todos.md#replace-workflow-with-a-skill-based-orchestrator), with expected decisions interpreted under this superseding policy. Focused policy walkthroughs for this revision are not claims that those execution scenarios or pilots passed. diff --git a/docs/todos.md b/docs/todos.md index 9ca0a8e..bdeb78b 100644 --- a/docs/todos.md +++ b/docs/todos.md @@ -62,7 +62,7 @@ Slice 1 found two Nono 0.74 limitations while building behavioral policy proofs. ## Replace `workflow` with a skill-based orchestrator -The strict `workflow` extension repeatedly failed before implementation because planner output and persisted state-machine constraints were too brittle for adaptive subagent orchestration. Implement the repository-managed `develop-workflow` skill under [ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md), where the parent owns the plan, task tree, isolated worktree, explicit approval gates, verification, and independent review while launching bounded subagents directly. Preserve file ownership, reviewer independence, and resumable repository evidence while preferring native Pi primitives. Keep this TODO open until all twelve fresh-session scenarios and three real-change pilots pass. The legacy implementations were archived separately with explicit approval to waive the retirement prerequisite under [ADR 0007](adr/0007-archive-legacy-workflows-05SEP2026.md); archival does not establish validation success. +The repository-managed `develop-workflow` skill replaces the brittle legacy engine under [ADR 0006](adr/0006-skill-led-development-workflow-04SEP2026.md), with risk-based automation now defined by [ADR 0008](adr/0008-risk-based-development-workflow-07OCT2026.md). Validate the parent-owned plan, isolated worktree, scoped approval boundaries, proportionate verification, independent review, ownership, and recoverable evidence through native Pi primitives. Keep this TODO open until all twelve fresh-session scenarios and three real-change pilots pass, interpreting old scenario expectations under the superseding policy: clear routine work is autonomous, declared disposable targets use standing authority, one reviewer covers both axes, and valid verification evidence is reused. Policy walkthroughs are not execution-pilot evidence. The legacy implementations were archived separately with explicit approval to waive the retirement prerequisite under [ADR 0007](adr/0007-archive-legacy-workflows-05SEP2026.md); archival does not establish validation success. ## Support finished-session resume for Claude CLI subagents diff --git a/docs/workflow/skill-led-development-workflow-plan.md b/docs/workflow/skill-led-development-workflow-plan.md index 0eef7fb..8464d86 100644 --- a/docs/workflow/skill-led-development-workflow-plan.md +++ b/docs/workflow/skill-led-development-workflow-plan.md @@ -1,6 +1,8 @@ # Skill-led development workflow plan -**Status:** Accepted +**Status:** Historical accepted plan; policy partially superseded + +> [ADR 0008](../adr/0008-risk-based-development-workflow-07OCT2026.md) supersedes categorical plan/migration gates, mandatory initial/per-gate/closure commits, two-reviewer defaults, and repeated full verification below. Use the current [develop-workflow skill](../../skills/develop/develop-workflow/SKILL.md) for execution. [ADR 0007](../adr/0007-archive-legacy-workflows-05SEP2026.md) already superseded the pilot-before-archival prerequisite. The twelve scenarios and three real-change pilots remain outstanding, evaluated against current policy rather than obsolete gate expectations. **Date:** 03SEP2026 **Working skill name:** `develop-workflow` diff --git a/docs/workflow/workflow-automation-record.md b/docs/workflow/workflow-automation-record.md new file mode 100644 index 0000000..f2ac9a4 --- /dev/null +++ b/docs/workflow/workflow-automation-record.md @@ -0,0 +1,80 @@ +# Risk-based workflow automation record + +## Status + +- Status: active +- Current phase: independent review +- Next safe action: review the pinned policy diff and four bounded scenarios. + +## Request and scope + +- Request: reduce routine human interaction and redundant testing, especially for replaceable pre-production data. +- In scope: develop-workflow skill and references/template; code-review skill; ADR and historical pointers; validation evidence and existing TODO alignment. +- Out of scope: extension runtime/config changes, global instructions, database access, archived engines, checkpoint format changes, replacement of outstanding twelve-scenario/three-pilot validation. + +## Git identity + +- Source branch: main +- Base commit: 284fdd638d1f2c790290491e0cfe2802880cec25 +- Feature branch: feature/workflow-automation +- Worktree: /home/jb/code/harness-tools/.worktrees/workflow-automation +- Omitted source changes: none; source checkout clean. + +## Acceptance criteria + +- [ ] Routine work proceeds from a recorded plan without an approval pause; substantive choices and protected actions remain gated. +- [ ] Disposable-data policy requires named authorized targets, identity checks, scope and reproducible reset/reseed; pre-production alone grants nothing. +- [ ] Focused tests and review precede one final full verification boundary; valid evidence can be reused and invalidated evidence is rerun. +- [ ] One non-author reviewer covers standards and specification; targeted fixes do not force fresh full reviews. +- [ ] Records remain recoverable with existing heading contract; no initial/per-gate/closure commit ceremony is mandatory. +- [ ] UI direction, real interface validation, worktree isolation, honest results and safe integration remain intact. +- [ ] No new extension, dependency, runtime behavior or user-level policy change. + +## Approved implementation plan and gates + +- Plan/specification source: user-approved /tmp/pi-present/develop-workflow-automation-review.md and the acceptance criteria above. +- Exact plan: revise workflow and supporting references, consolidate review policy in code-review, retain checkpoint heading schema, add ADR 0008 and supersession pointers, run focused checks and scenario walkthroughs, obtain one independent review, run final full suite/static checks, commit and integrate locally. +- Plan approval: user said "approved, let's proceed and implement this plan." on 07OCT2026. This explicitly authorizes the risk-based policy and its use for this revision; no redundant re-approval requested. +- UI classification and direction approval: documentation-only skill behavior; no product UI change. +- Risk decisions and scope: no database/environment declared disposable by this change; no dependency, security-posture, production, publishing or deployment changes. Existing external native-hooks default config directory is absent; no installed policy inferred or modified. + +## Ownership + +- Parent agent owns all edits under skills/develop/develop-workflow/, skills/develop/code-review/SKILL.md, docs/adr/0008-risk-based-development-workflow-07OCT2026.md, supersession pointers in ADR 0006 and the accepted workflow plan, docs/todos.md, and this record. +- Independent reviewer owns no files and cannot remediate. No mutating child assignments. + +## Verification matrix + +| Surface | Command or method | Exit code | Outcome | +| --- | --- | --- | --- | +| Checkpoint compatibility | node --test skills/develop/develop-workflow/tests/checkpoint-record.test.mjs | 0 | 13/13 passed; existing schema retained | +| Policy consistency | Node validateRecord on template/record, Python local-link validation, git diff --check | 0 | Both heading contracts valid; 18 links across 9 policy files resolve; whitespace clean. No prose snapshot tests added. | +| Scenarios | routine feature, disposable/protected data, targeted review fix/shared-code change, non-trivial UI | pending | Bounded policy walkthroughs, not full execution pilots | +| Final repository suite | bun run test | pending | Run after review fixes | +| Final static check | bun run typecheck | pending | Run at final boundary | + +## Review + +- Base and product HEAD: pending +- Clean status and tree hash: pending +- Commit list: pending +- Exact diff command: git diff --binary --full-index --find-renames ... -- +- SHA-256: pending +- Mutator identities: parent agent only +- Reviewer identity, digest confirmation, standards and specification verdicts: pending +- Findings and remediation: pending +- Before/after reviewer Git evidence: pending + +## Integration and rollback + +- Synchronization and re-verification: git fetch origin completed with exit 0; origin/main and source main both remain 284fdd638d1f2c790290491e0cfe2802880cec25. No rebase delta. +- Fast-forward result: pending +- Product and evidence commits: pending +- Reachability and cleanup: pending +- Rollback strategy: revert the focused policy commit; no data or runtime migration. + +## Checkpoints and blockers + +- Last committed valid checkpoint: none yet; initial durable record written before product edits; batch commits per approved policy. +- Blockers: none +- Exact next safe action: obtain independent review and scenario walkthroughs; then run final full suite and typecheck. diff --git a/skills/develop/code-review/SKILL.md b/skills/develop/code-review/SKILL.md index cc0d67a..1b5c111 100644 --- a/skills/develop/code-review/SKILL.md +++ b/skills/develop/code-review/SKILL.md @@ -1,83 +1,64 @@ --- name: code-review -description: Review changes since a fixed commit, branch, tag, or merge-base along separate repository-standards and specification axes. Use for branch, PR, work-in-progress, or workflow-record review after implementation and verification. +description: Independently review changes against repository standards and the requested behavior using a pinned Git diff. Use for branch, PR, work-in-progress, or workflow-record review, with targeted follow-up after fixes. --- # Code review -Run two independent, read-only reviews over one pinned diff: +Use one independent, read-only reviewer by default. Assess two axes and report them separately: - **Standards:** repository instructions and documented conventions. -- **Specification:** the originating issue, spec, or approved workflow record. +- **Specification:** the originating request, issue, spec, or workflow record. -Keep the axes separate so conformity cannot hide incorrect scope and correct scope cannot hide standards violations. +Add specialist reviewers when distinct risk or repository policy warrants them, not merely because there are two axes. The agent that authored or mutated the diff cannot review it or its own remediation. ## 1. Pin the review bytes -Require a fixed point; ask when none was supplied. Resolve and record: +Resolve a fixed point from the caller's brief or workflow record; ask only when the intended scope cannot be established. Record: -- review base commit; -- immutable product HEAD commit, never mutable `HEAD` in the reviewer brief; -- clean status and product tree hash; -- `git log .. --oneline`; -- exact command `git diff --binary --full-index --find-renames ... --`. +- review base and immutable product HEAD commits, never mutable `HEAD` in the brief; +- clean status, product tree hash, and `git log .. --oneline`; +- exact command `git diff --binary --full-index --find-renames ... --`; +- SHA-256 of those exact bytes, generated by the parent. -Run that command once in the parent, hash its exact bytes with SHA-256, and record the digest. Stop on a bad ref, dirty product state, or empty diff unless an empty comparison was explicitly expected. +Stop on a bad ref, dirty product state, or empty diff unless an empty comparison was expected. During a development workflow, review after focused checks and before the final full suite so fixes do not cause scheduled duplicate suite runs. Independent review does not establish test success. ## 2. Resolve specification and standards -Accept the first available specification source: +Use the caller's explicit request, supplied spec, or retained workflow record as the primary specification. Otherwise inspect linked issues (using repository issue-tracker instructions when configured) or matching repository docs. Ask only when the intended behavior remains unclear. A workflow record needs no issue-tracker configuration or ceremonial plan approval to be a valid specification. -1. a caller-supplied approved workflow record or spec path; -2. issue references in commits, using `docs/agents/issue-tracker.md` when configured; -3. a matching file under `docs/`, `specs/`, or `.scratch/`; -4. an explicit user statement that no specification exists. +If the user explicitly requests standards-only review without a specification, report “specification not assessed”; do not claim both axes passed. -A workflow record is a complete specification source and never requires issue-tracker configuration. Ask only when no source or explicit no-spec decision exists. Skip the specification reviewer and report “no specification available” only after that explicit decision. +Collect applicable `AGENTS.md`, `CLAUDE.md`, contributing, coding-standard, and ADR sources. Where repository standards do not override it, consider this judgment-based baseline and skip tooling-enforced issues: -Collect applicable `AGENTS.md`, `CLAUDE.md`, contributing, coding-standard, and ADR sources. Add this smell baseline where repository standards do not override it; treat each as a judgment call and skip tooling-enforced issues: +- Names hide purpose; duplicated logic obscures a shared contract. +- Feature envy, data clumps, primitive obsession, or repeated switches complicate change. +- Shotgun surgery or divergent responsibilities scatter one change across unrelated areas. +- Speculative generality, middlemen, message chains, or inappropriate inheritance add indirection without a current need. -- **Mysterious Name:** a name hides purpose. -- **Duplicated Code:** the same logic shape recurs. -- **Feature Envy:** behavior reaches into another object's data more than its own. -- **Data Clumps:** fields or parameters repeatedly travel together. -- **Primitive Obsession:** primitives stand in for a domain concept. -- **Repeated Switches:** the same type cascade recurs. -- **Shotgun Surgery:** one change requires scattered edits. -- **Divergent Change:** one module changes for unrelated reasons. -- **Speculative Generality:** abstraction exists without a current requirement. -- **Message Chains:** callers navigate long object chains. -- **Middle Man:** code delegates without adding value. -- **Refused Bequest:** an implementation ignores most inherited behavior. +Distinguish consequential defects and documented violations from optional style preferences. Do not require speculative abstractions, compatibility paths, or exhaustive tests without a concrete contract or risk. Judge coverage against changed behavior and credible failures. -## 3. Enforce reviewer independence +## 3. Enforce independence and read-only review -List every display name, profile, child/session ID, and ambiguous run that authored or mutated the diff. Select two different reviewer identities outside that set. Require repository read access plus Git-capable `bash`, with no declared `write`, `edit`, or nested-agent capability. +List every author/mutator by display name and stable child/session identity when exposed. Select a reviewer outside that set with repository read access and Git-capable `bash`, but no declared `write`, `edit`, or nested-agent tools. When identity cannot be distinguished, exclude the ambiguous profile/run rather than assuming independence. -Capture branch, HEAD, status, tree hash, and changed paths before review. Launch the standards and specification reviewers as separate direct subagent calls rather than a wrapped parallel call. Give both the pinned commits, exact diff command, expected digest, commit list, mutator exclusions, and identity-reporting requirement. +Capture branch, HEAD, status, tree hash, and changed paths before review. Launch the reviewer directly with the pinned commits, exact diff command and digest, specification, standards, mutator exclusions, and identity-reporting requirement. Require the reviewer to: -Require each reviewer to: +1. Regenerate the exact diff and confirm its SHA-256 before analysis. +2. Remain read-only, run no mutating commands, and perform no remediation. +3. Assess both axes, grounding findings in file/hunk evidence and severity; quote the requirement for specification findings. +4. Report identity when exposed and stay under 400 words unless complexity warrants more. -1. regenerate the exact diff and confirm its SHA-256 before analysis; -2. remain read-only and perform no remediation; -3. bind every finding to file/hunk evidence and severity; -4. report display/profile/child/session identity when exposed; -5. stay under 400 words. +After delivery, verify Git state is unchanged. Missing output, digest mismatch, mutator overlap, or reviewer mutation means no valid verdict. Mutation also makes that reviewer ineligible for subsequent review of the diff. -For standards, include every standards source and the full baseline above. Ask for documented violations separately from baseline judgments. For specification, include the approved source and ask for missing/partial requirements, scope creep, and apparently implemented but incorrect behavior with quoted requirements. +## 4. Report findings and remediate -Treat missing delivery, digest mismatch, reviewer/mutator identity overlap, or before/after repository mutation as no verdict. Any reviewer mutation also makes that identity a mutator. +Present `## Standards` and `## Specification`, separating documented violations from judgment-based concerns. Preserve each axis's findings and severity; report approval explicitly when no material findings remain. Keep optional suggestions non-blocking unless tied to a requirement or concrete risk. -## 4. Aggregate without reranking +Validate findings against repository evidence. An original implementer or another non-reviewer makes accepted fixes, then runs affected checks. Use [verification policy](../develop-workflow/references/verification.md) for evidence reuse and final-suite timing; obey stricter repository requirements. -Present the reports under `## Standards` and `## Specification`. Lightly clean formatting only; keep findings and axis severity separate. End with finding counts and the worst issue within each axis, not one combined winner. +For bounded corrections, resume the same independent reviewer with the previous verdict, old and new pinned commits/digests, fix delta, and check results. Require it to inspect fixes and affected interactions, confirm the new full-diff fingerprint, and state which prior conclusions remain applicable. A prior verdict alone never approves later product changes. -Bind approval to the base, product HEAD, clean status, tree hash, and diff digest. +Request a broader fresh review when scope, architecture, shared behavior, or uncertain interactions invalidate previous conclusions; use a new specialist identity only when useful or required. Ask the user only for changed requirements, approval-boundary risk, or an unresolved decision, not because an automatic remediation cycle count expired. Stop repetitive ineffective retries, reassess the cause, and surface blockers honestly. -## 5. Remediate through non-reviewers - -Validate findings against repository evidence. Assign accepted fixes to an original implementer or another non-reviewer. Rerun affected checks and the full required suite, create a new pinned fingerprint, and launch two fresh independent reviewers. - -Escalate after two unsuccessful remediation cycles or when a finding materially changes scope, acceptance criteria, ownership, verification, or architecture. Return material changes to plan approval before production mutation. - -**Complete when:** both axes approve the exact verified fingerprint and before/after evidence proves reviewers stayed read-only. +**Complete when:** independent review covers the final pinned product diff, applicable axes have no unresolved material findings, and before/after evidence proves the reviewer stayed read-only. Final test completion remains a separate integration requirement. diff --git a/skills/develop/develop-workflow/SKILL.md b/skills/develop/develop-workflow/SKILL.md index 14491aa..2e3d88d 100644 --- a/skills/develop/develop-workflow/SKILL.md +++ b/skills/develop/develop-workflow/SKILL.md @@ -1,97 +1,88 @@ --- name: develop-workflow -description: Runs feature work and other multi-step code changes through repository research, an approved implementation plan, isolated Git worktrees, explicit UI and risk gates, verification, independent review, and local integration. Use by default for features, non-trivial bug fixes, refactors, migrations, dependency changes, security-sensitive work, and UI changes. Excludes questions, research-only requests, and obvious low-risk edits requiring at most two steps. +description: Runs feature work, bug fixes, refactors, migrations, dependency changes, security-sensitive work, and UI changes through risk-based planning, isolated worktrees, proportionate verification, independent review, and local integration. Use by default for implementation work; keep questions read-only and straightforward low-risk edits lightweight. --- # Develop workflow -Own orchestration in the parent agent. Treat Git and the retained workflow record as recovery evidence; use task tools only as the live progress view. Give subagents bounded assignments, then verify their claims against repository state. +Own orchestration in the parent agent. Use Git and one retained record for recovery, task tools for live progress, and subagents only when their benefit exceeds coordination cost. Proceed within clear requirements and established patterns; reserve human interaction for decisions and meaningful risk. -## 0. Classify the request +## 0. Classify by impact Choose the smallest sufficient path before mutation: -- **Answer:** explain or research read-only. Make no changes. -- **Light:** make one obvious low-risk edit requiring at most two steps. Inspect, edit, run focused checks, and summarize. Record why this is safe when near the boundary. -- **Full:** use the phases below for three or more steps, multiple files or modules, ambiguity, architecture, dependencies, migrations, security implications, non-trivial UI, or meaningful regression risk. +- **Answer:** explain or research read-only. +- **Light:** a straightforward, bounded edit with understood behavior and low regression risk. Inspect, edit, run relevant checks, and summarize. Respect repository isolation and review requirements. +- **Standard:** feature work or changes needing coordinated implementation, verification, or recovery. Follow the phases below. Multiple files or steps alone do not imply high risk or require approval. -Promote light work to full before editing when discovery reveals meaningful scope or risk. +For either implementation path, assess affected consumers, data value, security, reversibility, and uncertainty. Record the reason when classification is near the boundary. Escalate the affected decision when new evidence reveals risk; do not restart the whole workflow for routine execution adjustments. -**Complete when:** observed scope and risk justify the selected path. +**Complete when:** scope and impact justify the path and any pending decisions are identified. -## Risk gates for every path +## Approval boundaries for every path -Ask just in time before adding, removing, or materially upgrading dependencies; schema/data migration; production or live-database access; public API or compatibility breaks; destructive Git/filesystem actions outside the narrowly proven final cleanup; force push or shared-history rewrite; non-fast-forward integration; conflict resolution that changes approved behavior; material scope or acceptance expansion; security-posture changes; publishing; or deployment. +Honor repository and global instructions. Ask for unresolved product or preference-sensitive design choices, material scope expansion, security-posture changes, externally breaking contracts, production/live-database access, protected data, publishing/deployment, unsafe cleanup, force operations, shared-history rewrite, non-fast-forward integration, or conflict resolution that changes agreed behavior. Dependency additions, removals, and material upgrades still need scoped authorization unless already explicitly approved. -Present concrete evidence, scope the authorization, and mark one option recommended with its reason. Checkpoint the decision before acting. Treat approval as specific to that action; ask again when later evidence broadens it. Promote light work to full before editing when meaningful risk appears. +For schema/data work, apply [data policy](references/data-policy.md): a standing authorization may cover named disposable targets, but pre-production alone grants no permission. Verify the actual target before any authorized operation. + +Reuse an explicit authorization within its scope instead of asking again at execution. Ask again only when evidence changes that scope or a rule explicitly requires a fresh decision. Present concrete evidence, a recommended option with its reason, and record the answer before acting. Routine worker reassignment after proven termination, equivalent checks, or internal implementation adjustments under established patterns are not new product decisions. ## 1. Preflight and isolate -For the full path, require Git worktrees, a writable repository record, `ask_user`, Git-capable independent reviewers, and target-interface validation when UI applies. Stop before product mutation when a mandatory capability is unavailable. Let task tools degrade to the retained record and let `artifact-presenter` degrade to reporting the exact artifact path; neither optional convenience may bypass a gate. In print or JSON mode, emit the pending gate or validation instructions and stop. +Read repository instructions, relevant docs/ADRs/tests, and Git state. For standard work, require an isolated Git worktree, a writable record, and a Git-capable independent reviewer. Require target-interface validation for UI changes. Follow [Git and integration](references/git-and-integration.md) for isolation and dirty-source handling. -Read repository instructions, relevant docs/ADRs/tests, and Git state. Follow [Git and integration](references/git-and-integration.md) to capture source evidence, resolve dirty-source approval, and establish the isolated branch/worktree. Prepare a unique record from [`assets/workflow-record.md`](assets/workflow-record.md) and publish it with the helper in [evidence and recovery](references/evidence-and-recovery.md). Create the available live progress view, run applicable documentation checks, and commit the initial record before product mutation. +Create a unique record from [`assets/workflow-record.md`](assets/workflow-record.md) using [evidence and recovery](references/evidence-and-recovery.md). Create the available task view. Save the record before product mutation; a separate initial commit is unnecessary. -**Complete when:** worktree identity is proven and the initial record commit names the next safe action. +Stop only at an unavailable capability needed for the next action. Noninteractive runs may proceed within clear authorization; if a human decision is pending and `ask_user` is unavailable, report the decision and stop before dependent mutation. Task tools may degrade to the record, and artifact presentation to an exact path. -## 2. Discover and decide requirements +**Complete when:** isolation and recovery evidence exist and the next action is authorized. -Launch independent read-only research lanes directly when concerns can be investigated separately; state that no files are owned. Give each child a self-contained prompt. Keep the parent active on other work and verify that every required result was delivered. Treat missing delivery as missing evidence. +## 2. Discover and plan -Reconcile repository evidence into scope, out-of-scope items, acceptance criteria, affected surfaces, constraints, and risks. Use `ask_user` only for decisions repository evidence cannot answer. Checkpoint decisions. +Resolve scope, acceptance criteria, affected surfaces, existing seams, and risks from repository evidence. Launch read-only research lanes only for useful independent questions; state that they own no files. Verify required results were delivered. -**Complete when:** requirements and unresolved questions are explicit. +Record a concise plan with implementation slices, path ownership, focused checks, final required verification, UI/data classification, outstanding decisions, and local integration/rollback. Use [proportionate verification](references/verification.md) to choose tests. Give mutating children bounded assignments, normally 15 minutes; the parent may adjust the bound to the task without a user gate. -## 3. Design and obtain plan approval +For clear routine work, state the plan and proceed. Present a plan through `artifact-presenter` when human review is needed, then use `ask_user` for the unresolved choices. An explicit user approval already supplied in conversation counts. Revisit only decisions affected by changed evidence; changing an owner or equivalent verification command does not itself require reapproval. -Record an exact implementation plan containing: +**Complete when:** the record states the intended outcome, checks, ownership, and authority to proceed. -- acceptance criteria mapped to slices; -- one named owner and concrete path ownership per mutating assignment; -- existing seams and patterns; -- focused and full verification commands with realistic data needs; -- UI classification, dependencies, migrations, production effects, and risk gates; -- review fixed point and specification source; -- integration and rollback strategy; -- a 15-minute default deadline per mutating assignment, or an explicitly approved alternative. +## 3. Resolve non-trivial UI direction -Present the complete record through `artifact-presenter`, then obtain explicit approval with `ask_user`. Checkpoint and commit the decision before production edits. Return to this gate after any material scope, acceptance, ownership, verification, or architecture change. +For non-trivial UI, invoke `prototype` and create three structurally different throwaway candidates before production-component edits. Ask approval for a smaller count when three meaningful alternatives are impossible. Validate candidates in the browser or real PTY/application, including representative responsive sizes. Prefer fast-browser for supported local web validation; use browser-harness when explicitly requested or its additional capabilities are needed. -**Complete when:** the user explicitly approved the exact committed plan. +Retain candidates on a dedicated throwaway branch and record its commit. Present them, obtain direction approval through `ask_user`, and checkpoint the choice. Rewrite the chosen direction as production code. Record why minor or non-visual UI skips prototyping; changed UI still needs actual interface validation. -## 4. Resolve non-trivial UI direction +**Complete when:** the selected direction and target-interface evidence are recorded before production UI mutation. -For non-trivial UI, invoke `prototype` and create three structurally different throwaway candidates before production-component edits. Ask approval for a smaller explicit count when three meaningful alternatives are impossible. Validate candidates through `browser-harness` for web UI or the real PTY/application for terminal/native UI, including representative responsive sizes. +## 4. Implement and run focused checks -Retain candidates on a dedicated throwaway branch and record its commit. Present them and obtain direction approval through `ask_user`. Checkpoint the selected direction before production mutation. Rewrite the chosen direction as production code rather than promoting prototype code. Record why minor or non-visual UI skips this phase. +State one owner and exclusive paths for each mutating assignment. Serialize by default; parallelize disjoint low-integration paths. Give workers the plan, decisions, acceptance criteria, test seam, commands, and deadline. Leave commits, integration, user interaction, and mutation delegation to the parent. -**Complete when:** target-interface evidence, retained prototype commit, selected direction, and reflected plan are recorded. +Follow [assignment evidence](references/evidence-and-recovery.md#assignment-evidence). Use TDD when appropriate under its agreed-seam rules, rather than invoking it for every edit. Run focused checks after meaningful behavioral slices; reuse delivered evidence when its inputs remain valid. Inspect returned diffs and repository state before accepting work. -## 5. Implement owned slices +**Complete when:** acceptance criteria have intentional implementation and proportionate focused evidence. -State one owner and exclusive paths for every mutating assignment. Serialize by default; parallelize only disjoint low-integration paths. Give each implementer the approved plan, decisions, acceptance criteria, test seam, allowed commands, and deadline. Tell workers to stop at the deadline and leave commits, integration, user interaction, and mutation delegation to the parent. +## 5. Synchronize and independently review -Follow [assignment evidence and recovery](references/evidence-and-recovery.md#assignment-evidence) before accepting, retrying, or reassigning mutation. Use TDD at agreed seams where practical. Run focused tests after behavioral slices. Inspect each returned diff and repository state before marking it complete. +Inspect the complete diff, synchronize affected documentation, and follow [Git and integration](references/git-and-integration.md) to fetch/rebase before final verification where practical. Run checks affected by synchronization, then create focused commits after their applicable checks pass. -**Complete when:** every acceptance criterion has intentional owned code and test evidence. +Follow [review and remediation](references/review-and-remediation.md). One independent, read-only reviewer covers standards and specification. Resolve material findings through a non-reviewer, run affected checks, and obtain targeted follow-up. Routine fixes do not require two new reviewers or a full-suite rerun before each review. -## 6. Verify the integrated worktree +**Complete when:** the final product diff has independent approval covering both axes and all material fixes. -Inspect the complete diff and status. Run focused behavioral tests, then repository-required typecheck, lint, build, and full tests. Exercise realistic E2E data across process/UI boundaries. Validate changed UI in its target interface and representative sizes. Synchronize affected documentation. +## 6. Run final verification -Record exact commands, exit codes, and concise outcomes. Keep flaky or environmental failures visible until resolved or escalated. Never infer success from a child transcript. +After review fixes, run the full repository-required test suite once against the integrated worktree, plus applicable typecheck, lint, and build checks. Use [verification evidence](references/verification.md) to reuse valid results and rerun invalidated checks. A failure is not permission to skip completion; fix it, obtain review for changed behavior, and rerun the necessary checks. -**Complete when:** the approved verification matrix passes against the integrated worktree state. +Validate changed UI in its target interface and important cross-boundary behavior with realistic data. Record commands, exit codes, and concise outcomes. Keep flaky/environmental failures visible until resolved or explicitly escalated. Distinguish a policy-authorized waiver from a pass. -## 7. Commit, synchronize, and review +**Complete when:** required final checks passed or exceptions were explicitly authorized under repository policy, and review still covers the final product state. -Create focused commits after their checks pass. Follow [Git and integration](references/git-and-integration.md) to fetch/rebase, reverify changed trees, and produce the pinned review brief and exact diff fingerprint. Follow [review and remediation](references/review-and-remediation.md) for two independent review axes, mutator exclusion, findings, and fresh-review rules. +## 7. Integrate and close -**Complete when:** standards and specification reviewers approve the exact verified product diff. +Follow [Git and integration](references/git-and-integration.md) for clean fast-forward integration, evidence updates, and proven-safe cleanup. Batch record changes with meaningful commits; a separate metadata closure commit is optional, not a gate. A later evidence-only record update cannot silently change requirements or executable instructions. -## 8. Integrate and close +Mark tasks complete and report commits, verification outcomes, review result, and record path concisely. Preserve detailed identity and fingerprint evidence in the record rather than repeating it in chat. Push, publish, deployment, and other protected actions remain outside local integration unless explicitly authorized. -Follow [Git and integration](references/git-and-integration.md). Recheck the source branch and checkout, fast-forward only when evidence remains valid, then create one metadata-only closure commit touching only the record. Run a cheap final sanity check. Remove the workflow-owned worktree and branch only after reachability and clean-state proofs. - -Mark tasks complete and report product/closure commits, review command and digest, reviewer identities, record path, and verification evidence. Keep push, publish, deployment, production access, unsafe cleanup, conflict-driven behavior changes, force operations, and non-fast-forward integration behind explicit just-in-time approval. - -**Complete when:** reviewed work and closure are reachable from the intended local source branch and temporary state is safely removed. +**Complete when:** reviewed work and retained evidence are reachable from the intended local branch and workflow-owned temporary state is safely removed. diff --git a/skills/develop/develop-workflow/assets/workflow-record.md b/skills/develop/develop-workflow/assets/workflow-record.md index 2ed0ff5..7d8e42d 100644 --- a/skills/develop/develop-workflow/assets/workflow-record.md +++ b/skills/develop/develop-workflow/assets/workflow-record.md @@ -28,19 +28,20 @@ - Plan/specification source: - Exact plan: -- Plan approval: +- Authority to proceed: clear request | standing policy | explicit approval +- Pending decisions (none when proceeding): - UI classification and direction approval: - Risk decisions and scope: ## Ownership -| Assignment | Owner identity | Deadline | Exclusive paths | Before/after Git evidence | Outcome | -| --- | --- | --- | --- | --- | --- | +- Parent-owned paths: +- Child assignments, when useful: owner/identity, paths, deadline, before/after Git evidence, outcome. ## Verification matrix -| Surface | Command | Exit code | Outcome | -| --- | --- | --- | --- | +| Surface | Command and cwd | Tested state/environment | Exit code | Outcome or reuse rationale | +| --- | --- | --- | --- | --- | ## Review @@ -50,21 +51,22 @@ - Exact diff command: - SHA-256: - Mutator identities: -- Standards reviewer identity, digest confirmation, and verdict: -- Specification reviewer identity, digest confirmation, and verdict: -- Findings and remediation cycles: +- Reviewer identity and digest confirmation: +- Standards verdict: +- Specification verdict: +- Findings and targeted follow-up: - Before/after reviewer Git evidence: ## Integration and rollback - Synchronization and re-verification: - Fast-forward result: -- Product and closure commits: +- Product and evidence commits: - Reachability and cleanup: - Rollback strategy: ## Checkpoints and blockers -- Last committed valid checkpoint: +- Latest saved checkpoint and last committed checkpoint (distinguish): - Blockers: - Exact next safe action: diff --git a/skills/develop/develop-workflow/references/data-policy.md b/skills/develop/develop-workflow/references/data-policy.md new file mode 100644 index 0000000..96aba4f --- /dev/null +++ b/skills/develop/develop-workflow/references/data-policy.md @@ -0,0 +1,24 @@ +# Disposable and protected data + +Pre-production is a lifecycle stage, not permission to discard data. Disposable means the owner authorizes replacement of specified data and it can be reproduced. Idempotent describes an operation's repeated effect; it does not establish disposability. + +## Establish authority + +Read the repository's existing instructions for a standing data policy. It must identify: + +- named disposable environments and how to verify the actual connection target; +- the data/resources that may be deleted or rebuilt; +- the authorized reset/reseed procedure and source of required fixtures; +- protected environments, valuable/shared data, and external compatibility obligations. + +Treat this as scoped authorization, not a reason to reset unnecessarily. Before each operation, verify the actual target matches the declaration, the operation stays within the allowed resources, and required data can be recreated. Stop and ask when identity, scope, or reproducibility is uncertain. Do not infer permission from a branch name, `NODE_ENV`, a database name containing “dev,” or the absence of production users. + +When no policy exists, ask for the intended preservation contract and explicit authority before schema/data changes. Record any approved standing policy in the repository's established instructions; never label an environment disposable on the agent's own authority. Production/live-database access remains explicitly gated even if another target is disposable. + +## Implement the smallest sufficient change + +For a verified, authorized disposable target, prefer a direct schema change plus reset/reseed over compatibility adapters, phased backfills, dual writes, or bespoke rollback machinery. Keep migration files when the framework needs them to create a fresh database. Verify initialization/rebuild and affected behavior with representative data. + +For protected data or external consumers, preserve the actual contract. Design migration, backup/recovery, compatibility, and verification around demonstrated risks and obtain scoped approval. Shared staging data with valuable manual QA state is protected unless its owner explicitly authorizes replacing it. + +Example: a required field in an authorized throwaway database may need an updated schema and seed data, a rebuild, and a feature check. It does not automatically need tests for upgrading every historic schema. The same field in a customer-backed service may require a staged migration and compatibility checks. diff --git a/skills/develop/develop-workflow/references/evidence-and-recovery.md b/skills/develop/develop-workflow/references/evidence-and-recovery.md index fd4ccb7..17292de 100644 --- a/skills/develop/develop-workflow/references/evidence-and-recovery.md +++ b/skills/develop/develop-workflow/references/evidence-and-recovery.md @@ -2,7 +2,7 @@ ## Checkpoint records -Keep one concise Markdown record in the repository's established plan location; otherwise use `docs/plans/.md`. Require a unique path before creation. Store status/current phase, request/scope, Git identity, acceptance criteria, exact approved plan and gate decisions, assignment ownership, verification outcomes, review identities/findings/fingerprint, integration, blockers, and the next safe action. +Keep one concise Markdown record in the repository's established plan location; otherwise use `docs/plans/.md`. Require a unique path before creation. Store status/current phase, request/scope, Git identity, acceptance criteria, the plan and its authority (clear user request, standing policy, or explicit decision), ownership, verification outcomes, review identity/findings/fingerprint, integration, blockers, and the next safe action. Retain the template's headings for helper compatibility; use short entries or “not applicable” rather than inventing ceremony for every section. Keep transcripts, leases, heartbeats, notification receipts, full command output, and model-authored execution graphs out of the record. Link durable artifacts or commits instead. Update only at meaningful boundaries; task tools hold high-frequency progress. @@ -13,7 +13,7 @@ node skills/develop/develop-workflow/scripts/checkpoint-record.mjs \ --input --expected-sha256 ``` -Omit `--expected-sha256` only for first creation; require an absent target. Commit the initial record and every approved gate before dependent product mutation. The exclusive lock serializes cooperating helper invocations; external mutation of its pathname is outside the contract. A stale digest, lock, temporary artifact with no valid record, validation failure, or filesystem error blocks progress. Preserve artifacts for inspection; never hand-delete recovery evidence to make a command pass. +Omit `--expected-sha256` only for first creation; require an absent target. Save the initial plan and scoped decisions before dependent mutation; batch record changes with meaningful commits instead of committing every gate. The exclusive lock serializes cooperating helper invocations; external mutation of its pathname is outside the contract. A stale digest, lock, temporary artifact with no valid record, validation failure, or filesystem error blocks dependent progress. Preserve artifacts for inspection; never hand-delete recovery evidence to make a command pass. ## Assignment evidence @@ -21,11 +21,11 @@ Before every mutating assignment, record: - display name, profile, stable child/session IDs when exposed; - deadline and exclusive owned paths; -- branch, HEAD, clean/dirty status, changed paths, and patch artifact. +- branch, HEAD, clean/dirty status, and changed paths; retain a patch artifact when needed to distinguish concurrent or interrupted edits. After delivery, capture the same Git evidence and inspect the patch. Treat the entire ambiguous profile/run as a mutator when stable identity is unavailable. Reject unexpected commits and paths outside ownership. -On an ownership or Git invariant failure, freeze mutation and present evidence-backed choices: inspect, accept and replan, restore with a non-destructive patch, or abort. Obtain a user decision before proceeding. +On an ownership or Git invariant failure, freeze affected mutation and inspect the evidence. Resume automatically only when ownership is re-established, prior children are terminal, and the next action preserves all work within existing authority. Ask with evidence-backed options when recovery would discard work, change agreed behavior, accept uncertain ownership, or broaden scope. On deadline expiry or missing delivery, request stop through the available control surface and prove the process/session terminal before reassignment. A completed UI indicator is not output or liveness proof. Keep the workflow blocked for human termination/takeover when liveness remains unknown. @@ -37,9 +37,9 @@ Reconstruct observed reality before trusting prose: 2. Discover candidate records from observed branches/worktrees and repository conventions. 3. Treat a workflow branch/worktree without a record as an orphan. Preserve it; inspect branch, base, reflog, status, commits, and diff; ask whether to adopt it with a record, quarantine it, or remove it after separate cleanup approval. 4. Compare the record's base, branch, and checkpoint with Git evidence. -5. Preserve atomic-update temporary files. Use the last committed valid record until recovery is approved. +5. Preserve atomic-update temporary files. Prefer the latest valid saved record only after reconciling it with Git; distinguish saved from committed checkpoints. When interrupted-write evidence conflicts, use a committed valid record as a fallback if available, then inspect and resolve uncertainty before mutation. Absence of an initial record commit alone is not an orphan or approval gate. 6. Rebuild task state from completed evidence and the recorded next action. 7. Freeze interrupted mutation until its diff is inspected and prior child liveness is terminal. 8. Resume from the last proven checkpoint. -Ask when evidence conflicts, scope may have changed, child liveness is unknown, or recovery needs risk. Treat the record as a recovery map, not a transaction log. +Ask when conflicting evidence remains unresolved, scope needs a new decision, child liveness cannot be proven, or recovery crosses an approval boundary. Resume routine work automatically when inspection restores the evidence within existing authority. Treat the record as a recovery map, not a transaction log. diff --git a/skills/develop/develop-workflow/references/git-and-integration.md b/skills/develop/develop-workflow/references/git-and-integration.md index 9c690f3..480c2f7 100644 --- a/skills/develop/develop-workflow/references/git-and-integration.md +++ b/skills/develop/develop-workflow/references/git-and-integration.md @@ -2,39 +2,28 @@ ## Isolation -Record the source branch and exact base before creating `./.worktrees/` on `feature/`. Prove every shell location with explicit `cd` or `git -C`; verify `git rev-parse --show-toplevel` before mutation. Block on collisions, unmerged paths, unexpected ownership, or an unignored worktree root. Never rename, reset, clean, stash, copy source changes, or remove an orphan silently. +Record the source branch and exact base before creating `./.worktrees/` on `feature/`. Prove shell locations with explicit `cd` or `git -C`; verify `git rev-parse --show-toplevel` before mutation. Block on collisions, unmerged paths, unexpected ownership, or an unignored worktree root. Never rename, reset, clean, stash, copy source changes, or remove an orphan silently. -A dirty source checkout requires bounded status/path evidence and explicit approval because its changes are omitted. Preserve that evidence in the record. +A dirty source checkout requires bounded status/path evidence and explicit approval because its changes are omitted. Preserve that evidence in the record. Do not disturb another workflow's worktree or changes. ## Synchronize and pin review -After focused commits and verification: +Fetch the latest source branch when a remote exists and rebase onto the intended latest source commit before final verification where practical. Inspect any resulting delta and apply [verification invalidation](verification.md#reuse-and-invalidation); rerun affected checks rather than restarting all phases automatically. Ask before resolving conflicts that change agreed behavior, rewriting shared history, force operations, or non-fast-forward integration. -1. Fetch the latest source branch when a remote exists. -2. Rebase the feature branch onto the latest source commit. -3. Rerun affected checks and full required verification whenever rebase changes the effective tree or resolves conflicts. -4. Record the review base, product HEAD, clean status, tree hash, and commit list. -5. Generate exact review bytes: +Create focused commits after their applicable checks pass. Pin the review base, product HEAD, clean status, tree hash, commit list, exact binary diff command, and digest using [review policy](review-and-remediation.md). Keep product approval attached to immutable evidence, including targeted follow-up on subsequent fixes. -```bash -git diff --binary --full-index --find-renames ... -- -``` - -6. Hash those bytes with SHA-256 and record the command and digest. Regenerate from the durable commits rather than committing a duplicate patch. - -Ask before conflict resolution changes approved behavior, history rewrite of shared work, force operations, or non-fast-forward integration. +Update the record at meaningful boundaries and batch it with related commits. Neither an initial record-only commit nor a commit per decision is mandatory. A saved, uncommitted record is recovery evidence, but verify it against Git rather than assuming it was previously committed. ## Fast-forward integration -After both review axes approve the exact fingerprint: +After independent review and final required verification: -1. Confirm the source branch still equals the final rebase base. Return to synchronize, verify, and review if it advanced. +1. Confirm the source branch still equals the integration base. If it advanced, inspect the delta, synchronize, invalidate affected checks, and refresh review coverage for changed interactions. Reuse unaffected evidence only with justification. 2. Confirm the source checkout exists, is clean, and is safe to update. Stop when dirty or missing. -3. Fast-forward the source branch to the reviewed feature branch; create no merge commit. -4. In the source checkout, update only the workflow record with bound review and integration evidence. -5. Prove the closure diff touches only that record, run applicable documentation checks, and create one metadata-only closure commit. -6. Run a cheap final sanity check. -7. Prove the product and closure commits reachable from the source branch. -8. Remove the completed worktree, then delete its feature branch. +3. Confirm the final product changes are covered by review and verification. Evidence-only updates to the workflow record may follow review only after proving they change results/status, not scope, acceptance, policy, or executable instructions. Review other changes normally. +4. Fast-forward the source branch to the feature branch; create no merge commit. +5. Save integration evidence in the record. Batch it with a pending evidence update or use an optional record-only commit when needed to retain final results. Prove any post-review evidence commit touches only the record and run its applicable checks; there is no mandatory separate closure-commit gate. +6. Run a cheap sanity check, prove all product and retained evidence commits reachable from the source branch, and verify clean source/worktree state. +7. Remove only the workflow-owned worktree, then delete its feature branch. -Treat cleanup in step 8 as pre-authorized only after every preceding clean-state and reachability proof. Ask before any other destructive cleanup. Pushing, publishing, deployment, and production access remain separate user actions. +Cleanup in step 7 is pre-authorized only after the ownership, reachability, and clean-state proofs. Ask before other destructive cleanup. Push, publish, deployment, and production access remain separate scoped actions. diff --git a/skills/develop/develop-workflow/references/review-and-remediation.md b/skills/develop/develop-workflow/references/review-and-remediation.md index c9519b6..e0a02d4 100644 --- a/skills/develop/develop-workflow/references/review-and-remediation.md +++ b/skills/develop/develop-workflow/references/review-and-remediation.md @@ -1,33 +1,9 @@ # Independent review and remediation -## Identity and capability +Use the shared [code-review skill](../../code-review/SKILL.md) as the single source of truth for reviewer selection, pinned evidence, both review axes, findings, and follow-up. One non-author reviewer is the default; additional reviewers require distinct risk or repository policy. -Exclude every identity that authored or mutated the reviewed diff. Record reviewer display name, profile, child ID, and session ID when available. When stable identity is unavailable, exclude the entire ambiguous profile/run. Keep reviewers read-only and separate for: +For workflow reviews, supply the retained record and originating request as the specification, along with repository standards, mutator identities, immutable base/product commits, tree/status evidence, exact binary diff command, and SHA-256. Record the delivered identity and verdict. Leave fixes to an implementer, never the reviewer. -- **Standards:** repository instructions and documented conventions. -- **Specification:** the approved workflow record and linked source plan/spec. +Review after focused checks and synchronization, before the final full-suite boundary. For a bounded fix, run affected checks and obtain targeted follow-up from the same independent reviewer covering the new fingerprint and interactions. Broaden review when prior conclusions no longer apply. Keep verification evidence and code-review approval separate: neither substitutes for the other. -Use Git-capable reviewer profiles with repository read access and no declared `write` or `edit` tools. Shell access can still mutate; capture status, tree, HEAD, and changed paths before and after review. Any mutation invalidates the verdict and marks that identity as a mutator. - -## Review brief - -Generate the brief in the parent. Include: - -- pinned base and product HEAD; -- clean status and product tree hash; -- commit list; -- exact `git diff --binary --full-index --find-renames ... --` command; -- SHA-256 of those exact bytes; -- approved record/specification sources; -- repository standards sources; -- all excluded mutator identities. - -Launch standards and specification reviewers through separate direct subagent calls. Avoid wrapped parallel launch until its delivery defect is proven fixed. Require each reviewer to regenerate the pinned diff, confirm its digest before review, remain read-only, and bind every finding to file/hunk evidence and severity. Treat a missing result or digest mismatch as no verdict. - -Approval binds to base, product HEAD, clean status, tree hash, and diff digest. Permit a later closure commit outside that fingerprint only after proving it changes the workflow record alone. - -## Findings and remediation - -Validate findings against repository evidence. Send accepted fixes to an original implementer or another non-reviewer, never the reviewer. Preserve exclusive path ownership and assignment evidence. Rerun affected checks and the full required suite, create focused commits, and generate a new fingerprint. - -Launch fresh independent reviewers for the changed diff. Escalate after two unsuccessful remediation cycles or whenever a finding requires material scope, acceptance, ownership, verification, or architecture changes; return to plan approval before further production mutation. +After review, record-only evidence updates may be excluded only under the narrow [integration rule](git-and-integration.md#fast-forward-integration). Scope, specification, policy, and executable-instruction changes are not evidence-only updates. diff --git a/skills/develop/develop-workflow/references/verification.md b/skills/develop/develop-workflow/references/verification.md new file mode 100644 index 0000000..3e7cb35 --- /dev/null +++ b/skills/develop/develop-workflow/references/verification.md @@ -0,0 +1,36 @@ +# Proportionate verification + +## Choose tests by the changed contract + +Cover meaningful behavior, important boundaries, and credible failure modes. Prefer existing test seams and realistic minimal fixtures. + +- Unit tests establish logic and regressions through public interfaces. +- Integration tests establish contracts unit tests cannot, such as persistence or process boundaries. +- E2E tests establish important user journeys and changed wiring. Avoid replaying every unit-level permutation through the UI. +- Validate changed UI in its real interface. One realistic scenario may supply both automated and interface-validation evidence when it actually establishes both. +- Simple straightforward code does not need a test for every branch. Avoid assertions that restate implementation, snapshots of incidental details, and regression tests preserving intentionally removed behavior. +- For authorized disposable data, verify fresh initialization/reset, representative seed data, and affected behavior. Add historical upgrade/rollback coverage only when data or compatibility must be preserved. + +When test infrastructure threatens to become larger than the feature, reassess the seam and failure cost before expanding it. Do not impose a coverage percentage or time cap that leaves consequential behavior untested. Security, valuable data, and broad shared-code changes can warrant more testing than implementation. + +## Development and final checks + +Run focused checks during implementation and after review fixes. Schedule one full required suite after review/remediation and synchronization, together with applicable static/build checks. Reuse an already completed check instead of running it again merely because a new phase started. + +Before a commit, run the checks appropriate to its changes; earlier review commits may rely on focused checks. The final integration boundary still requires the full suite. Repository or CI rules requiring stricter pre-commit checks take precedence. Pure documentation changes may use documentation checks when repository policy permits; executable skill instructions need policy validation, not arbitrary prose snapshots. + +## Reuse and invalidation + +Record the command, working directory, exit/result, tested commit or tree, and relevant environment/configuration. Evidence is reusable only when the command and relevant code, tests, dependencies, configuration, and environment remain applicable and the process actually completed. + +- A commit-only change, record evidence update, or unrelated prose edit does not automatically invalidate product tests. Check documentation links/formatting as applicable. +- A bounded behavior fix requires affected tests and targeted review. Preserve other results only with an evidence-backed impact assessment. +- Shared code, dependency/build configuration, conflicting rebases, or uncertain impact require broader checks, including the full suite when its coverage may be affected. +- If the source branch advanced, inspect the actual delta. Do not equate a new commit ID with changed test inputs, or assume disjoint filenames imply no interaction. +- Failed, aborted, stale, or environmental checks remain visible. Retry with a reason; never convert a failure to a pass by inference. + +“One final full run” removes scheduled duplication, not legitimate reruns after failures or invalidation. If new fixes affect the verified state, rerun the required checks and make the review cover the changed diff before integration. + +## External verification gates + +Inspect repository scripts, CI requirements, and active hook policy before promising evidence reuse. An exact-command hook may require a standalone full command even when a focused command passes. Its requirements remain binding until explicitly changed or waived under its own policy. Record a waiver as skipped, never passed; avoid routine waivers as a substitute for aligning policy. Scope hook/config changes separately rather than inventing a workflow verification cache.