refactor: implement governed Delivery program contracts
This commit is contained in:
1 parent
c306ea4794
commit
65e546c448
18 files changed
+575
-99
No files matched your search
@@ -1,6 +1,11 @@
|
||||
# the adopted project Task Delivery Gates
|
||||
|
||||
This file contains the complete ordered procedure for delivering one the adopted project Task. Load it before selecting or continuing a Task.
|
||||
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.
|
||||
|
||||
**Bounded unresolved A02/A04:** substantive push/review order and “base drift is harmless” remain recorded local clauses pending the separate exact resolution. This consolidation does not choose between them and the reusable owner's ordering/base rule. Do not treat the load as approval of a new exception; route an affected conflict before acting.
|
||||
|
||||
## End-to-End Task Delivery Gates
|
||||
|
||||
@@ -10,7 +15,7 @@ These gates are mandatory and ordered. Each `GATE_###_NAME` code is the stable i
|
||||
- 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>`.
|
||||
|
||||
All local work and evidence for a Task is isolated under `<code>-delivery/workspace/<TASK_ID>/`. Start with the required repository clones. Create Task-local `review/`, `cache/`, `tmp/`, `logs/`, or `artifacts/` only when a concrete activity for that Task needs them. Reusable installed toolchains and technical dependencies belong in `<code>-delivery/cache/` so later Tasks can reuse verified versions. Channel-provided input files belong in `<code>-delivery/uploads/`.
|
||||
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 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 implementation or review subagent may work on the selected Task.
|
||||
|
||||
@@ -18,19 +23,17 @@ Verification is part of each stage, not a separate end checklist. Before leaving
|
||||
|
||||
### Mandatory gate-failure recovery
|
||||
|
||||
If any check, command, test, review, CI job, merge precondition, integration check, publication check, or Exit gate fails, the Task remains in that same gate. Hermes must diagnose the root cause, implement the smallest safe forward fix within the approved Task scope, rerun every affected check, and repeat this repair-and-verification loop until the complete gate passes. A repairable failure is work to fix; it is not a stopping point, a reason to abandon the Task, or permission to start another Task.
|
||||
|
||||
Hermes may pause the repair loop only when progress requires an unavailable external dependency or credential, a human decision or permission, a change outside the approved requirements or Architecture, or an unsafe, destructive, or otherwise unauthorized action. In that case, keep the Task's lifecycle status unchanged, record `BLOCKED` separately with the exact evidence, responsible owner, and next action, and resume the same gate as soon as the blocker is removed. Never bypass, weaken, suppress, or relabel a failed gate to make it pass.
|
||||
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:** First read `corp-v1-<code>/corp-v1-<code>-documentation` remote `test` without creating a branch. After one eligible Task is identified, create `<code>-delivery/workspace/<TASK_ID>/`. Create only its initial fresh repository clones: clone the application repository into `application/` and documentation repository into `documentation/`. Do not create optional support folders during preparation. In `application/`, create branch `<release>/<TASK_ID>-<short-explanation>-<attempt>` from application `test`, with a PR whose title exactly equals the branch name and whose base is `test`. In `documentation/`, create branch `<release>/<TASK_ID>-start-delivery-<attempt>` into documentation `test`, with the same title/base rules.
|
||||
**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. Do not use HermesSubAgent or cron.
|
||||
|
||||
**Required work:** Verify that the Task file says `READY_FOR_DELIVERY`, the Board places the Task in the current wave, dependencies have reached the states required by the Task, the parent Feature has implementation approval, and required Architecture, requirements, target release, and UI/UX inputs exist. Inspect only the adopted project's eight project channels and select exactly one Task. Create the Task workspace and fresh application/documentation clones before repository mutation. Fetch application `test`; create the exact local application branch; use an empty kickoff commit if Gitea requires a difference; push; open the application PR; and verify that local branch, remote branch, PR head branch, local head, remote head, PR title, and `test` base match. Then use the Task's documentation clone to add the hash-linked `READY_FOR_DELIVERY` to `IN_PROGRESS` event with actor, time, Task, wave, application branch/PR evidence, previous hash, and new hash, and merge that documentation change.
|
||||
**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:** The Task directory exists under `<code>-delivery/workspace/<TASK_ID>/`; its required `application/` and `documentation/` clones exist and have the expected remotes; no optional support folder was created without a concrete Task need; no Task checkout was created elsewhere; the application branch and PR are visible and all identities match; the documentation PR is merged; and the Task file on remote documentation `test` says `IN_PROGRESS`. Only then may source, test, configuration, or application documentation files be edited. Report the selected Task, wave, satisfied dependencies, application PR, Task workspace, and merged status change. If eligibility evidence is missing or contradictory, do not select or mutate the Task and do not create the application branch; stop and name the responsible owner.
|
||||
**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
|
||||
|
||||
@@ -46,18 +49,18 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
|
||||
|
||||
**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:** Hermes main session runs the implementation and review loops with local repository tools inside the selected Task directory. Create and use optional `review/`, `cache/`, `tmp/`, `logs/`, or `artifacts/` folders only when the current activity needs them. Repeat environment and real-working-directory preflight in every foreground shell, review checkout, background process, main-session review command, and CI job. Do not use an implementation or review subagent, human-review dependency, or cron to satisfy this gate.
|
||||
**Runtime:** Main session implements and reviews inside the selected Task workspace. Load runtime preflight before every execution context and create optional folders only for concrete needs. No implementation/review subagent, human-review dependency or cron.
|
||||
|
||||
**Required work:**
|
||||
|
||||
1. Resolve the real working directory and verify it is inside `<code>-delivery/workspace/<TASK_ID>/`; then verify branch and PR identity, repository state, required tools and committed versions, and required environment-variable names without printing values. For Node/pnpm work, check the resolved `node` and `pnpm` commands and versions. Delivery unit tests use process-local fakes and must not start runtime services; UAT owns resource-dependent testing.
|
||||
2. For a defect, write or identify an exact named unit test and show that it fails for the expected product reason before repair. For new behavior, add a failing unit test first when practical and request the required non-unit coverage from UAT. Syntax, tooling, environment, or credentials errors do not count as product evidence.
|
||||
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. After local checks pass, commit and push the Task changes without rewriting history. Read back the remote branch and PR and verify that the local checked revision, remote branch head, and PR head are identical.
|
||||
6. Hermes main session reviews that exact PR head for logic, security, acceptance coverage, production-path use, and test gaps. Tests alone are not the review. The main session must inspect the complete diff and relevant production paths, record a pass/fail verdict for the exact revision, and remain accountable for that verdict. If review finds a problem, remain in `GATE_003_TASK_IMPLEMENTATION`: repair it on the same Task branch, rerun affected local checks, push the new PR head, and review that exact head again.
|
||||
|
||||
**Exit gate:** Every local command and review used the selected Task workspace, and every optional support folder had a concrete Task need; every acceptance criterion has implementation and test evidence; every required local check passes; the local checked revision, remote branch head, and PR head are identical; and that exact PR head has a passing review with no unresolved logic, security, acceptance, or material test finding. Any later file change keeps or returns the Task to `GATE_003_TASK_IMPLEMENTATION` until affected checks, push/readback, and review pass again. Any failure report names the exact command, file, test, or review finding; observed and expected behavior; failure class; mutation state; and repair or owner.
|
||||
**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, push/readback and review 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
|
||||
|
||||
@@ -67,10 +70,10 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
|
||||
|
||||
**Required work:**
|
||||
|
||||
1. Verify that every required Delivery CI job—unit tests, lint, typecheck, build, static security checks, and artifact publication validation—passes on the exact PR head reviewed in `GATE_003_TASK_IMPLEMENTATION` and within one complete successful attempt. Never combine passing jobs from different revisions or attempts.
|
||||
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 base drift is harmless.
|
||||
3. If conflict resolution, rebase, or any file/tree change is required, return to `GATE_003_TASK_IMPLEMENTATION`; repeat affected local checks, push/readback, and review for the new PR head; then restart `GATE_004_TASK_PR_CI` for that exact head.
|
||||
4. Merge without rewriting the reviewed PR head. Read back the merged PR and resulting application `test` revision.
|
||||
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`.
|
||||
|
||||
@@ -82,7 +85,7 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
|
||||
|
||||
**Required work:**
|
||||
|
||||
1. Verify every required application unit-test/build job, container build, immutable image publication, registry digest readback, and artifact check on the exact application `test` integration revision. PR-head CI cannot replace post-merge integration evidence.
|
||||
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.
|
||||
|
||||
Reference in new issue
Block a user