corp-v1-channel-architecture/references/delegated-solution-package-tdd.md

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.