Files
channel-delivery-skic/references/task-delivery-gates.md
T

113 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# the adopted project Task Delivery Gates
This file contains the ordered Delivery overlay for delivering one the adopted project Task. Load it before selecting or continuing a Task.
Before candidate review, CI, merge or integration verification, run `skill_view(name="development-gates")` and load `references/review-ci-merge-contract.md`. Its Evidence model and Attempt integrity own immutable identities, complete required job/aggregate inventory, one successful attempt and separate integration evidence. Use those mechanics at each stage; retain the local exit outcomes and reviewer/authority bindings below. Missing owner guidance blocks the affected gate.
**Global gate alignment (A02/A04):** apply `development-gates` without project exceptions to review independence, substantive push ordering or base-change invalidation. Visibility-only kickoff publication does not publish implementation. The sequence below also applies to documentation claims/handoffs and GitOps candidates, not only application changes.
## End-to-End Task Delivery Gates
These gates are mandatory and ordered. Each `GATE_###_NAME` code is the stable identifier used in communication and evidence. Hermes must not skip ahead, combine evidence from different revisions, or start the next Task before `GATE_005_TASK_POST_MERGE` passes. The three repositories used by this process are:
- application: `corp-v1-<code>/corp-v1-<code>`;
- Task files and project documentation: `corp-v1-<code>/corp-v1-<code>-documentation`; and
- this Delivery skill: `corp-v1-<code>-skills-code-agent/channel-delivery-skic-<code>`.
Before repository entry, load [repository-entry-and-visibility.md](repository-entry-and-visibility.md) for the complete entry/branch/visibility contract and [runtime-and-ci.md](runtime-and-ci.md#channel-owned-workspace) for required clones, optional directories, reusable cache and Task isolation. These remain mandatory gate inputs, not optional background reading.
Hermes main session owns the Task, performs implementation and obtains independent exact-head review, and communicates with the active project authority. Local repository tools execute deterministic commands. Gitea Actions runs remote CI. Gondor/GitOps is used only by an approved deployment or Release process. Cron never owns or continues a Task. No second implementation worker may work on the selected Task. A separate read-only reviewer is required; review is not implementation ownership.
Verification is part of each stage, not a separate end checklist. Before leaving a stage, pass its **Exit gate** and retain the evidence named there. Every Delivery progress, blocker, CI, merge, handoff, and completion update must name the active gate code and title. When a gate passes, report the passed gate code and the next gate code. At every stage, use only the adopted project's eight project channels, load the references and engineering skills required for that action, route contradictions instead of guessing, and report failures with the exact command, file, test, or CI job.
### Mandatory gate-failure recovery
Before repairing any failed check/review/CI/publication/exit condition, load [Failure-Repair Workflow](failure-and-documentation.md#failure-repair-workflow). It owns diagnosis, scope-safe forward repair, affected revalidation, blocker evidence and routing. Remain in the same gate until its complete exit passes; never weaken or relabel a failed gate. Pause only for its external-dependency, credential, decision, authority or safety blocker, recording `BLOCKED` separately without changing lifecycle status. Resume the same gate when removed.
### Stage 1 — `GATE_001_PREP` — Pick, Start, and Open the Task PR
**Repository and branch:** Read documentation remote `test` before branching. Establish fresh `application/` and `documentation/` clones inside the selected Task workspace under the loaded entry contract. Application branch: `<release>/<TASK_ID>-<short-explanation>-<attempt>`; documentation claim branch: `<release>/<TASK_ID>-start-delivery-<attempt>`. Each PR title equals its branch and targets `test`.
**Runtime:** Hermes main session verifies eligibility, creates and reads back the application branch and PR without editing repository content, then creates the documentation branch and PR, updates the Task file, runs documentation checks, and merges the documentation PR only after its checks pass. Gitea Actions runs remote checks. No implementation subagent or cron; obtain independent read-only review before substantive documentation publication.
**Required work:** Apply the loaded entry contract to exactly one current-wave `READY_FOR_DELIVERY` Task: Feature approval, dependencies, Architecture/requirements, target release and UI/UX readiness. Inspect only the adopted project’s eight channels. Establish and read back the application branch/PR before any edit. In the Task’s documentation clone add the hash-linked `READY_FOR_DELIVERY` to `IN_PROGRESS` event with actor, time, Task, wave, branch/PR evidence, previous hash and new hash; validate/review/merge it.
**Exit gate:** Loaded workspace and entry checks pass: required Task-local clones have expected remotes, optional folders have a concrete need, and application branch/PR identity is verified. Documentation claim is merged and remote Task state is `IN_PROGRESS`. Only then edit repository content. Report Task, wave, dependencies, PR, workspace and merged claim. Missing or contradictory eligibility blocks selection, mutation and branch creation; name the owner.
### Stage 2 — `GATE_002_TASK_PLAN` — Plan the Task
**Repository and branch:** Read Task, requirement, Architecture, and UI/UX files from the Task's `documentation/` clone at `test`; keep implementation notes and changes in the Task's `application/` clone on the existing application Task branch.
**Runtime:** Hermes main session inspects documentation and application code. Do not use HermesSubAgent.
**Required work:** Load the project engineering skills needed by the Task. Map each acceptance criterion to affected production code, a named test, edge and failure cases, security boundaries, build or artifact evidence, and its requirement or Architecture reference.
**Exit gate:** Every criterion has a checkable proof. A contradiction stops implementation and goes to the responsible Scope, Architecture, UI/UX, Kanban, or Release owner.
### Stage 3 — `GATE_003_TASK_IMPLEMENTATION` — Implement and Review the Task
**Repository and branch:** Use `<code>-delivery/workspace/<TASK_ID>/application/` on the existing application Task branch and PR. Application source, unit tests, configuration, application-documentation changes, builds, and image/container/Helm artifact validation stay in that clone and branch. Every functional non-unit suite stays in the UAT-owned E2E repository. If a separate review checkout or output is needed, create and use `review/` under the same Task directory.
**Runtime:** Main session is the sole implementer inside the selected Task workspace. The reviewer must not be the candidate implementer: obtain a separate read-only reviewer who must not edit, push, merge or become a second implementer. Load runtime preflight before every execution context and create optional folders only for concrete needs. No new human-review dependency or cron ownership.
**Required work:**
1. Load [runtime-and-ci.md](runtime-and-ci.md#execution-context-toolchain-preflight) and pass its exact-context preflight inside the selected Task workspace before commands. Unit tests use process-local fakes, not runtime services; UAT owns resource-dependent testing.
2. Load `development-method-ttd` and follow mandatory failing-unit-test-first TTD for defects, new behavior and refactors; only an explicitly approved documented exception from the authorized project owner permits departure. Request non-unit coverage from UAT. Tooling, environment and credential failures are not product-test evidence.
3. Implement only the approved Task, one behavior slice at a time. Keep the diff small, cover normal, edge, and failure behavior, avoid unrelated refactors, and repair forward without reverting valid work.
4. Run all applicable focused and full unit tests, lint, format checks, typecheck or compile, production build, production dependency audit, static checks, generated-artifact checks, and Delivery-owned Dockerfile/image/container/publication/Helm artifact validations, plus `git diff --check` and repository-state checks. Do not run functional integration, browser, security-boundary, performance, or acceptance suites in Delivery; request and consume those results from UAT.
5. Freeze and commit the complete locally validated candidate without rewriting shared history. Record candidate head/tree, target-base SHA and merge-base; require a clean candidate worktree. Do not push substantive changes yet.
6. Obtain independent logic/security review of that exact local candidate, including acceptance coverage, production-path use and test gaps. Tests alone are not the review. Record reviewer identity, base/head/tree and PASS/FAIL. Remote CI is not required to issue code-review PASS; publication readiness remains false until its later gates pass. If review finds a problem, stay in `GATE_003_TASK_IMPLEMENTATION`: the sole implementer repairs locally, reruns affected checks, freezes the new commit, and has the reviewer review that exact head again before its next substantive push. Any candidate change invalidates PASS.
7. Push only the exact reviewed head after PASS and verify remote branch/PR head equality with the checked and reviewed local commit. If any identity differs, stop and reconcile; never transfer a verdict to a different head. Required exact-head remote CI is verified in Stage 4.
**Exit gate:** Task-workspace/preflight rules and all local checks pass; every acceptance criterion has implementation/test evidence; `development-gates` candidate identity matches remote branch/PR and exact-head review has no unresolved finding. Later edits keep/return the Task to `GATE_003_TASK_IMPLEMENTATION` until affected checks, independent local review and then push/readback pass. Failure reports use [status-and-reporting.md](status-and-reporting.md): exact command/file/test/finding, observed versus expected behavior, failure class, mutation state and repair/owner.
### Stage 4 — `GATE_004_TASK_PR_CI` — Verify and Merge the Task PR
**Repository and branch:** Use the application PR and `application/` clone inside the selected Task workspace, targeting `corp-v1-<code>/corp-v1-<code>` `test`; then fetch and read the resulting application `test` revision in that same clone after merge.
**Runtime:** Gitea Actions runs PR CI. Hermes main session verifies CI and PR state, confirms independent exact-head review still covers the PR head, performs the authorized Gitea merge, and reads back the merge result. The read-only reviewer never merges; the authorized main session remains the sole writer.
**Required work:**
1. Apply the loaded `development-gates` attempt-integrity contract to all required Delivery jobs: unit tests, lint, typecheck, build, static security and artifact validation, including the required aggregate.
2. Immediately before merge, re-read the PR and current application `test`. Confirm that the PR remains open, its head is unchanged, its base is `test`, its branch equals the reviewed PR head, required CI is green, review still matches, the PR is mergeable, and the target-base SHA still equals the reviewed base. Any target-base SHA change invalidates merge readiness, even when candidate head/tree is unchanged; refresh/synchronize and repeat validation and independent review under `development-gates`. There is no local harmless-drift exception.
3. If conflict resolution, rebase, or any file/tree change is required, return to `GATE_003_TASK_IMPLEMENTATION`; repeat affected local checks, independent review of the frozen local candidate, and then push/readback for the new PR head; then restart `GATE_004_TASK_PR_CI` for that exact head.
4. Apply the loaded owner’s reviewed-head merge and separate integration readback contract within existing merge authority.
**Exit gate:** All required PR CI succeeds on the exact reviewed PR head; the final pre-merge check refers to that same head; the PR is merged; and the exact application `test` integration revision is known. The Task remains `IN_PROGRESS`; merge alone does not mean `TO_BE_RELEASED` or `DONE`.
### Stage 5 — `GATE_005_TASK_POST_MERGE` — Verify Integration and Hand Off the Task
**Repository and branch:** Use the selected Task's `application/` clone to validate `corp-v1-<code>/corp-v1-<code>` `test` at the exact integration revision produced by `GATE_004_TASK_PR_CI`. Then use the same Task's `documentation/` clone to create branch `<release>/<TASK_ID>-release-handoff-<attempt>` into documentation `test`, with a PR title exactly equal to the branch name and base `test`.
**Runtime:** Gitea Actions runs application integration, build, publication, and documentation checks. Hermes main session verifies those results, creates and validates the documentation handoff, applies the review rules from `GATE_003_TASK_IMPLEMENTATION` to the exact documentation PR head, and performs the authorized documentation merge. Gondor/GitOps is used only within approved deployment authority. Apply the deployment and handoff evidence contract below before declaring the handoff complete.
**Required work:**
1. Apply the loaded owner’s separate integration gate to all required application unit/build, container, immutable publication and artifact checks. Retain registry digest readback; PR-head CI cannot replace integration evidence.
2. Complete the deployment and handoff evidence contract below, then add the hash-linked `IN_PROGRESS` to `TO_BE_RELEASED` event with the merged application PR, integration revision, successful integration CI, publication and deployment evidence when required, and the UAT handoff or verified non-runtime exception.
3. Update Ways of Working or Engineering documentation only when this Task changed how the project actually works.
4. Validate, review, merge, and read back the documentation handoff PR.
**Exit gate:** Every required post-merge unit-test, build, and publication job succeeds on the exact application `test` revision; the documentation PR is merged; and the Task file on remote documentation `test` says `TO_BE_RELEASED`. The deployment and handoff evidence contract below must also pass. Only then may Delivery call the Task delivered. Release execution and the later `DONE` transition belong to `channel-releases-skic-<code>`, not this Delivery process.
#### Deployment and handoff evidence
For runtime-affecting work using Delivery → UAT, require a verified non-production deployment before a ready-for-UAT handoff. Resolve the approved deployment owner, target environment, and desired-state repository from the project contract; this requirement grants no deployment authority. Missing authority or deployment evidence is `BLOCKED`, not a successful handoff. If the project requires deployment before `TO_BE_RELEASED`, enforce that gate even when the Task omits it. Only work with no deployable runtime effect may record `not_applicable`, with a verified reason; lack of permission is not such a reason.
Retain the exact integrated application commit, immutable image digests and chart identity where applicable, template provenance, rendered GitOps commit, controller revisions/sync/health, pod image IDs, environment/base URL, verification time, Task identity, and limitations. Follow the owning GitOps workflow, not direct workload mutation. For app-of-apps, distinguish root Git revision from child chart/source revision and verify each against its own desired state. Deployment readback proves identity and operational health, not user-visible acceptance; UAT owns that verdict.
Send the frozen packet to the mapped UAT channel and any release-readiness notification required by the adopted workflow. Retain the destination channel/message ID and readback, or the verified dispatcher delivery receipt; a source-channel mention is not delivery proof. Respect auto-delivery contracts rather than sending duplicate messages, and report delivery as unverified until a receipt exists. A Releases notification routes readiness only; it neither skips UAT nor authorizes release or `DONE`.
### Stage 6 — `GATE_006_NEXT_TASK` — Pick the Next Task
**Repository and branch:** Read refreshed documentation `test` and the Board from the completed Task's `documentation/` clone. Do not reuse that Task directory for another Task and create no new branch until the next Task passes `GATE_001_PREP`, which creates its own workspace and fresh clones.
**Runtime:** Hermes main session selects the next Task. Do not use cron or a subagent for selection.
**Required work:** Confirm the previous Task says `TO_BE_RELEASED`, no delivery blocker remains, capacity is free, and the next Task says `READY_FOR_DELIVERY` with satisfied dependencies.
**Exit gate:** Report the next selected Task and return to `GATE_001_PREP`. Do not wait for `DONE`; release execution and `DONE` are owned by `channel-releases-skic-<code>`.