Compare commits

...
11 changed files with 300 additions and 168 deletions

No files matched your search

+75
View File
@@ -0,0 +1,75 @@
# Bounded Delivery simplification — 2026-10-23
## Authority and boundary
GUILD-IMP-20261023-delivery-existing-owners. Piotras (`501954115690168321`), verified Board member, approved “implement delivery skills proposal” in [Guild message 1563054836508008539](https://discord.com/channels/1518726359512387766/1542596418215092264/1563054836508008539), as supplied by the commissioning parent. This record does not claim an independent Discord re-audit.
Implements only the [published recommendation / smallest useful change](https://pages.apps.lego-cloud.eu/corp-v1-aerosim/corp-v1-aerosim-documentation/engineering/skills-delivery-channel#smallest-useful-change), read from `delivery-proposal-refresh-20261023/engineering/skills-delivery-channel.mdx`, with [2026-10-23 source/finding evidence](https://pages.apps.lego-cloud.eu/corp-v1-aerosim/corp-v1-aerosim-documentation/evidence/delivery-skills-refresh-2026-10-23.json). Baseline: `225ae3b068d97748af69597353479eb9c26579fc`, version 1.14.1; candidate 1.14.2.
Central package only; no helper, dependency change, file removal, migration, policy choice, dependency-repository edit or documentation-project edit. This manifest is an audit artifact, not an operational loaded reference. Parent owns publication, runtime refresh and separately authorized semantic project adoption.
## Responsibility manifest
Each row states the old rule/location, retained or single owner, and the new load point. Unlisted operational paragraphs remain unchanged.
| Rule / before | After: owner and decision point | Retained outcome / limit |
|---|---|---|
| Login origin and authorized purpose — entry + runtime repeated Board policy | Board **Corp v1 System SSO Credential Use**; entry says load before login, runtime follows that binding | Origin/purpose verification remains mandatory; unavailable owner stops login |
| Login secret names/runtime-only use — same two copies | Board; same pre-login load | Exact names retained in entry; no secret values introduced |
| No inspect/print/hash/serialize/paste/log/screenshot/persist or unsafe transport — same copies | Board full policy, not a selected subset | Board rules 2–3 and 7–8 retain all restrictions and session safety |
| Missing secret names only; never ask for values — same copies | Board rules 2–4, pre-login load | Injection only, no fallback secret |
| Login is not account/credential/MFA/permissions/billing/destructive authority | Board plus short Delivery boundary | No recovery or additional authority granted |
| Canonical lifecycle vocabulary repeated entry + status reference | Existing status reference owns full vocabulary; entry loads it before status action | Exact Task admission/claim, separate BLOCKED, TO_BE_RELEASED vs DONE retained in entry; full statuses unchanged in reference |
| Ways of Working five sections repeated entry + failure reference | Existing failure reference owns domain coverage; entry loads it before edits | All ten domain sections remain; verified practice only, not aspirations |
| Documentation platform mechanics | Global Docusaurus + project overlay; failure reference before authoring/validating | Source identity must match, not unrelated same-name VSSA installation; no domain/Diátaxis conflation |
| Canonical reusable definitions | Existing global Glossary; failure reference before defining terms | Final top-level Glossary and domain links, not copied explanations |
| Nested pnpm/Corepack bootstrap recipe — planning step 5 | Retained unchanged locally pending resolution of global Docusaurus runtime identity | Published owner has the procedure, but the installed name currently resolves to an unrelated source; no extraction to an unverified runtime owner |
| Current checkpoint/report claims — planning steps 8/12 | Integrity evidence-first sequence; explicit before-report load in planning/status | Fresh source/merge distinction, revalidation on drift/merge/close, final equality and duplicate suppression retained locally |
| Report shape and lifecycle meaning | Delivery status reference remains owner | Requested wave header, every Task, real owner, linked PR, gate codes, failure classification and no automatic DONE unchanged |
| pnpm/script implementation routing — runtime Coding | Existing pnpm and scripts owners with source-table link and action triggers | Approved Feature/Task, structure/namespace, traceability, no unrelated refactor/fabrication remain |
| Unit mechanics — runtime Unit testing | Explicit TTD action load added; existing generic owner already routed in entry | Existing bullets and Task stage left intact; no choice on discard/forward repair |
| Failure diagnosis/forward-repair procedure repeated entry + failure reference | Existing failure reference; entry loads at observed failure | Complete reference repair and escalation text unchanged, including no premature stop/help-policy rewrite |
| Build/CI failure classes repeated runtime + entry | Entry owns classes; runtime loads it and Integrity before reporting | Task CI job inventory and exact-head requirements untouched |
| Base-image policy repeated entry + runtime | Existing runtime reference owns complete contract; entry loads before create/publish/consume | Digest, version/platform/non-root/tools, candidate secret isolation, immutable publication/readback, fail-closed tests, lockfile parity, separate layers, forward repair/last-good all retained |
| Pitfalls duplicated entry + reference | Existing pitfalls reference, loaded on failed/resumed work and before status | Full reference unchanged; no safeguarding rule deleted |
## Verified existing sources
Source audit used the published capture, not version-label equality. No owner content was copied into a new helper or changed in this task.
- [Board login owner](https://gitea.lego-cloud.eu/skic-skills/channel-board-skic/src/commit/9170a6749f0adf5ec65fc99a645600cb471be9f1/SKILL.md): published/installed equal in evidence; loaded for comparison.
- [Integrity reporting owner](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-integrity/src/commit/b677c99f24cbe83734a9d6a495e388837fc88701/SKILL.md): published/installed equal; loaded for comparison.
- [Global Docusaurus](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus/src/commit/699cf6786e02bef74e84ec64b5a6233d4839ed47/SKILL.md): full captured `remote_text` read from `delivery-refresh-evidence/documentation-source.json`, including nested-pnpm remedy. Direct unauthenticated fetch returned 404; no false live-readback claim. Skill loader resolves a different VSSA owner; operational loads now explicitly require correct provenance.
- [Glossary](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-glossary/src/commit/24732bf6864a14f2d6aa6cccd7d9fc023438a42d/SKILL.md): retained existing route; no glossary procedure extracted.
- [TTD](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-method-ttd/src/commit/2155b0a250cea282bf6628231d8e3de286522a86/SKILL.md): retained strict existing route, no discard-policy rewrite.
- Ordinary Git, pnpm and scripts source links remain in the unchanged Development Skill Routing table. No Git procedure is extracted because exact Task/branch/readback requirements are tightly coupled to unresolved gates.
## Deferred findings and untouched boundaries
A01: no gate algorithm extraction; published `development-gates` lacks installed complete-job-inventory protections. A02/A04: substantive push/review order and harmless-base-drift wording untouched. A03: main-session review/worker restrictions unchanged. A05: strict TTD route retained, weaker wording/local-discard versus valid-work forward repair not reconciled. A06: whole-wave claim mapping not chosen. A08: no help-threshold/worker-role decision. A09: project CI source/runtime drift not changed. A10: no obsolete Helm fix needed; current static artifact versus functional UAT boundary retained. A11: exact branch/title/attempt/early-PR identity untouched. A12: no recovery skill or authorization change. A13: GitOps loadability/storage source issues not solved; all runtime/storage safeguards retained. A14: exact-context preflight remains byte-identical. A15: domain/platform distinction retained. A16: base-image safeguard remains local, not delegated to an incomplete external owner. A17: no scheduler authority conclusion or job mutation. A18: central eight-channel boundary unchanged; no project cleanup here.
The four complete files `task-delivery-gates.md`, `repository-entry-and-visibility.md`, `common-pitfalls.md`, `aerosim-lessons-review.md` are byte-identical. Runtime workspace, exact-context preflight/base-image/runtime-resource tail, failure-repair procedure and entry Authority/Escalation are hash-locked in tests. All 12 metadata dependencies and all 8 references remain.
## Validation and operational footprint
Test-first: initial unittest run had 12 tests, with expected failures for missing load points and size reduction (2 failures). Final suite includes unittest classes and the three existing function-style routing tests through `unittest.FunctionTestCase`; plain discovery alone would miss those three. No network required by tests.
Final local validation: `uv run --with pytest python -B -m pytest tests -q` — 16 tests passed. `git diff --check` passed. No remote CI workflow is configured. Publication/installation is separately verified by the parent.
## Measured operational footprint
Includes entry and every reference; excludes this audit manifest, tests, adoption record and caches. No removed procedure was moved into an operationally loaded new file.
| File | Before bytes | After bytes | Reduction |
|---|---:|---:|---:|
| `SKILL.md` | 27413 | 23017 | 4396 |
| `references/aerosim-lessons-review.md` | 3400 | 3400 | 0 |
| `references/common-pitfalls.md` | 2276 | 2276 | 0 |
| `references/failure-and-documentation.md` | 4428 | 5136 | -708 |
| `references/planning-artifact-reconciliation.md` | 6624 | 6621 | 3 |
| `references/repository-entry-and-visibility.md` | 6514 | 6514 | 0 |
| `references/runtime-and-ci.md` | 11078 | 10654 | 424 |
| `references/status-and-reporting.md` | 5135 | 5385 | -250 |
| `references/task-delivery-gates.md` | 17921 | 17921 | 0 |
| **Total** | **84789** | **80924** | **3865 (4.56%)** |
+40 -110
View File
@@ -1,16 +1,16 @@
---
name: corp-v1-channel-delivery
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.11.1
version: 1.14.2
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [corp-v1, discord, channel, delivery, coding, testing, ci]
related_skills: [corp-v1-main, home-v1-discord, documentation-docusaurus, corp-v1-glossary, development-durable-wave-execution, development-gates, development-integrity, development-method-ttd, development-branching-strategy, development-monorepo-pnpm, development-scripts, development-gitops-argo-cd-gondor-v1]
related_skills: [channel-board-skic, home-v1-discord, documentation-docusaurus, corp-v1-glossary, development-durable-wave-execution, development-gates, development-integrity, development-method-ttd, development-branching-strategy, development-monorepo-pnpm, development-scripts, development-gitops-argo-cd-gondor-v1]
---
# Corp v1 Delivery Channel
# SKIC Delivery Channel Reference
## Overview
@@ -20,55 +20,30 @@ Whenever a response mentions a Hermes Kanban board, initiative, card, or task, i
## Canonical Scope Status Vocabulary
Before reporting or changing any lifecycle status, read the project's current Ways of Working Scope page. Use only the canonical values defined there.
Before reporting or changing lifecycle status, load [status-and-reporting.md](references/status-and-reporting.md) and read the project's current Ways of Working Scope page. That contract retains the complete canonical vocabulary, requested wave format and gate codes; `development-integrity` owns checkpoint claims. Delivery claims only an exact `READY_FOR_DELIVERY` Task into `IN_PROGRESS`, without a second Focus admission. `BLOCKED` remains a separate flag; merge/green CI is not `DONE`, and releasable application work normally ends Delivery at `TO_BE_RELEASED`.
Ideas, Epics, and Features:
```text
IN_BACKLOG → IN_DESIGN → READY_FOR_DELIVERY → IN_DELIVERY → TO_BE_RELEASED → DONE
```
Tasks:
```text
IN_BACKLOG → READY_FOR_DELIVERY → IN_PROGRESS → TO_BE_RELEASED → DONE
```
`READY_FOR_DELIVERY` is the exact Task's Focus-admitted, pickup-ready state. It means Architecture, dependencies, implementation boundaries, verification steps, and Kanban selection are complete; implementation has not started. Delivery claims that Task by moving it directly to `IN_PROGRESS`. Never require or invent a second Focus-admission decision after `READY_FOR_DELIVERY`.
`CANCELLED` is an exceptional terminal status. `BLOCKED` is a separate flag with a reason and evidence; it never replaces the lifecycle status.
Never invent, abbreviate, or substitute lifecycle values such as `Ready`, `Active`, `Delivered`, `Complete`, `Awaiting CI`, or `Overrun`. Those phrases may describe activity only when clearly separated from the canonical status field. If the canonical status cannot be verified, report `status unverified` and inspect the source record rather than guessing.
A merge or successful CI does not automatically mean `DONE`. Releasable application Tasks normally move from `IN_PROGRESS` to `TO_BE_RELEASED`; `DONE` requires the applicable release or completion evidence. Status reports must show the exact canonical value even when a separate plain-language action is also included.
This skill owns delivery health for a Corp v1 project. It monitors the project's `general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, and `releases` channels and implements only tasks whose parent Feature has explicit human `Approved for Implementation` evidence and whose exact Task status is `READY_FOR_DELIVERY`. That status is the Focus-admitted pickup handoff; no separate post-status admission gate exists.
This skill owns delivery health for a Corp v1 project. It monitors the project's `general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, `uat`, and `releases` channels and implements only tasks whose parent Feature has explicit human `Approved for Implementation` evidence and whose exact Task status is `READY_FOR_DELIVERY`. That status is the Focus-admitted pickup handoff; no separate post-status admission gate exists.
Its scope includes coding, unit testing, builds, continuous integration, review readiness, delivery blockers, and maintenance of the project documentation's `Ways of Working` and `Engineering` areas.
Delivery owns application **unit testing only** plus static/build-time validation of the application artifacts it publishes: Dockerfiles, image/container contracts, publication records/workflows, and Helm chart linting/rendering/packaging. The project's standalone E2E repository under its UAT channel owns every functional non-unit suite and its fixtures, configuration, runner, and evidence: integration, browser, E2E, acceptance, security-boundary, performance, runtime-budget, smoke, regression, and deployed-environment testing. Delivery must not maintain or execute functional non-unit suites in the application repository. E2E must not install Helm or build/publish application images. It consumes UAT failures as defect evidence, fixes application code with unit-first TTD, and hands the corrected deployed tuple back to UAT.
Load the global `documentation-docusaurus` skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus` before changing documentation structure, navigation, Markdown/MDX, Docusaurus configuration, or builds.
Load the global `corp-v1-glossary` skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-glossary` whenever project documentation needs to define or explain a reusable term. Maintain one canonical definition in the project's final top-level **Glossary** area and link to it from the owning domain page; do not duplicate glossary-style explanations across channel documentation.
## Shared Corp v1 System Login
When an authorized task requires login to a Corp v1 system being built or operated, follow the shared policy in `corp-v1-main` and use only the Bitwarden-injected runtime secrets named:
```text
HL_V1_SSO_EMAIL
HL_V1_SSO_PASSWORD
```
Secret availability is capability, not authorization. Verify the destination origin and task purpose before login. Never print, inspect, log, hash, serialize, paste, screenshot, or persist either value; never place a value in a command line, URL, file, repository, prompt, Discord message, browser console, test fixture, CI output, or generated artifact. Never ask a human to paste a value into chat. If a variable is unavailable, report only its missing name and request Bitwarden/gateway injection. Login does not authorize account recovery, MFA or credential changes, permission changes, billing, spending, destructive operations, or access outside the approved project task.
Before login, load `channel-board-skic` from [its authoritative source](https://gitea.lego-cloud.eu/skic-skills/channel-board-skic) and follow **Corp v1 System SSO Credential Use** in full. It owns origin/purpose verification, runtime-only `HL_V1_SSO_EMAIL` / `HL_V1_SSO_PASSWORD` handling, non-disclosure, missing-secret injection and session safety. If that policy cannot be loaded, stop before login. Secret availability is not authorization; Delivery grants no account recovery, credential/MFA, permission, billing, destructive-operation or unrelated-access authority.
## When to Use
Use this skill when:
- operating in `corp-v1-<code>-delivery`;
- operating in `<code>-delivery`;
- running its recurring synchronization job;
- implementing or reviewing project code;
- adding or repairing unit tests;
- adding or repairing unit tests only; non-unit coverage is routed to the project's UAT channel and standalone E2E repository;
- diagnosing build or CI failures;
- checking implementation against requirements and ADRs;
- maintaining delivery-oriented documentation.
@@ -114,20 +89,21 @@ The Corp v1 overlay is narrower: every Task requires a dedicated visible branch
## Proactive Iteration Requirement
Every delivery iteration must complete at least one useful, safe activity for an implementation-approved Feature or delivery-health need: implement an unblocked task, add tests, diagnose/fix CI, improve build tooling, update real Ways of Working/Engineering guidance, verify dependency readiness, or document a concrete blocker with evidence. Never create filler changes. Select work only from exact Tasks in `READY_FOR_DELIVERY`; claiming one moves it to `IN_PROGRESS`. Keep architecture's approved task/dependency plan and project documentation current.
Every delivery iteration must complete at least one useful, safe activity for an implementation-approved Feature or delivery-health need: implement an unblocked task, add unit tests, diagnose/fix CI, improve build tooling, update real Ways of Working/Engineering guidance, verify dependency readiness, or document a concrete blocker with evidence. Never create filler changes. Select work only from exact Tasks in `READY_FOR_DELIVERY`; claiming one moves it to `IN_PROGRESS`. Keep architecture's approved task/dependency plan and project documentation current.
## Approved Information Boundary
Inspect only the project's seven channels:
Inspect only the project's eight channels:
```text
corp-v1-<code>-general
corp-v1-<code>-scope
corp-v1-<code>-architecture
corp-v1-<code>-ui-ux
corp-v1-<code>-kanban
corp-v1-<code>-delivery
corp-v1-<code>-releases
<code>-general
<code>-scope
<code>-architecture
<code>-ui-ux
<code>-kanban
<code>-delivery
<code>-uat
<code>-releases
```
Use enough delivery history to avoid duplicate work and only relevant new activity from the other channels. Never inspect another project.
@@ -140,26 +116,17 @@ Load the project-adopted engineering skill for the repository stack before editi
### Unit testing
Load `development-method-ttd` for every behavior change, defect fix, or refactor. It owns RED–GREEN–REFACTOR mechanics, focused-test progression, and test-design anti-patterns. Delivery only requires that the resulting tests map to approved acceptance evidence and that real commands/results are retained.
Load `development-method-ttd` for every behavior change, defect fix, or refactor. It owns RED–GREEN–REFACTOR mechanics, focused-test progression, and test-design anti-patterns. Delivery requires unit tests to map to approved acceptance evidence and retains their real commands/results. UAT owns every functional non-unit test required to prove that evidence outside the unit boundary; Delivery retains build-time image/container/Helm artifact validation.
### Build and continuous integration
Load `development-gates` before candidate review, remote CI, merge, or integration validation, and load `development-integrity` before reporting their status. These skills own exact-head identity, attempt integrity, base-drift handling, candidate-versus-integration separation, and honest checkpoint wording.
Delivery still monitors repository-specific compile/type, unit/integration, lint/format, dependency, packaging, container, chart, workflow, and artifact failures. A green local build is never remote CI evidence.
Delivery still monitors repository-specific compile/type, unit-test, lint/format, dependency, packaging, workflow, image/container contract, Helm chart, and artifact-publication failures. Functional non-unit browser, integration, performance, security-boundary, and acceptance failures arrive as UAT evidence and are routed back for application remediation. A green local build is never remote CI evidence.
### Per-project reusable CI base images
Each Corp v1 project should own `corp-v1-<code>/corp-v1-<code>-base-images` when stable runtimes or operating-system tools would otherwise be downloaded repeatedly in application CI.
- Keep one folder per image, with its Dockerfile, machine-readable version/platform metadata, usage documentation, build helper, and smoke contract.
- Pin the upstream base by digest and assert exact runtime/tool versions, architecture, numeric non-root identity, writable workspace, CA trust, Git, shell, and other required tools.
- Build and smoke-test without registry credentials on pull requests. Publish only from the trusted integration branch using a narrowly scoped Harbor robot secret.
- Publish immutable full-source-SHA tags, read back the Harbor artifact digest, and consume the image from project workflows by digest—not `latest`, a mutable version tag, or an unverified local name.
- Extend fail-closed tests to reject broad publication triggers, mutable tags, secret access from candidate/PR paths, shell interpolation, wrong digests, and reintroduced runtime setup actions.
- Prefer the verified job image over repeated runtime or package-manager setup actions. Keep lockfile-frozen application dependency installation in the application repository; do not bake project dependencies into a generic base image.
- Treat the first real Gitea build, runtime smoke test, Harbor publication, digest readback, and a consumer workflow at the exact candidate SHA as separate acceptance layers.
- Repair image or publication failures forward only. Preserve the last known-good digest for consumers until the replacement image and consuming workflow pass exact-head CI.
Each project should own `corp-v1-<code>/corp-v1-<code>-base-images` when stable runtimes or OS tools would otherwise be downloaded repeatedly in CI. Before creating, publishing or consuming an image, load [the complete Delivery-owned base-image contract](references/runtime-and-ci.md#per-project-reusable-ci-base-images). It retains digest pinning, credential-free candidate validation, trusted integration-branch publication, immutable tags/digest readback, fail-closed tests and forward repair with the last known-good digest. Runtime smoke remains UAT-owned; no external CI owner is assumed to replace this contract.
### Runtime-resource placement
@@ -173,49 +140,11 @@ CI jobs and developer workstations must not provision databases, queues, object
## Failure-Repair Workflow
When a build or CI failure is observed:
1. verify repository, branch, head SHA, failed job, and exact logs;
2. reproduce locally when feasible;
3. determine root cause before editing;
4. compare the intended fix against approved FR/NFRs, ADRs, architecture documentation, and project conventions;
5. implement the smallest safe fix;
6. add/update tests where behavior changed;
7. run local validation;
8. commit and push through the approved branch workflow;
9. inspect CI for the exact new head SHA;
10. report evidence and remaining risk.
The skill may attempt a safe fix when the failure and expected behavior are clear. If evidence is insufficient or requirements/architecture conflict, stop and raise the issue in the relevant channel:
- requirement/product ambiguity → `general` and/or `architecture` as appropriate;
- architecture contradiction → `architecture`;
- release policy/readiness ambiguity → `releases`;
- implementation-only blocker → `delivery`.
Never guess the team's intended direction.
Load [failure-and-documentation.md](references/failure-and-documentation.md#failure-repair-workflow) when a build or CI failure is observed. It owns diagnosis, safe forward repair, affected validation, exact-head CI and escalation destinations. Keep repairable failures in the same Task/gate; pause only for the documented external, authority, decision or safety blocker. Never guess requirements or Architecture, weaken a gate or treat a blocker as passing.
## Documentation Ownership
Maintain two documentation areas.
### Ways of Working — five sections
1. **Delivery workflow** — intake, prioritization, implementation states, and definition of done.
2. **Branching and reviews** — branch conventions, pull requests, approvals, and merge expectations.
3. **Planning and ownership** — backlog, sequencing, owners, dependencies, blockers, and escalation.
4. **Quality practices** — review standards, test strategy, defect handling, and evidence expectations.
5. **Collaboration and decisions** — channel routing, handoffs, decision references, and communication norms.
### Engineering — five sections
1. **Repository and workspace** — monorepo/application/package structure and local prerequisites.
2. **Development and testing** — commands, unit/integration testing, fixtures, and debugging.
3. **Build and continuous integration** — pipelines, checks, artifacts, runners, and failure diagnosis.
4. **Packaging and deployment preparation** — containers, Helm/GitOps interfaces, configuration, and release inputs.
5. **Operations and troubleshooting** — observability, known failure modes, recovery checks, and evidence collection.
Update these pages from verified project practice. Do not document a planned process as already operational.
Delivery owns verified Ways of Working and Engineering content, not documentation-platform mechanics. Before changing either area, load [the domain coverage contract](references/failure-and-documentation.md#documentation-ownership), the linked global `documentation-docusaurus` source and the project-adopted documentation overlay. Load `corp-v1-glossary` before defining reusable terms. Keep planned practice distinct from operational evidence.
## UI/UX Coordination
@@ -237,9 +166,9 @@ For frontend-affecting work, Delivery requires the approved UI/UX design package
May autonomously:
- run tests/builds/read-only checks;
- run unit tests, builds, Delivery artifact validations, and read-only checks; functional non-unit suites run through UAT;
- repair clear CI/build defects within authorized scope;
- add tests for an approved behavior;
- add unit tests for an approved behavior and request non-unit coverage from UAT;
- maintain accurate delivery documentation;
- prepare branches/commits/PRs where the project workflow authorizes it.
@@ -258,6 +187,8 @@ Include repository, branch, commit SHA, changed paths, commands, local results,
## Mined Project-Adoption Improvements
Review provenance and exclusions: [AeroSim lessons review](references/aerosim-lessons-review.md).
## Dedicated Project Channel Workspace
Every project adoption must bind this channel to a dedicated local workspace under the active working root. Keep clones, worktrees, plans, reports, screenshots, generated artifacts, retained logs, and channel inputs inside that channel root. Use run-unique or task-specific children under `workspace/`; keep durable project truth in approved repositories. A local folder boundary organizes execution only—it neither broadens authority nor replaces remote evidence. Delivery adoptions should additionally use a channel-level `cache/` for reusable pinned toolchains and dependencies, while keeping Task evidence isolated by Task.
@@ -284,17 +215,7 @@ When selectable controls are needed, explain every complete option and its trade
## Common Pitfalls
1. Patching symptoms before understanding root cause.
2. Changing requirements or architecture implicitly through code.
3. Claiming CI success from a local build.
4. Editing without loading applicable project engineering skills.
5. Skipping tests for behavioral fixes.
6. Updating documentation with aspirational rather than actual practice.
7. Repeatedly posting unchanged failure summaries.
8. Inspecting another project.
9. Starting implementation because requirements exist but human implementation approval is absent.
10. Ignoring architecture task dependencies, Kanban Focus admission, or target-version allocation.
11. Posting passive status when safe implementation, testing, diagnosis, or documentation work is available.
Load [common-pitfalls.md](references/common-pitfalls.md) on failed gates, resumed work and before blocker/CI/merge/completion reports. It retains the complete Delivery traps, including approval/admission, same-project scope, useful safe activity, real evidence and same-gate forward repair. These reminders do not replace the ordered Task gates.
## Verification Checklist
@@ -309,3 +230,12 @@ When selectable controls are needed, explain every complete option and its trade
- [ ] Contradictions were escalated, not guessed through.
- [ ] Ways of Working and Engineering documentation remains accurate.
- [ ] Completed work includes exact evidence.
## Canonical naming and compatibility
- Canonical installed and repository name: `channel-delivery-skic`.
- Source: `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/channel-delivery-skic`.
- Previous name: `corp-v1-channel-delivery`; retained locally only as a compatibility alias. New guidance and presentations use the canonical name.
- Naming-only migration authorized by RootAtSkic in [presentation message 1562523679223578705](https://discord.com/channels/1518726359512387766/1543922127898415154/1562523679223578705). Repository ID, history, support files, project authority and organization ownership are preserved.
- This is a reusable central reference, not a new shared Discord channel. Project adoptions use `channel-delivery-skic-<code>` and remain separately owned.
- Current project channel: `<code>-delivery` inside `skic-<code>`.
+30
View File
@@ -0,0 +1,30 @@
# AeroSim lessons review — Delivery
## Immutable sources
AeroSim Delivery source SHA: `0c0e68bde3189fd96415af6035200cf7fcb9c877`. Central baseline: `0bf71b905f0160631460807b371732b1afc5b0cb`.
- [SKILL.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/channel-delivery-skic-aerosim/src/commit/0c0e68bde3189fd96415af6035200cf7fcb9c877/SKILL.md)
- [references/task-delivery-gates.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/channel-delivery-skic-aerosim/src/commit/0c0e68bde3189fd96415af6035200cf7fcb9c877/references/task-delivery-gates.md)
- [references/runtime-and-ci.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/channel-delivery-skic-aerosim/src/commit/0c0e68bde3189fd96415af6035200cf7fcb9c877/references/runtime-and-ci.md)
- [references/single-subagent-task-delivery.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/channel-delivery-skic-aerosim/src/commit/0c0e68bde3189fd96415af6035200cf7fcb9c877/references/single-subagent-task-delivery.md)
Read the full source skill and all nine references against the central skill and its seven references. Relevant sections: **Overview**, **End-to-End Task Delivery Gates**, **Hourly Worker Reconciliation**, gate **Stage 5**, **Immutable application images and Helm charts**, and **Main-Session Verification**.
## Promoted lessons
- Bind the post-integration UAT handoff to an actual deployed tuple, not a PR-head CI result or image push. Put the contract in Stage 5, without duplicating generic exact-head algorithms already owned by `development-gates`.
- Distinguish root Git, child chart/source, pod image, and endpoint identity; operational health is not user-visible acceptance.
- Retain destination delivery proof and prevent a Releases notification from bypassing UAT or authorizing release.
- Include UAT in the information boundary; replace stale seven-channel wording rather than retaining two conflicting lists.
## Runtime drift reviewed
Installed Delivery `SKILL.md` SHA-256: `46e5304d701d180496688d9a16bb1413fb96c7a888aaf83570da62fc8a7447ff`; installed `references/task-delivery-gates.md` SHA-256: `fcb02322d5f440f3e59a24fa03c4ae74370e469aa6a35a42d94db8818448cca0`. These are supplementary local snapshots, not content attributed to the pinned Git commit. Their **End-to-End Task Delivery Gates / Stage 5** strengthen runtime readback and non-runtime `not_applicable` reasons. Generalized only the ready-for-UAT evidence requirement; the universal AeroSim development-deployment mandate and its standing authority remain project-local. Full runtime reference diffs were inspected, including stale test-ownership wording.
## Exclusions
No project rollout, runtime overwrite, owner reassignment, branch naming change, Jira mandate, standing merge/deploy delegation, account recovery, board/channel IDs, endpoint, scheduler cadence, or deployment configuration is promoted. Central authority and project overlays remain unchanged. The newer central functional-non-unit versus build-time artifact-validation split is retained; runtime references that send Helm artifact validation to UAT are stale and are not imported.
## Verification
Run `python3 -B -m unittest discover -s tests -v` from this repository, plus `git diff --check`. Tests validate the published documentation contract and links offline; they do not prove a deployment or live acceptance run.
+4 -2
View File
@@ -29,7 +29,9 @@ Never guess the team's intended direction, weaken a gate, or treat a blocker as
## Documentation Ownership
Maintain two documentation areas.
Before authoring or validating documentation, load `documentation-docusaurus` from [the global source](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus) and the project-adopted documentation overlay for Diátaxis, Markdown/MDX, navigation and build mechanics. Verify source identity: an unrelated same-name installation is not this global owner. Before defining reusable terms, load `corp-v1-glossary` from [its source](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-glossary); it owns canonical definitions in the final top-level Glossary and domain-page links. If the required owner cannot be loaded, stop the affected documentation action.
Delivery retains these domain outcomes in two areas:
### Ways of Working — five sections
@@ -42,7 +44,7 @@ Maintain two documentation areas.
### Engineering — five sections
1. **Repository and workspace** — monorepo/application/package structure and local prerequisites.
2. **Development and testing** — commands, unit/integration testing, fixtures, and debugging.
2. **Development and unit testing** — commands, unit-test fixtures, debugging, Delivery artifact validation, and the handoff to UAT for every functional non-unit suite.
3. **Build and continuous integration** — pipelines, checks, artifacts, runners, and failure diagnosis.
4. **Packaging and deployment preparation** — containers, Helm/GitOps interfaces, configuration, and release inputs.
5. **Operations and troubleshooting** — observability, known failure modes, recovery checks, and evidence collection.
@@ -11,17 +11,14 @@ Use this procedure when Scope, Architecture, Kanban, Ways of Working, Engineerin
5. Validate the exact head in that clean or detached worktree using the repository's own validation command. Explicitly execute package-manager commands with the worktree as the process working directory (or begin the shell block with `cd "$worktree"`); setting up the worktree in an earlier command does not make it the current directory for a later process. Install dependencies with the repository's declared frozen-lockfile command when the clean worktree has no installed dependencies. If the package manager shim is unavailable, use the repository-declared package-manager launcher rather than changing project files. Before running a composite package script, verify that child scripts can resolve the package-manager executable too: `corepack pnpm validate` can start successfully yet fail when `validate` invokes nested `pnpm ...` commands. In that case, create a writable temporary shim directory with `corepack enable --install-directory <cache>/pnpm-bin`, prepend it to `PATH`, and run the declared command (for example, `PATH=<cache>/pnpm-bin:$PATH pnpm validate`). Keep the shim and dependency cache outside committed content, run `git diff --check`, and confirm the worktree remains clean afterward.
6. Query Gitea Actions tasks and match the full exact head SHA. Require each matching task to report `success`; do not transfer a PR-head result to the eventual merge head. Keep Gitea identifiers distinct: the Actions task API `id`, its `run_number`, and any UI run URL/ID are separate fields and may not have the same value. Report the exact field actually returned by the verified endpoint (for example, `task id 684, run_number 66`) rather than relabeling a channel-reported UI run ID as a task ID.
7. Read back the changed planning artifacts through the authenticated raw-file API at the exact PR source ref and verify their **semantics**, not merely keyword presence. Headings and lifecycle guidance naturally contain terms such as `READY_FOR_DELIVERY`, so keyword presence alone does not prove a Task is pickup-ready. For Kanban, assert the exact Task row and status, the evidence timestamp, and any newly cited head/task pairs; also assert superseded pairs are absent when the change claims reconciliation. Parse each lifecycle section independently and verify the Task's actual row rather than using loose whole-file heuristics such as a state-name count. If an automated semantic probe disagrees with the rendered Markdown, read the relevant numbered lines and correct the probe before reporting.
8. Immediately before reporting, re-fetch the PR, its remote source ref, the default branch, and exact-SHA tasks. Scheduled writers or human reviewers can change repository state during local validation.
- If the open PR source head advanced, treat the completed source-head check as stale and validate the new source head.
- If the PR merged or closed during validation, stop describing it as open. Fetch the freshly resolved merge/default-branch SHA, create or switch to a clean detached worktree at that exact commit, rerun the repository's declared validation and semantic probes there, and require a successful Actions task whose full `head_sha` equals the merge commit. PR-head CI must not be transferred to the merge head.
- Re-fetch once more after merge-head validation and assert the PR state, default-branch SHA, local validated SHA, and latest exact-SHA terminal task still agree. If another Delivery report already covers that identical evidence, remain silent.
8. Apply `development-integrity`'s evidence-first checkpoint sequence immediately before reporting: refresh PR state, source/default refs and exact-SHA tasks. If the source head advanced, revalidate it. If the PR merged or closed during validation, stop calling it open; validate the fresh merge/default SHA in a clean detached worktree, including semantic probes and a successful Actions task with matching full `head_sha`. PR-head CI is not merge-head CI. Refresh again after validation and require PR state, default head, local validated head and latest exact-SHA terminal task to agree. Stay silent if Delivery already reported identical evidence.
9. Reconcile Kanban separately:
- Proposed Epics/Features may appear in an ideation view.
- An exact Task is Focus-admitted and pickup-ready when its status is `READY_FOR_DELIVERY`; there is no second Focus-admission gate.
- A newly added Kanban page or merged board does not itself move an exact Task to `READY_FOR_DELIVERY`.
10. Re-evaluate every implementation gate from the source files and approvals: Approved for Implementation, FR/NFR and ADR context, task/dependency plan, target version, acceptance evidence, and exact Task `READY_FOR_DELIVERY` state.
11. If the gate remains closed, do not create application changes. A useful delivery activity can be exact-head build/CI verification, durable documentation reconciliation, or a newly evidenced blocker report.
12. Report only deltas not already covered by the latest delivery message. Include repository, branch, full SHA, local commands/results, exact-SHA task IDs, and the specific missing gate.
12. Before reporting, load `development-integrity` from [its source](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-integrity) for evidence-first checkpoint claims, then [status-and-reporting.md](status-and-reporting.md) for Delivery formatting. Retain repository, branch, full SHA, commands/results and exact-SHA task IDs as audit evidence; report only new deltas and the specific missing gate. This reporting load does not change review ownership, gate order, repair/help or scheduler authority.
## Evidence interpretation
@@ -2,7 +2,7 @@
Load this reference before claiming a Task, creating its application branch, opening its PR, or resuming its worktree.
All local repository entry happens inside `corp-v1-<code>-delivery/workspace/<TASK_ID>/`. During preparation, create only the required repository clones: `application/` and `documentation/`. Optional Task-local `review/`, `cache/`, `tmp/`, `logs/`, or `artifacts/` folders may be added later only when a concrete Task activity needs them. Reusable installed toolchains and technical dependencies are the sole exception: place them in `corp-v1-<code>-delivery/cache/`, never in a Task workspace. A repository branch, clone, Task evidence file, or other Task-local support folder outside the selected Task directory does not satisfy this gate.
All local repository entry happens inside `<code>-delivery/workspace/<TASK_ID>/`. During preparation, create only the required repository clones: `application/` and `documentation/`. Optional Task-local `review/`, `cache/`, `tmp/`, `logs/`, or `artifacts/` folders may be added later only when a concrete Task activity needs them. Reusable installed toolchains and technical dependencies are the sole exception: place them in `<code>-delivery/cache/`, never in a Task workspace. A repository branch, clone, Task evidence file, or other Task-local support folder outside the selected Task directory does not satisfy this gate.
## Implementation Entry Gate
+12 -33
View File
@@ -4,10 +4,10 @@ Load this reference before login, toolchain execution, CI work, image publicatio
## Channel-owned workspace
Resolve the channel root as `corp-v1-<code>-delivery/` under the active user's working root:
Resolve the channel root as `<code>-delivery/` under the active user's working root:
```text
corp-v1-<code>-delivery/
<code>-delivery/
├── cache/ # reusable channel toolchains and technical dependencies
├── uploads/
└── workspace/
@@ -21,7 +21,7 @@ corp-v1-<code>-delivery/
└── artifacts/ # optional: only when outputs must be retained
```
- `cache/` contains reusable technical dependencies installed by Delivery, including pinned Node/pnpm toolchains, Playwright browsers, Nginx binaries, and package-manager download caches. Reuse verified entries across Tasks instead of reinstalling them. Version or digest cache paths when compatibility matters, verify the resolved executable and version in every execution context, and never store credentials, Task evidence, repository content, or mutable application state there.
- `cache/` contains reusable technical dependencies installed by Delivery, including pinned Node/pnpm toolchains, Nginx binaries, and package-manager download caches. Browser/Playwright dependencies for non-unit suites belong to the UAT workspace and E2E repository. Reuse verified entries across Tasks instead of reinstalling them. Version or digest cache paths when compatibility matters, verify the resolved executable and version in every execution context, and never store credentials, Task evidence, repository content, or mutable application state there.
- `uploads/` contains files supplied through this channel. It is not a repository checkout or build directory.
- Create one `workspace/<TASK_ID>/` directory per Task.
- During `GATE_001_PREP`, create only the required repository clones: `application/` and `documentation/`. If a Task genuinely needs another repository, clone it as another clearly named child.
@@ -34,29 +34,18 @@ corp-v1-<code>-delivery/
## Shared Corp v1 System Login
When an authorized task requires login to a Corp v1 system being built or operated, follow the shared policy in `corp-v1-main` and use only the Bitwarden-injected runtime secrets named:
```text
HL_V1_SSO_EMAIL
HL_V1_SSO_PASSWORD
```
Secret availability is capability, not authorization. Verify the destination origin and task purpose before login. Never print, inspect, log, hash, serialize, paste, screenshot, or persist either value; never place a value in a command line, URL, file, repository, prompt, Discord message, browser console, test fixture, CI output, or generated artifact. Never ask a human to paste a value into chat. If a variable is unavailable, report only its missing name and request Bitwarden/gateway injection. Login does not authorize account recovery, MFA or credential changes, permission changes, billing, spending, destructive operations, or access outside the approved project task.
Before login, load `channel-board-skic` and follow its complete **Corp v1 System SSO Credential Use** policy through [Delivery's source/authority binding](../SKILL.md#shared-corp-v1-system-login). Stop if unavailable; secret access grants no additional authority.
## Delivery Responsibilities
### Coding
- implement only human-approved Features and their authorized tasks;
- load applicable project engineering skills before changing code;
- preserve project structure, conventions, and environment namespace;
- keep changes small, reviewable, and traceable to requirements/issues;
- avoid unrelated refactors during failure repair;
- never fabricate command, test, CI, or deployment results.
Load `development-monorepo-pnpm` for pnpm/TypeScript implementation and `development-scripts` for Taskfile, shell, environment and Devbox work, using their [source links and project-overlay precedence](../SKILL.md#development-skill-routing). Preserve project structure/namespace; implement only approved Features and authorized Tasks with small, traceable changes, no unrelated refactors and no fabricated results.
### Unit testing
Load `development-method-ttd` before behavior changes, fixes or refactors using its [source link](../SKILL.md#development-skill-routing). Its reusable mechanics do not replace the Task gate's unit/UAT boundary or resolve local-discard versus forward-repair policy.
- add or update tests with behavioral changes;
- reproduce defects before fixing when practical;
- cover normal, edge, and failure cases proportional to risk;
@@ -65,17 +54,7 @@ Secret availability is capability, not authorization. Verify the destination ori
### Build and continuous integration
Monitor local builds and Gitea Actions for:
- compile/type failures;
- unit/integration test failures;
- lint/format failures;
- dependency, packaging, container, or chart failures;
- workflow/configuration defects;
- missing or stale artifacts;
- branch/head-SHA mismatch.
A green local build is not proof that CI or delivery succeeded. Verify the actual remote branch and matching CI task/run.
Use [Delivery's build/CI responsibilities](../SKILL.md#build-and-continuous-integration) for the required failure classes and UAT remediation boundary. Before reporting CI, load `development-integrity` through [status-and-reporting.md](status-and-reporting.md); a local build is not remote CI evidence. Task gate job inventory and exact-head checks still apply.
### Execution-context toolchain preflight
@@ -93,13 +72,13 @@ Never assume a background process inherits `PATH`, shell activation, Devbox stat
the adopted project owns `corp-v1-<code>/corp-v1-<code>-base-images` as the reusable CI-image repository. Use it when stable runtimes or operating-system tools would otherwise be downloaded repeatedly in application jobs.
- Keep one folder per image, with its Dockerfile, machine-readable version/platform metadata, usage documentation, build helper, and smoke contract.
- Keep one folder per image, with its Dockerfile, machine-readable version/platform metadata, usage documentation, build helper, and static publication contract. Runtime smoke belongs to UAT.
- Pin the upstream base by digest and assert exact runtime/tool versions, architecture, numeric non-root identity, writable workspace, CA trust, Git, shell, and other required tools.
- Build and smoke-test without registry credentials on pull requests. Publish only from the trusted `test` branch using a narrowly scoped Harbor robot secret.
- Build and perform static/unit validation without registry credentials on pull requests. Publish only from the trusted `test` branch using a narrowly scoped Harbor robot secret; UAT validates the published digest at runtime.
- Publish immutable full-source-SHA tags, read back the Harbor artifact digest, and consume the image from the adopted project workflows by digest—not `latest`, a mutable version tag, or an unverified local name.
- Extend fail-closed tests to reject broad publication triggers, mutable tags, secret access from PR paths, shell interpolation, wrong digests, and reintroduced runtime setup actions.
- Prefer the verified job image over repeated `actions/setup-node` or package-manager bootstrap steps. Keep `pnpm install --frozen-lockfile --ignore-scripts` in the application repository for lockfile parity; do not bake project dependencies into a generic base image.
- Treat the first real Gitea build, runtime smoke test, Harbor publication, digest readback, and a consumer workflow at the exact PR-head SHA as separate acceptance layers.
- Treat the first real Gitea build, Harbor publication, digest readback, and consumer workflow at the exact PR-head SHA as separate Delivery layers. Runtime smoke is a separate UAT layer.
- Repair image or publication failures forward only. Preserve the last known-good digest for consumers until the replacement image and consuming workflow pass exact-head CI.
### Gondor runtime-resource placement
@@ -107,7 +86,7 @@ the adopted project owns `corp-v1-<code>/corp-v1-<code>-base-images` as the reus
The adopted project CI jobs and developer workstations must not provision PostgreSQL, queues, object stores, caches, brokers, or other application runtime services. Load `development-gitops-argo-cd-gondor-v1` before defining or changing Gondor desired state. Render the committed project template separately into one repository per environment; Delivery may update only the repository assigned to its non-production environment, while production remains outside Delivery authority unless an explicit project overlay says otherwise.
- Keep every non-production the adopted project environment—including development, integration, test, staging, and preview—and all of its resources isolated from production and from other non-production environments. Destructive or concurrent validation requires a per-run database/schema/role or explicit serialization; it must not reset shared data.
- CI may orchestrate exact-head validation, but it must not start application runtime-resource service containers or receive application-resource credentials. Harmless process-local test doubles and build tools are not runtime resources. Run resource-dependent tests through a restricted trigger as private in-cluster Jobs/Workflows; do not expose PostgreSQL or another internal resource through Ingress, NodePort, LoadBalancer, or a runner-accessible public endpoint.
- Delivery CI may orchestrate exact-head unit/build validation, but it must not start application runtime-resource service containers or receive application-resource credentials. Harmless process-local unit-test doubles and build tools are not runtime resources. UAT owns resource-dependent tests and their restricted execution; Delivery only provisions an approved development dependency and hands its exact identity to UAT. Do not expose PostgreSQL or another internal resource through Ingress, NodePort, LoadBalancer, or a runner-accessible public endpoint.
- Persistent Gondor storage must follow `home-v1--truenas`. For durable the adopted project data, create a purpose-specific TrueNAS dataset and NFS share restricted to Gondor node networks, then bind a static PV/PVC with `persistentVolumeReclaimPolicy: Retain` and `storageClassName: ""`. Do not use the default dynamic `truenas-csi` StorageClass for durable data because its `Delete` reclaim policy can remove the backing dataset with the PVC.
- Use only External Secrets backed by the existing Bitwarden `ClusterSecretStore`; never commit connection strings or credentials.
- Provision and verify required Gondor resources before deploying dependent the adopted project code. Resource-independent implementation may proceed, but deployment remains blocked until the dependency is healthy and consumed by the application.
+1 -1
View File
@@ -1,6 +1,6 @@
# the adopted project Status and Reporting
Load this reference when reading Task states or reporting Task, wave, CI, blocker, or completion status.
Before reporting, load [development-integrity](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-integrity) for checkpoint claims and implementation-versus-closure evidence. Delivery retains the vocabulary/format below and its existing review, gate, repair/help and scheduler boundaries; this load resolves none of those policy questions.
## Scope Status Vocabulary
+24 -16
View File
@@ -8,13 +8,13 @@ These gates are mandatory and ordered. Each `GATE_###_NAME` code is the stable i
- 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/corp-v1-channel-delivery-<code>`.
- this Delivery skill: `corp-v1-<code>-skills-code-agent/channel-delivery-skic-<code>`.
All local work and evidence for a Task is isolated under `corp-v1-<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 `corp-v1-<code>-delivery/cache/` so later Tasks can reuse verified versions. Channel-provided input files belong in `corp-v1-<code>-delivery/uploads/`.
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/`.
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.
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 seven 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.
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
@@ -24,13 +24,13 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
### 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 `corp-v1-<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:** 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.
**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 seven 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:** 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.
**Exit gate:** The Task directory exists under `corp-v1-<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:** 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.
### Stage 2 — `GATE_002_TASK_PLAN` — Plan the Task
@@ -44,16 +44,16 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
### Stage 3 — `GATE_003_TASK_IMPLEMENTATION` — Implement and Review the Task
**Repository and branch:** Use `corp-v1-<code>-delivery/workspace/<TASK_ID>/application/` on the existing application Task branch and PR. All source, test, configuration, application-documentation changes, builds, and tests stay in that clone and branch. If a separate review checkout or output is needed, create and use `review/` under the same Task directory.
**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.
**Required work:**
1. Resolve the real working directory and verify it is inside `corp-v1-<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. Tests may use only disposable test services, never persistent Gondor data.
2. For a defect, write or identify an exact named test and show that it fails for the expected product reason before repair. For new behavior, add a failing behavioral test first when practical. Syntax, tooling, environment, or credentials errors do not count as product evidence.
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.
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 tests, full tests, integration and security-boundary tests, lint, format checks, typecheck or compile, production build, production dependency audit, static checks, generated-artifact checks, `git diff --check`, and repository-state checks.
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.
@@ -67,7 +67,7 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
**Required work:**
1. Verify that every required CI job—such as tests, lint, typecheck, build, security checks, and image 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. 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.
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.
@@ -78,16 +78,24 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
**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 if the Task explicitly includes an approved deployment.
**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. Verify every required integration job, application test, 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.
2. Add the hash-linked `IN_PROGRESS` to `TO_BE_RELEASED` event with the merged application PR, integration revision, successful integration CI, publication evidence when required, and acceptance evidence.
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.
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 integration 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`. Only then may Delivery call the Task delivered. Release execution and the later `DONE` transition belong to `corp-v1-channel-releases-<code>`, not this Delivery process.
**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
@@ -97,4 +105,4 @@ Hermes may pause the repair loop only when progress requires an unavailable exte
**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 `corp-v1-channel-releases-<code>`.
**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>`.
+57
View File
@@ -0,0 +1,57 @@
"""Offline regression tests for the channel's published prose contract."""
from pathlib import Path
import re
import unittest
ROOT = Path(__file__).resolve().parents[1]
class LessonsContract(unittest.TestCase):
def test_review_provenance_and_link(self):
review = ROOT / "references/aerosim-lessons-review.md"
self.assertTrue(review.is_file())
text = review.read_text()
self.assertRegex(text, r"/src/commit/[0-9a-f]{40}/")
self.assertIn("## Exclusions", text)
self.assertIn("aerosim-lessons-review.md", (ROOT / "SKILL.md").read_text())
def test_local_markdown_links_resolve(self):
for path in [ROOT / "SKILL.md", *ROOT.glob("references/*.md")]:
for target in re.findall(r"\]\(([^)]+)\)", path.read_text()):
if "://" not in target and not target.startswith(("#", "<")):
self.assertTrue((path.parent / target.split("#")[0]).is_file(), (path, target))
def test_no_project_authority_transplant(self):
for path in [ROOT / "SKILL.md", *ROOT.glob("references/*.md")]:
if path.name == "aerosim-lessons-review.md":
continue
text = path.read_text()
for forbidden in ("jarvis-at-skic", "aerosim-dev.apps", "AEROSIM_STANDING", "1537388451501056081"):
self.assertNotIn(forbidden, text)
def test_contract_0(self):
text = (ROOT / 'references/task-delivery-gates.md').read_text()
self.assertIn('#### Deployment and handoff evidence', text)
self.assertIn('pod image IDs', text)
self.assertIn('destination channel/message ID', text)
self.assertIn('not_applicable', text)
self.assertIn('not user-visible acceptance', text)
def test_contract_1(self):
text = (ROOT / 'SKILL.md').read_text()
self.assertIn('<code>-uat', text)
self.assertIn('version: 1.14.2', text)
def test_stage_five_scope_and_authority(self):
text = (ROOT / "references/task-delivery-gates.md").read_text()
stage = text.split("### Stage 5", 1)[1].split("### Stage 6", 1)[0]
self.assertIn("#### Deployment and handoff evidence", stage)
self.assertNotRegex(stage, r"(?m)^## ")
self.assertIn("this requirement grants no deployment authority", stage)
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)
if __name__ == "__main__":
unittest.main()
+54
View File
@@ -0,0 +1,54 @@
"""Offline bounded simplification contract; no dependency or network mutation."""
from pathlib import Path
import hashlib
import unittest
ROOT = Path(__file__).resolve().parents[1]
class SimplificationContract(unittest.TestCase):
def test_retained_safety_sections(self):
for (path, start, end), digest in SECTIONS.items():
text = (ROOT / path).read_text().split(start, 1)[1]
if end:
text = text.split(end, 1)[0]
self.assertEqual(hashlib.sha256(text.encode()).hexdigest(), digest, (path, start))
def test_dependencies_unchanged(self):
self.assertIn(DEPS, (ROOT / 'SKILL.md').read_text())
def test_unresolved_gates_and_safety_files_unchanged(self):
for name, digest in PROTECTED.items():
self.assertEqual(hashlib.sha256((ROOT / name).read_bytes()).hexdigest(), digest, name)
def test_decision_point_loads(self):
for name, markers in {
'SKILL.md': ['Before login, load', 'skic-skills/channel-board-skic', 'version: 1.14.2'],
'references/runtime-and-ci.md': ['Before login, load', 'Load `development-method-ttd`', 'Load `development-monorepo-pnpm`'],
'references/status-and-reporting.md': ['Before reporting, load', 'home-v1-skills-code-agent/development-integrity'],
'references/planning-artifact-reconciliation.md': ['corepack enable --install-directory', 'Before reporting, load'],
'references/failure-and-documentation.md': ['Before authoring or validating documentation, load', 'home-v1-skills-code-agent/corp-v1-glossary'],
}.items():
for marker in markers:
self.assertIn(marker, (ROOT / name).read_text(), (name, marker))
def test_no_helper_or_reference_removed(self):
self.assertEqual({p.name for p in (ROOT / 'references').glob('*.md')}, REFERENCES)
self.assertNotIn('SIMPLIFICATION.md', (ROOT / 'SKILL.md').read_text())
def test_retained_reporting_and_planning_guards(self):
status = (ROOT / 'references/status-and-reporting.md').read_text()
for marker in ['wave-previous:', 'List every Task', 'GATE_003_TASK_IMPLEMENTATION', 'status unverified', 'exact failed command']:
self.assertIn(marker, status)
planning = (ROOT / 'references/planning-artifact-reconciliation.md').read_text()
for marker in ['each matching task', 'run_number', 'semantics', 'If the PR merged or closed', 'no second Focus-admission', 'configured silent response']:
self.assertIn(marker, planning)
def test_operational_size_reduction(self):
paths = [ROOT / 'SKILL.md', *ROOT.glob('references/*.md')]
self.assertLess(sum(len(p.read_bytes()) for p in paths), BASELINE_BYTES)
DEPS = ' related_skills: [channel-board-skic, home-v1-discord, documentation-docusaurus, corp-v1-glossary, development-durable-wave-execution, development-gates, development-integrity, development-method-ttd, development-branching-strategy, development-monorepo-pnpm, development-scripts, development-gitops-argo-cd-gondor-v1]'
PROTECTED = {'references/task-delivery-gates.md': '9d803be17cf6254c7ea938e3899d58f25784c294f351d3485a20bdf4be18f597', 'references/repository-entry-and-visibility.md': 'f040d6f57c4ec5faf4527296f7f71a751fab2153809e2dbe20c90cf2d582a77d', 'references/common-pitfalls.md': '41c3b5cc88227b7402f52777f329c3fb9b891954dabee36dfd639f2bf27795a1', 'references/aerosim-lessons-review.md': '03873d038f146e28ea648c95f7c2e32d2648d1b5eaa963fb635980fe6e814514'}
REFERENCES = {'task-delivery-gates.md', 'common-pitfalls.md', 'failure-and-documentation.md', 'runtime-and-ci.md', 'repository-entry-and-visibility.md', 'aerosim-lessons-review.md', 'planning-artifact-reconciliation.md', 'status-and-reporting.md'}
SECTIONS = {('references/runtime-and-ci.md', '### Execution-context toolchain preflight', None): '87a1bdc8c00bdd9f4ad975703bec81f9c9affd26edcfc939f936a7556e7bfa39', ('references/runtime-and-ci.md', '## Channel-owned workspace', '## Shared Corp'): '48d1e74b737db691ec31ac593400d59abc7d4eed4cd67b2f12f8a428a48034b5', ('references/failure-and-documentation.md', '## Failure-Repair Workflow', '## Documentation Ownership'): 'fb6a08666ffcba086984d5437b2d89ce5c7961c007c50e59e1f07f41ea384db1', ('SKILL.md', '## Authority and Escalation', '## Evidence Requirements'): 'e3c566055d9d04d3ab0286e6e5035a8c30f66a81b17b4d0379e8010dead3fa83'}
BASELINE_BYTES = 84789