refactor: implement concrete Delivery responsibility dispositions

This commit is contained in:
jarvis-at-skic committed 2026-10-23 08:11:40 +00:00
1 parent cb6b41f1a5
commit 1bff2cefab
23 files changed
+231 -717

No files matched your search

+3 -19
View File
@@ -1,21 +1,5 @@
# the adopted project Delivery Pitfalls
# Delivery exception checks
Load this reference when a gate fails, when work resumes after interruption, or before reporting a blocker, CI result, merge, or completion.
On failed gates or resumption, load [Task gates](task-delivery-gates.md) and [planning reconciliation](planning-artifact-reconciliation.md) to verify original admission, current claim and visibility; merged planning text is not implementation approval.
Before execution, load [runtime-and-ci.md](runtime-and-ci.md#execution-context-toolchain-preflight) for exact-context preflight. Before claims, load `development-gates` and `development-integrity`, then [status-and-reporting.md](status-and-reporting.md) and [planning-artifact-reconciliation.md](planning-artifact-reconciliation.md) for project formatting, semantic reconciliation and duplicate suppression.
## Common Pitfalls
1. Patching symptoms before understanding root cause.
2. Changing requirements or architecture implicitly through code.
3. Editing without loading applicable project engineering skills.
4. Skipping tests for behavioral fixes.
5. Updating documentation with aspirational rather than actual practice.
6. Inspecting another project.
7. Starting implementation because requirements exist but human implementation approval is absent.
8. Ignoring architecture task dependencies, the Task's `READY_FOR_DELIVERY` handoff, or target-version allocation.
9. Posting passive status when safe implementation, testing, diagnosis, or documentation work is available.
10. Treating a human-merged planning or Architecture documentation PR as implementation approval.
11. Treating an ideation-board entry, generated presentation, or broad approval as equivalent to an exact Task `READY_FOR_DELIVERY` transition—or requiring a second admission after that verified transition.
12. Editing in a local-only worktree or on a differently named local branch before the exact remote branch and PR head are visible and verified.
13. Stopping at a repairable gate failure, abandoning the active Task, or starting another Task instead of fixing forward and rerunning the gate until it passes.
Load `ci-runtime-skic` before command/repair work, `delivery-docs` before recording operational practice, and `status-reporting-skic` before blocker or completion wording. These owners carry their topic pitfalls once; do not repeat them here.
+4 -47
View File
@@ -1,56 +1,13 @@
# the adopted project Failure and Documentation Operations
Load this reference when repairing a failure or changing Delivery-owned project documentation.
# Project failure and documentation bindings
## Failure-Repair Workflow
When a build or CI failure is observed:
1. verify repository, linked branch and PR, exact failed command/file/test/job, failure class, 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. load `development-method-ttd` and [runtime-and-ci.md — Unit testing](runtime-and-ci.md#unit-testing); observe the product-reason unit failure before behavior changes;
6. implement the smallest safe forward fix, preserving valid shared work and missing-RED honesty;
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;
11. repeat diagnosis, repair, and affected validation until the active gate passes.
The skill must continue with a safe forward fix when the failure and expected behavior are clear. A repairable failure does not end the Task or authorize moving to another gate or Task. If evidence is insufficient, requirements/architecture conflict, an external dependency is unavailable, or the required action exceeds authority, keep the Task in the same gate, record the separate blocker with evidence and owner, 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, weaken a gate, or treat a blocker as a passed gate. Resume the same gate and continue the repair loop when the blocker is removed.
Before diagnosis or forward repair, load `ci-runtime-skic` for the same-gate repair loop and [Unit testing](runtime-and-ci.md#unit-testing) for local TTD/exception authority. Before blocker communication, load `status-reporting-skic` for the evidence packet and owner routing. Keep the selected Task/gate; never weaken requirements to pass it.
## Documentation Ownership
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
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 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.
Update these pages from verified project practice. Do not document a planned process as already operational.
Before changing Delivery-owned Ways of Working or Engineering, load `delivery-docs` for coverage and evidence-to-page reconciliation. Bind the authoring owner to `documentation-docusaurus` at https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus, plus the project-adopted overlay. Before defining reusable terms, bind/load `glossary-skic` at https://gitea.lego-cloud.eu/home-v1-skills-code-agent/glossary-skic. Stop if the source-qualified owner is unavailable; an unrelated same-name runtime skill is not that owner.
## Synchronization Workflow
Before reconciling planning/Architecture/Kanban changes, load [planning-artifact-reconciliation.md](planning-artifact-reconciliation.md) for Task-row semantics and its verification-owner loads. Use the entry skill's synchronization/iteration contract for useful safe work and current documentation. Reconcile only changed evidence; do not duplicate its workflow here.
Before reconciling planning/Architecture/Kanban changes load [planning-artifact-reconciliation.md](planning-artifact-reconciliation.md); follow the entry skill's single synchronization workflow for useful safe work and domain-owner loads.
+16
View File
@@ -0,0 +1,16 @@
# Final Delivery verification
- [ ] Only same-project channels and repositories were used.
- [ ] Work maps to approved requirements/architecture.
- [ ] Feature has explicit human `Approved for Implementation` evidence and a documented target version.
- [ ] Selected tasks respect documented dependencies and carry exact Task `READY_FOR_DELIVERY` evidence.
- [ ] At least one useful delivery activity was completed, or a concrete blocker was documented and routed.
- [ ] Applicable project skills were loaded.
- [ ] Tests and builds were actually run.
- [ ] Remote branch and matching CI head SHA were verified.
- [ ] Contradictions were escalated, not guessed through.
- [ ] Ways of Working and Engineering documentation remains accurate.
- [ ] Completed work includes exact evidence.
Apply this evidence checklist before a final Delivery handoff. It checks the existing gates; it grants no new authority and is not another implementation stage.
@@ -35,4 +35,4 @@ New pickup requires current `READY_FOR_DELIVERY`, dependencies, target version,
## Avoid duplicate status
Before posting, compare the proposed report with enough Delivery history to find the newest marker, head SHA, CI task, and blocker set. If there is no new human decision, repository head, CI result, actionable failure, or durable documentation change, return the configured silent response instead of restating the same gate.
Before posting, compare the proposed report with enough Delivery history to find the newest marker, head SHA, CI task, and blocker set. If there is no new human decision, repository head, CI result, actionable failure, or durable documentation change, return the configured silent response instead of restating the same gate.
+9 -58
View File
@@ -1,40 +1,10 @@
# the adopted project Runtime and CI
# Project runtime bindings
Load this reference before login, toolchain execution, CI work, image publication, or Gondor resource work.
Before commands, CI changes, image publication, resource work or repair, load `ci-runtime-skic` and follow its full procedure with these bindings. Before login or credential-bearing operations, load `development-security-skic` and `development-security`; Board policy remains authoritative. Stop the affected action when an owner cannot load.
## Channel-owned workspace
Resolve the channel root as `<code>-delivery/` under the active user's working root:
```text
<code>-delivery/
├── cache/ # reusable channel toolchains and technical dependencies
├── uploads/
└── workspace/
└── <TASK_ID>/
├── application/ # always: repository clone
├── documentation/ # always: repository clone
├── review/ # optional: only when separate review files are needed
├── cache/ # optional: only when a Task-specific cache is needed
├── tmp/ # optional: only when temporary Task files are needed
├── logs/ # optional: only when logs must be retained
└── artifacts/ # optional: only when outputs must be retained
```
- `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.
- Do not create Task-local `review/`, `cache/`, `tmp/`, `logs/`, or `artifacts/` speculatively. Create each folder only when a concrete activity for that Task needs it.
- Use Task-local `review/` only for a separate review checkout or review output. Use Task-local `cache/` only for non-reusable data bound to that Task; reusable installed technical dependencies belong in the channel-level `cache/`. Use `tmp/`, `logs/`, and `artifacts/` only for their named Task-local purpose.
- Run dependency installation, generation, tests, and builds inside the applicable repository clone using that repository's normal paths. Copy or export outputs to `artifacts/` only when they must be retained separately.
- Keep every optional folder inside the selected Task directory. Never share it between Tasks or place it at the channel root.
- Before every local repository command, resolve the real working directory and require it to be inside the selected Task directory. A command running elsewhere is invalid evidence and must stop before mutation.
- Do not reuse another Task's clone or support folder as a shortcut. Resume only from the selected Task's own workspace after fetching and matching its visible PR head.
## Shared Corp v1 System Login
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.
Bind the project channel root under the active working root, Task `workspace/<TASK_ID>/`, reusable `cache/` and channel-provided `uploads/`. The shared owner defines cache contents, optional folders, real-CWD containment and exact-context preflight; this binding does not authorize execution outside the selected Task.
## Delivery Responsibilities
@@ -42,43 +12,24 @@ Before login, load `channel-board-skic` and follow its complete **Corp v1 System
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 every behavior change, defect fix or refactor. Follow its mandatory failing-test-first unit workflow and retain real commands/results; request non-unit coverage from UAT. Exceptions require the authorized project owner explicitly approving a documented exception. Discard/start-over applies only to the executor's isolated, unpublished experimental delta, preserving unrelated or valid work. Never rewrite shared history, delete another worker's changes or revert integrated work. Repair shared/integrated code forward, record historical missing RED honestly and never claim retrospective tests proved test-first compliance; seek the named project-authority exception if compliant repair cannot satisfy the gate.
### Build and continuous integration
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.
Load `ci-runtime-skic`, `development-gates` and `development-integrity`; preserve the required job inventory and local gate order in [Task gates](task-delivery-gates.md). Before Actions or publication load `devsecops-ci-cd-gitea` and the bound project overlay.
### Execution-context toolchain preflight
Immediately before every repository operation, load `skill_view(name="development-scripts", file_path="references/runtime-preflight.md")` for exact-context checks and repair, plus `skill_view(name="development-monorepo-pnpm", file_path="references/workspace-and-tooling.md")` for committed versions. Load `development-scripts` for the selected repository's script overlay; generic mechanics never replace project authority.
Treat every foreground shell, detached worktree, background process, worker, Hermes main-session review command, and CI job as a separate execution context. Complete the applicable preflight in that exact context before execution; the full owner procedure is mandatory for a Node/pnpm repository or any command that may invoke Node or pnpm. Stop on failed preflight or an unavailable owner; do not run the original command until its complete preflight passes.
Delivery supplies the selected Task directory, selected repository, expected branch/PR/revision, required non-secret environment names under `CORP_V1_<CODE>_*`, and allowed command scope. Preserve Task/cache isolation and real-CWD containment above. Preflight does not authorize resource-dependent tests, functional non-unit suites, credentials, Devbox execution or deployment; the existing project boundary decides allowed operations. Narrow local checks never replace complete repository CI, all required jobs/aggregates or exact-head evidence in [Task gates](task-delivery-gates.md).
Before Delivery publication/install or operational adoption, verify the published and installed owner reference covers the mapped safeguards and record its immutable owner revision and reference hash. The adopted immutable owner revisions and reference hashes are recorded in FULL-PROGRAM.md and the owner-consolidation manifest; a sibling source checkout is not installed-owner evidence. If that gate is unresolved, stop adoption rather than silently weakening preflight. See [FULL-PROGRAM.md](../FULL-PROGRAM.md#final-bounded-owner-consolidation) for inspected evidence.
Before each foreground/background/worktree/worker/review/CI command, load `ci-runtime-skic` and its exact-context preflight, including `development-scripts` → `references/runtime-preflight.md` and `development-monorepo-pnpm` → `references/workspace-and-tooling.md`. Supply the selected Task/repository, branch/PR/revision, allowed scope and `CORP_V1_<CODE>_*` non-secret environment names. Load `development-scripts` for the repository overlay.
### Per-project reusable CI base images
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.
Before creating, validating, publishing, consuming or repairing a base image, load `skill_view(name="devsecops-ci-cd-gitea", file_path="references/base-images.md")`, then its `references/pipeline-workflow.md` and `references/harbor-auth.md` trust/credential contracts. The owner carries construction, credential-free candidate validation, immutable publication/readback, fail-closed regressions and consumer verification mechanics. Stop if unavailable; retain all project-specific image requirements rather than replacing them with generic defaults.
- Publish only from the trusted `test` branch of the selected project base-image repository; candidate checks remain credential-free. The global owner's configurable branch does not change this binding.
- Consume the directly verified immutable digest in project workflows, never `latest`, a mutable tag or an unverified local name. Keep the first real Gitea build, Harbor publication, digest readback and consumer workflow at the exact PR-head SHA as separate Delivery evidence layers.
- Runtime smoke and published-digest runtime acceptance belong to UAT, separately from Delivery static/unit validation. No publication or consumer success implies deployment or UAT acceptance.
- 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 and applicable UAT acceptance.
Owner adoption evidence: global CI source `669e28eadfe79ac7cb3c10ccdea318dd5296d481`; inspected source and installed `references/base-images.md` are byte-identical (SHA-256 `1fb0e24ec5789b195be9ae35fbb9529fa1cab56112dae5baf9455284ca490e53`). Its `owner-responsibility.json` maps both Delivery contracts. Reverify the complete published owner package and project CI overlay at adoption; this is owner-policy evidence, not a consumer build, publication or runtime result.
Bind `corp-v1-<code>/corp-v1-<code>-base-images`, trusted publication branch `test`. Before image work load `ci-runtime-skic` for digest consumption and forward-repair safeguards and its required `devsecops-ci-cd-gitea` reference loads.
### Gondor runtime-resource placement
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-home-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.
- 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.
- Before storage design or mutation, load `truenas` and `references/gondor-retained-application-storage.md`. That owner supplies dataset/NFS, retained static PV/PVC and live StorageClass verification; stop if unavailable. Durable storage must not use a deletion-reclaim policy. The load grants no platform authority and does not assert current live storage state.
- 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.
Before resource/storage work load `ci-runtime-skic` for isolation, secret-store, retained-storage and selected GitOps owner/fallback procedures. Bind the approved template and separate desired-state repository for each environment. Only the project-approved non-production environment is within Delivery authority; missing storage/platform authorization blocks mutation.
+3 -79
View File
@@ -1,81 +1,5 @@
# the adopted project Status and Reporting
# Project reporting bindings
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.
Before Task/wave/CI/blocker/completion reports or lifecycle changes, load `status-reporting-skic` and `development-integrity` (including `references/remote-checkpoint-matrix.md`). The shared reporter owns vocabulary and templates; the current project Scope record remains authoritative.
## Scope Status Vocabulary
Before reporting or changing any lifecycle status, read the project's current `ways-of-working/scope.md`. Use only the values defined there.
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 status field. If the 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 value even when a separate plain-language action is also included.
## Wave Status Report
When the active project authority explicitly asks for project, delivery, blocker, progress, or wave status, begin the status report with this exact first-line structure, with no text before it:
```text
wave-previous: <previous wave> | wave-current: <current wave> | wave-next: <next wave>
```
Each value must be an actual dependency-wave label calculated by the the adopted project Release Task Board, such as `Wave 11`, `Wave 12`, or `Wave 13`. Never substitute activities, work descriptions, statuses, invented phases, or ad hoc labels. Resolve the current wave and its adjacent existing waves from the Board selector and task assignments; do not infer them from conversation wording. Use `none` only when the Board has no previous or next wave.
Do not repeat the wave header or task chapter in ordinary acknowledgements, implementation narration, questions, or non-status replies. Use them only when the active project authority explicitly asks for status.
### Current-wave task chapter
Immediately after the header in a requested status report, include:
```text
## Wave XX (Current)
- TASK-XXXX — <status> — Responsible: <Hermes main session or concrete owning process>
```
Replace `XX` with the current Board wave number. List every Task assigned to that wave—never a sample or only changed Tasks—and use each Task's verified flow status. For responsibility, name Hermes main session when it actively owns the Task; otherwise name the concrete owning process, such as Delivery pickup, implementation/review, integration, or Release handoff. When no active executor or owning process exists, say `Unassigned`; never invent an agent, process, or ownership. Refresh the Board/task records and live process state before reporting when they may have changed.
### Human-facing delivery updates
In every implementation, review, CI, blocker, merge, handoff, or completion update, lead with the linked branch and pull request where the work is visible. The next line must identify the Task, exact Task status, active gate code, and gate title:
```text
<TASK_ID> | <TASK_STATUS> | <GATE_CODE> — <GATE_TITLE>
```
Example:
```text
TASK-0084 | IN_PROGRESS | GATE_003_TASK_IMPLEMENTATION — Implement and Review the Task
```
While work remains inside a gate, continue reporting that same code. When its exit gate passes, report the transition explicitly:
```text
GATE_003_TASK_IMPLEMENTATION passed → GATE_004_TASK_PR_CI
```
When blocked, name the gate where progress stopped:
```text
BLOCKED at GATE_004_TASK_PR_CI — Verify and Merge the Task PR
```
Do not invent a separate phase or shorthand. Do not lead with or routinely include commit SHAs, tree hashes, digests, internal worktree paths, or temporary review-commit identities; retain those for automated verification and provide them only when the active project authority asks for audit detail or when an identity mismatch itself is the blocker.
When anything fails, identify the exact failed command, file, test, or CI job. State its failure classification—application code, test assertion, workflow, infrastructure, credentials, or local execution environment—then provide the expected behavior and observed behavior, whether repository or remote state changed, and the concrete repair or owner. Never summarize a failure as only “validation failed”, “review failed”, or “CI failed”.
Bind the active project status-request authority, actual Release Task Board selector, Scope record and release owner before reporting. Missing records mean status unverified. No report changes admission, release authority or scheduler policy.