refactor: implement governed Delivery program contracts
This commit is contained in:
1 parent
c306ea4794
commit
65e546c448
18 files changed
+575
-99
No files matched your search
@@ -44,13 +44,7 @@ Load `development-monorepo-pnpm` for pnpm/TypeScript implementation and `develop
|
||||
|
||||
### 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;
|
||||
- run the narrowest relevant tests first, then required broader validation;
|
||||
- record exact commands and real results.
|
||||
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
|
||||
|
||||
@@ -58,35 +52,33 @@ Use [Delivery's build/CI responsibilities](../SKILL.md#build-and-continuous-inte
|
||||
|
||||
### Execution-context toolchain preflight
|
||||
|
||||
Treat every foreground shell, detached worktree, background process, Hermes main-session review command, and CI job as a separate execution context. Before any repository command or operation runs in an execution context, complete the applicable preflight for that exact context. For a Node/pnpm repository—or any command that may invoke Node or pnpm—the following checks are mandatory:
|
||||
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.
|
||||
|
||||
1. resolve the repository-required Node and pnpm versions from its committed toolchain contract;
|
||||
2. run `command -v node`, `node --version`, `command -v pnpm`, and `pnpm --version` inside the exact context, then compare the observed versions with the committed required versions;
|
||||
3. verify required non-secret environment variable names are present, including disposable-test database markers when applicable, without reading or printing their values;
|
||||
4. verify the actual working directory, linked branch/PR identity, and clean or intentionally staged repository state; and
|
||||
5. start the repository command only after every applicable preflight check passes.
|
||||
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.
|
||||
|
||||
Never assume a background process inherits `PATH`, shell activation, Devbox state, Corepack activation, database variables, or other exports from a foreground terminal. A missing `pnpm` executable is always an execution-context/toolchain failure, never an application-code or test failure. Repair the exact context by providing the required toolchain path or activation, repeat the complete preflight there, and rerun the original command before making any claim about repository code.
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
- 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 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, 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.
|
||||
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.
|
||||
|
||||
### 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-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.
|
||||
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.
|
||||
- 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.
|
||||
- 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.
|
||||
Reference in new issue
Block a user