142 lines
12 KiB
Markdown
142 lines
12 KiB
Markdown
# Delegated solution-package TDD and handoff pattern
|
|
|
|
Use this reference when one change must transition several approved Features and add their complete Architecture/Kanban packages.
|
|
|
|
## RED contract
|
|
|
|
Add one repository-level contract test before changing canonical records. It should assert, for every exact Epic/Feature/task/ADR ID. For every Task, bind decisions, lifecycle/flow events, evidence, history, and governance hashes to `canonical_id: TASK-<ZERO_PADDED_NUMBER>`; treat `display_id: <CODE>-TS-<NUMBER>` only as a separate reader-facing alias:
|
|
|
|
- delegated actor identity, authority basis, exact state, date, conditions, evidence URL, and event ID;
|
|
- append-only decision-history continuity and baseline hash registration;
|
|
- a complete Feature package: C4 impact, diagram link/rationale, interfaces, flows, technical dependencies/risks, version proposal, implementation decision, and handoff;
|
|
- reciprocal Feature↔FR/NFR/ADR/task links;
|
|
- acyclic dependency-aware task ordering, exact repository/component ownership, future acceptance-evidence specification, and `delivery_started: false`;
|
|
- release-wide task completeness: every Feature assigned to the release has an Architecture-reviewed task breakdown, every required Task and dependency is present, and planning readiness remains false when coverage or dependency closure is incomplete;
|
|
- exact-task Kanban admission as a separate decision.
|
|
|
|
Run only that test and confirm an expected missing-behavior assertion, not a parser, command-line, syntax, or setup error.
|
|
|
|
## GREEN implementation order
|
|
|
|
1. Extend the canonical validator and public types to model delegated authority without weakening human decisions. Bind the delegated identity to a manifest allowlist and validate the authority basis and safe durable delegation URL.
|
|
2. Append lifecycle events; never rewrite baseline history. Compute hashes with the repository's canonical hash function and add each event to the baseline manifest.
|
|
3. Add solution packages and separate Architecture-owned technical risks/dependencies from Scope-owned questions/dependencies.
|
|
4. Add accepted FR/NFR/ADR records, then small task records and reciprocal indexes.
|
|
5. Encode implementation sequence in task dependencies rather than prose alone.
|
|
6. Regenerate indexes using repository scripts.
|
|
7. Update generated-data components and current-state prose together. Preserve verified implementation as baseline evidence, not target acceptance evidence.
|
|
|
|
## Adversarial closure contract
|
|
|
|
A green happy-path suite is insufficient for a multi-Feature solution package. Before publication, add negative mutations and prove the validator rejects each class below.
|
|
|
|
### Evidence ownership
|
|
|
|
- A `canonical-record` evidence path must equal the exact owning collection/ID path, not merely match a broad path regex.
|
|
- The cited item, state, and event must belong to that same record.
|
|
- Test a valid-looking cross-record forgery, such as an FT-1 event citing the FT-2 path; testing only a syntactically invalid path does not close the gap.
|
|
- Derive public verification fields while loader metadata such as collection and filename is still present. Strip private metadata only after verification; assert it is absent from serialized public data.
|
|
|
|
### Conditions and sequencing
|
|
|
|
- Every interface and data flow must preserve all applicable approval-question conditions, reject unknown IDs, and reject known but non-applicable IDs.
|
|
- Enforce the canonical handoff sequence as data, not prose only.
|
|
- Test removal of each required cross-Feature stage gate. Acyclicity and rank ordering alone do not detect omitted predecessors.
|
|
- Test removal of an assigned Feature's required Task, terminal predecessor, or dependency and prove that release planning readiness fails closed.
|
|
- Check reciprocal requirement/task ownership and exact acceptance-outcome indexes, not only that IDs exist.
|
|
|
|
### Testable requirements and tasks
|
|
|
|
- Architecture owns complete release-wide Feature-to-Task decomposition.
|
|
- Architecture creates missing Tasks and reviews, retains, revises, supersedes, or removes existing Tasks against current Feature outcomes and Architecture boundaries.
|
|
- Only draft Tasks with no implementation approval, Kanban admission, execution, or completion evidence may be freely revised or removed.
|
|
- Approved, Kanban-admitted, in-progress, or completed Tasks must not be deleted or silently rewritten.
|
|
- Obsolete protected Tasks retain prior evidence and history, use terminal Superseded or Cancelled status, and carry explicit replacement links when replaced.
|
|
- Every governed Feature requires between two and six independently executable Tasks; one Task is permitted only with a recorded Architecture rationale proving it is the smallest atomic, independently verifiable boundary.
|
|
- Task mappings must be exact and reciprocal for every acceptance-outcome ID and every applicable active `FR-*` and `NFR-*` record.
|
|
- Every entry Task must depend on all terminal Tasks of every prerequisite Feature.
|
|
- A material scope, outcome, dependency, repository, or component change invalidates existing implementation approval, returns the Task to its pre-approval state, and always requires renewed `Approved for Implementation` under the active authority contract before implementation can resume; execution then requires a separate exact-task Kanban Focus admission.
|
|
- Functional requirements need structured measurable criteria: `given`, `when`, `then`, and the future evidence required to prove the assertion.
|
|
- Criteria must name concrete inputs, observable outputs, boundaries, invalid behavior, and pass/fail expectations; title-restating acceptance text is not sufficient.
|
|
- Task outcomes and acceptance evidence must be specific to the implementation boundary and must not claim future tests or reviews already exist.
|
|
- Task contracts must identify implementation artifacts, concrete inputs and outputs, failure boundaries, explicit exclusions, verification steps, and task-specific future acceptance evidence; generated placeholder wording fails the package gate even when IDs and aggregate coverage are complete.
|
|
- Verify evaluator versus presenter/debrief tasks have not accidentally exchanged FRs or outcome ownership.
|
|
|
|
### C4 and publication truth
|
|
|
|
- Separate a source-verified implementation baseline from the approved target design. A target solution package must not link to a diagram or overview that still says its components/contracts are absent or merely proposed.
|
|
- Ensure every target relationship described in prose exists in editable Draw.io—for example evaluator outputs feeding the debrief pipeline—and ensure edge labels identify the actual payload owner.
|
|
- Type and render every material contract field: producer, consumer, schema owner, ordering/timing, persistence, error behavior, and unresolved conditions.
|
|
- Search dated steering/current-state prose for stale “remediation in progress,” “no artifacts,” or old approval-authority claims.
|
|
|
|
## Public-data and browser verification
|
|
|
|
After canonical validation, inspect the production/public adapter separately:
|
|
|
|
1. assert all expected Epic/Feature lifecycle decisions publish as verified;
|
|
2. assert conditional solution approval publishes as verified while unconditional entry readiness remains false;
|
|
3. assert every admitted task publishes its exact verified flow state;
|
|
4. assert no loader-private metadata leaks;
|
|
5. exercise the Board/Focus adapters against production records and prove they contain the expected Epic, Features, and tasks;
|
|
6. build and restart the local static server after the final build—an already-running server may retain an older bundle;
|
|
7. browse at the real Docusaurus `baseUrl`, not the root route;
|
|
8. verify Scope renders delegated approval evidence rather than a false “not recorded” state, Architecture renders conditions/contracts/version honestly, Board contains governed Epics/Features, Focus contains admitted tasks, and the Draw.io SVG appears without console/resource errors.
|
|
|
|
Do not use unconditional entry readiness to decide whether a conditional approval record exists. Present these as distinct facts:
|
|
|
|
- approval record verified;
|
|
- conditions preserved;
|
|
- unconditional entry readiness true/false;
|
|
- solution package complete/incomplete.
|
|
|
|
## Independent fail-closed review loop
|
|
|
|
Freeze the complete effective diff—including intentional uncommitted review corrections—and give a read-only reviewer explicit permission to adversarially inspect it. A reviewer PASS is a publication gate; a BLOCK must be remediated with RED/GREEN evidence and sent to a fresh reviewer.
|
|
|
|
The reviewer should inspect more than test output:
|
|
|
|
- stale diagrams and prose;
|
|
- semantic FR/task alignment;
|
|
- public adapter derivation order;
|
|
- rendered browser truth;
|
|
- omitted dependencies/conditions;
|
|
- cross-record evidence forgery;
|
|
- implementation/release/deployment overclaims.
|
|
|
|
Do not weaken validators to obtain PASS. Keep iterating until a fresh review returns PASS against the final effective candidate.
|
|
|
|
## Validation discipline
|
|
|
|
Before rewriting mutable pages, inspect repository validators and tests for required headings, historical-snapshot markers, and route contracts. Dynamic data migration does not authorize deleting validator-required static markers; preserve or intentionally update the contract test and validator together.
|
|
|
|
Reserve execution budget for this exact finish sequence:
|
|
|
|
1. targeted contract test;
|
|
2. full tests;
|
|
3. data validation and deterministic index check using scripts that actually exist in `package.json`;
|
|
4. Scope, Architecture, and Kanban validators;
|
|
5. typecheck;
|
|
6. strict production build and dependency audit;
|
|
7. `git diff --check`, generated-file drift check, path inventory, and uncommitted status inspection;
|
|
8. production/public-data assertions and browser verification;
|
|
9. independent fail-closed review;
|
|
10. commit, push, PR readback, complete paginated changed-file readback, and exact-head terminal CI by SHA.
|
|
|
|
Do not report “fully validated” unless all required stages passed after the final edit. If execution stops early, enumerate the exact failing checks and leave no stronger completion claim.
|
|
|
|
## Common failure modes
|
|
|
|
- Assuming a semantically related Discord URL is the authority source instead of preserving the exact canonical delegation URL.
|
|
- Updating the validator's actor error wording without updating its negative assertion.
|
|
- Enforcing complete-package fields on minimal unit fixtures globally. Prefer an explicit manifest capability flag for repositories that require complete packages, while keeping focused validator fixtures small.
|
|
- Replacing current-state prose and accidentally removing headings required by page validators.
|
|
- Invoking guessed script names such as `data:index:check`; read `package.json` and execute only declared scripts or an explicit generate-and-diff equivalent.
|
|
- Spending the validation budget on broad prose rewrites before the repository's static contracts are known.
|
|
- Treating canonical validation as proof that public adapters derived verification fields correctly.
|
|
- Stripping collection/filename metadata before exact-path evidence verification.
|
|
- Testing malformed evidence only, while a valid-looking cross-record forgery still passes.
|
|
- Checking only DAG/rank validity while required stage-gate edges can be removed.
|
|
- Rendering only summary interface fields while silently dropping ownership, timing, persistence, errors, or conditions.
|
|
- Reusing a browser server started before the latest build and misclassifying its stale bundle as current output.
|
|
- Trusting the first default-sized PR-files API page as the complete changed-file list; follow pagination until an empty/short page and verify required artifacts across the union.
|