diff --git a/SKILL.md b/SKILL.md index 1a3d0d5..df1ef49 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: channel-delivery-skic description: "Use when operating or synchronizing a Corp v1 project's delivery channel. Drives coding, unit testing, build and continuous-integration health, attempts safe evidence-based fixes, escalates requirement or architecture contradictions, and maintains Ways of Working and Engineering documentation." -version: 1.17.0 +version: 1.18.0 author: Hermes Agent license: MIT metadata: @@ -169,7 +169,7 @@ Every project adoption must bind this channel to a dedicated local workspace und Before selecting/continuing/reviewing/merging/handoff load [Task gates](references/task-delivery-gates.md); before branch/PR work load [repository entry](references/repository-entry-and-visibility.md). Before commands, CI, images or resource work load [runtime bindings](references/runtime-and-ci.md); before failure repair/docs load [failure/docs bindings](references/failure-and-documentation.md). Before planning changes load [planning reconciliation](references/planning-artifact-reconciliation.md); on failed/resumed gates load [exception checks](references/common-pitfalls.md). -Project adoptions may narrow execution to a main session or prohibit subagents/cron. Preserve that overlay; this reference grants no account recovery, permission, merge, release or deployment authority. Keep exactly one Task active unless explicit project authority defines another safe model. Freeze Task/branch/PR identity and retain exact-head review under the ordered gates. +Project adoptions may narrow implementation execution to a main session or prohibit implementation subagents/cron. Preserve that overlay without prohibiting independent read-only review; this reference grants no account recovery, permission, merge, release or deployment authority. Keep exactly one Task active unless explicit project authority defines another safe model. Freeze Task/branch/PR identity and retain exact-head review under the ordered gates. When selectable controls are needed, provide complete options and their trade-offs, recommended first; follow the active interface's option-rendering contract without hiding consequences. diff --git a/references/planning-artifact-reconciliation.md b/references/planning-artifact-reconciliation.md index 64ed31a..7438f8e 100644 --- a/references/planning-artifact-reconciliation.md +++ b/references/planning-artifact-reconciliation.md @@ -6,7 +6,7 @@ Use when planning or readiness documentation changes while implementation remain Before verifying a PR or CI, run `skill_view(name="development-gates")` and load its `references/review-ci-merge-contract.md`: **Evidence model**, **Attempt integrity**, and **Concurrent publication** own candidate/remote equality, complete successful job inventory including aggregates, and separate integration evidence. Do not use a successful listed-task subset as a gate. -Before reporting, load `skill_view(name="development-integrity")` and its `references/remote-checkpoint-matrix.md` for the current remote checkpoint, changed-head invalidation and candidate-versus-integration claims; then load [status-and-reporting.md](status-and-reporting.md) for Delivery formatting. Preserve project reviewer/merge authority; A02/A04 review-order/base-drift remain bounded unresolved clauses, not implicitly settled by these loads. +Before reporting, load `skill_view(name="development-integrity")` and its `references/remote-checkpoint-matrix.md` for the current remote checkpoint, changed-head invalidation and candidate-versus-integration claims; then load [status-and-reporting.md](status-and-reporting.md) for Delivery formatting. Preserve project merge authority; A02/A04 follow global independent review-before-push and any-target-base-change invalidation without local exceptions. Before validation, load `documentation-docusaurus-global` and the project-adopted overlay through [Documentation Ownership](failure-and-documentation.md#documentation-ownership); verify source identity. Run the complete repository validator and production build with frozen-lockfile installation and `git diff --check`. Generic and VSSA packages now have separate source-qualified names. Retain the bounded nested-pnpm fallback below until that procedure is present in the generic owner; identity repair alone does not establish procedural coverage. diff --git a/references/repository-entry-and-visibility.md b/references/repository-entry-and-visibility.md index db15c2f..580cb6f 100644 --- a/references/repository-entry-and-visibility.md +++ b/references/repository-entry-and-visibility.md @@ -23,6 +23,8 @@ Delivery must verify the Feature decision and exact Task `READY_FOR_DELIVERY` st Before any implementation or repository content change begins on a newly claimed the adopted project Task, establish and verify all of these Gitea checkpoints: +Visibility-only kickoff commits contain no file/tree changes. This exception does not authorize a substantive push: freeze and independently review every implementation or documentation candidate before publication. + 1. Create the dedicated local branch with the required Task branch name, create an empty kickoff commit if needed, and push that exact branch immediately. 2. Open a visible pull request from that exact branch to `test` before editing a repository file. Do not wait for implementation, tests, review, or a finished diff. 3. Put the Task ID, wave, planned scope, and current Task state in the PR so the active project authority and the team can monitor progress from the beginning. diff --git a/references/task-delivery-gates.md b/references/task-delivery-gates.md index 9d9d996..8eb9b92 100644 --- a/references/task-delivery-gates.md +++ b/references/task-delivery-gates.md @@ -5,7 +5,7 @@ This file contains the ordered Delivery overlay for delivering one the adopted p 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. +**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 @@ -17,7 +17,7 @@ These gates are mandatory and ordered. Each `GATE_###_NAME` code is the stable i 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. +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. @@ -29,7 +29,7 @@ Before repairing any failed check/review/CI/publication/exit condition, load [Fa **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: `/--`; documentation claim branch: `/-start-delivery-`. 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. +**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. @@ -49,7 +49,7 @@ Before repairing any failed check/review/CI/publication/exit condition, load [Fa **Repository and branch:** Use `-delivery/workspace//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 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. +**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:** @@ -57,22 +57,23 @@ Before repairing any failed check/review/CI/publication/exit condition, load [Fa 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. +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, 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. +**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-/corp-v1-` `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 its own exact-head review still covers the PR head, performs the authorized Gitea merge, and reads back the merge result. No subagent reviews or merges. +**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 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. +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`. diff --git a/tests/disposition-protected.json b/tests/disposition-protected.json index c95f024..bf310cc 100644 --- a/tests/disposition-protected.json +++ b/tests/disposition-protected.json @@ -1,15 +1,15 @@ [ { "path": "references/task-delivery-gates.md", - "sha256": "4475ccf43b8f026bdc1acee38cbe09969be6a387c71f6724cad94c8cef93e973" + "sha256": "6ecc350c0aaa66551a4bcd9a5da278c55980cce783eaf563a1a7546c1d5ac588" }, { "path": "references/repository-entry-and-visibility.md", - "sha256": "727d2ed32483a895237e6891b4ce78d79442d1c9e002bac4237e438fb9c4426d" + "sha256": "ee89ad297ea28e5a393b8a7e53de487883e64c720276f4055e368086d1c0ba65" }, { "path": "references/planning-artifact-reconciliation.md", - "sha256": "098c16b5f2f5d7a55211cefcc31bdfd8daaffad8433f0a32b34e8bdf0da0c611" + "sha256": "8676cb832199c4e11acc0f9f3abc649364a9ed6eec83d561ffd9c21bc556c3af" }, { "path": "references/aerosim-lessons-review.md", diff --git a/tests/full-program-preserved.json b/tests/full-program-preserved.json index 5e6ca15..9701ea5 100644 --- a/tests/full-program-preserved.json +++ b/tests/full-program-preserved.json @@ -1,32 +1,4 @@ [ - { - "path": "references/task-delivery-gates.md", - "pattern": "^5\\. After local checks pass,.*$", - "hashes": [ - "e4e6ae6f894fdb0b5dc1779b7037c39eb476ee80620f93a253c4a68ea4adabd1" - ] - }, - { - "path": "references/task-delivery-gates.md", - "pattern": "^6\\. (?:The active executor|Hermes main session) reviews.*$", - "hashes": [ - "63acb91e7391daac3af378032e4842ef7da6d03ff1f1939016180f9fffb5f86c" - ] - }, - { - "path": "references/task-delivery-gates.md", - "pattern": "^2\\. Immediately before merge,.*$", - "hashes": [ - "fb6968a7bea4662e945ca914c53988cc1d9d72b02681384f7041a89ad347c229" - ] - }, - { - "path": "references/task-delivery-gates.md", - "pattern": "^3\\. If conflict resolution,.*$", - "hashes": [ - "6052be5ba307b088499acdc0abcecbea36719695f423e6e9b888027d85867e89" - ] - }, { "path": "references/task-delivery-gates.md", "pattern": "^\\*\\*Exit gate:\\*\\* All required PR CI.*$", diff --git a/tests/test_aerosim_lessons_contract.py b/tests/test_aerosim_lessons_contract.py index e9269f1..644fb96 100644 --- a/tests/test_aerosim_lessons_contract.py +++ b/tests/test_aerosim_lessons_contract.py @@ -39,7 +39,7 @@ class LessonsContract(unittest.TestCase): def test_contract_1(self): text = (ROOT / 'SKILL.md').read_text() self.assertIn('-uat', text) - self.assertIn('version: 1.17.0', text) + self.assertIn('version: 1.18.0', text) def test_stage_five_scope_and_authority(self): text = (ROOT / "references/task-delivery-gates.md").read_text() @@ -50,7 +50,7 @@ class LessonsContract(unittest.TestCase): self.assertIn("If the project requires deployment before", stage) self.assertNotIn("only if the Task explicitly includes", stage) self.assertIn("image/container/Helm artifact validation", text) - self.assertIn("No implementation or review subagent", text) + self.assertIn("No second implementation worker", text) if __name__ == "__main__": diff --git a/tests/test_global_gate_alignment.py b/tests/test_global_gate_alignment.py new file mode 100644 index 0000000..7931501 --- /dev/null +++ b/tests/test_global_gate_alignment.py @@ -0,0 +1,34 @@ +"""Central executable policy follows the global exact-candidate gates.""" +from pathlib import Path +import unittest +ROOT = Path(__file__).resolve().parents[1] +class GlobalGateAlignment(unittest.TestCase): + def test_review_before_substantive_push(self): + gates = (ROOT/'references/task-delivery-gates.md').read_text() + stage = gates.split('### Stage 3')[1].split('### Stage 4')[0] + self.assertLess(stage.index('5. Freeze'), stage.index('6. Obtain independent')) + self.assertLess(stage.index('6. Obtain independent'), stage.index('7. Push only')) + self.assertIn('before its next substantive push', stage) + self.assertIn('reviewer must not be the candidate implementer', stage) + self.assertIn('read-only reviewer', stage) + self.assertNotIn('push the new PR head, and review', gates) + self.assertNotIn('No implementation or review subagent', gates) + def test_any_base_change_invalidates_readiness(self): + gates = (ROOT/'references/task-delivery-gates.md').read_text() + self.assertIn('Any target-base SHA change invalidates merge readiness', gates) + self.assertIn('even when candidate head/tree is unchanged', gates) + self.assertNotIn('base drift is harmless', gates) + self.assertNotIn('push/readback, and review', gates) + def test_kickoff_and_cross_repository_scope(self): + entry = (ROOT/'references/repository-entry-and-visibility.md').read_text() + self.assertIn('no file/tree changes', entry) + self.assertIn('does not authorize a substantive push', entry) + gates = (ROOT/'references/task-delivery-gates.md').read_text() + self.assertIn('documentation claims/handoffs and GitOps candidates', gates) + def test_no_unresolved_policy_marker(self): + for path in [ROOT/'SKILL.md', *ROOT.glob('references/*.md')]: + text = path.read_text() + self.assertNotIn('Bounded unresolved A02/A04', text) + self.assertNotIn('A02/A04 review-order/base-drift remain bounded unresolved', text) +if __name__ == '__main__': + unittest.main() diff --git a/tests/verify_full_program.py b/tests/verify_full_program.py index e206fa9..9203048 100644 --- a/tests/verify_full_program.py +++ b/tests/verify_full_program.py @@ -3,5 +3,5 @@ from pathlib import Path import subprocess,sys ROOT=Path(__file__).resolve().parents[1] if __name__=='__main__': - print('Source-contract checks only; A02/A04/A17 and deferred helpers are not completion claims.',flush=True) + print('Source-contract checks only; A17 and deferred helpers are not completion claims.',flush=True) subprocess.run([sys.executable,'-m','pytest','-q',str(Path(__file__).parent)],cwd=ROOT,check=True)