{ "owners": { "preflight": { "owner": "development-scripts", "reference": "references/runtime-preflight.md", "source_url": "https://gitea.lego-cloud.eu/global-skills/development-scripts", "inspected_head": "0e36552938da94c0539e39b35256b8effe34c25d", "sha256": "07306382b8afe5c2d2e83e2955a04a1523d008e7e39cead7c7a1797bb6640462", "state": "merged source and installed reference byte-identical; authenticated immutable full-package readback verified", "evidence_text": "# Exact-context toolchain preflight\n\nUse before repository commands in a Node/pnpm repository, or any command that may invoke Node or pnpm. This is a reusable execution procedure, not a project directory convention or permission to run tests. The caller supplies the authorized repository, revision, worker context, required environment names and permitted operation. Task-directory containment and stop-on-failed-preflight remain caller responsibilities.\n\n## Required inputs\n\nLoad `development-monorepo-pnpm` and its `references/workspace-and-tooling.md` tooling reference for version selection and committed toolchain/workspace conventions. Resolve required Node and pnpm versions from the repository's **committed toolchain contract**, not ambient executables. Inspect the selected revision's package-manager pin, Node declaration and applicable locked environment/image metadata. Do not invent a universal version or workspace layout. If declarations conflict, are absent, or leave the required exact version unresolved, stop and reconcile the contract with its owner before running the requested command. A version range alone is not an exact observed-version pin.\n\n## Procedure\n\nTreat every foreground shell, detached worktree, background process, main-session review command and CI job as a separate execution context. A successful check elsewhere is not transferable evidence. Perform inspection/preflight in the intended context before the requested repository operation; inspection commands themselves are necessary to establish the context.\n\n1. Resolve the required versions from the committed toolchain contract at the expected source revision. Record the paths/revision used, not secret content.\n2. Inside that exact shell/process/container run `command -v node`, `node --version`, `command -v pnpm`, and `pnpm --version`, using `terminal` or the equivalent job step. Require every command to succeed; compare observed versions to the resolved required versions (normalize only Node's leading `v`). An executable found in a different shell is not sufficient. Record executable paths and observed/required versions.\n3. Verify required non-secret environment variable names are present, including disposable-test database markers when applicable, **without reading or printing their values**. For Bash, a presence-only `[[ -v VARIABLE_NAME ]]` check is suitable after validating a supplied name against `[A-Za-z_][A-Za-z0-9_]*`. Do not dump `env`, expand indirect values, enable tracing, or read credentials. Presence alone does not prove resource isolation or authorize database use; that remains the caller's separate gate.\n4. Verify the actual working directory and repository root; compare source HEAD and linked branch/PR identity with caller-supplied expected identity. Inspect repository state and confirm it is clean or intentionally staged, with every intentional change accounted for. Detached HEAD is allowed only when it matches the authorized revision/worktree. Never reset/stash unrelated changes to make a check green. Do not assume a project-specific application layout.\n5. Start the original command only after every applicable check passes. Keep activation, verification and execution in the same context. Recheck if PATH, activation, working directory, revision, image or required environment changes. A background worker must do its own preflight within its launch command, not consume a foreground success flag.\n\n## Failure and repair\n\nNever assume a background process inherits `PATH`, shell activation, Devbox state, Corepack activation, database variables or other exports from a foreground terminal. Missing `pnpm` is an execution-context/toolchain failure, **never an application-code or test failure**. Missing Node, wrong versions, wrong working directory/revision and absent required names also block execution; they do not constitute product RED.\n\nRepair the exact context by providing the required toolchain path or approved activation. Do not silently install a latest toolchain, rewrite pins, or execute Devbox unless the parent workflow permits it. Then **repeat the complete preflight** there and rerun the original command before making a claim about repository code. Preserve failure and rerun evidence separately.\n\n## Verification and scope\n\nRecord expected/observed versions, executable paths, repository root/revision, branch/PR link, approved state, presence-only results, context identity and command outcome. Do not include secrets or environment values. Local narrow validation never replaces all-app CI or exact-head remote job evidence. Toolchain success is not a claim of CI, publication, deployment or runtime acceptance.\n\nRun the owner contract regression with `terminal(command=\"python3 scripts/test_preflight_contract.py\", workdir=\"\")`. This checks maintained guidance, not a live consumer toolchain; the five steps above must still be exercised for each real consumer context.\n" }, "base_images": { "owner": "devsecops-ci-cd-gitea", "reference": "references/base-images.md", "source_url": "https://gitea.lego-cloud.eu/global-skills/devsecops-ci-cd-gitea", "inspected_head": "669e28eadfe79ac7cb3c10ccdea318dd5296d481", "sha256": "1fb0e24ec5789b195be9ae35fbb9529fa1cab56112dae5baf9455284ca490e53", "state": "merged source and installed reference byte-identical; authenticated immutable full-package readback verified", "evidence_text": "# Reusable CI base-image contract\n\nUse when stable runtimes or OS tools would otherwise be downloaded repeatedly in application jobs. This owner defines reusable construction, validation, publication and consumption mechanics; it does not choose a project's image repository, branch, application layout or runtime-smoke authority. Supply those bindings from the project Delivery/CI overlay. Runtime verification is a separate acceptance layer delegated to the project's authorized runtime-test owner, not permission granted by this reference.\n\nRead [pipeline-workflow.md](pipeline-workflow.md) for trust boundaries, exact checkout and immutable retries, and [harbor-auth.md](harbor-auth.md) for credential handling. These safeguards apply in addition to this contract; base-image work is not an exemption.\n\n## Construction and static contract\n\n1. Keep one folder per image containing a Dockerfile, machine-readable version/platform metadata, usage documentation, a build helper and a static publication contract. Record required upstream reference, platforms, runtime/tool pins, numeric user/group and supported workspace path. Do not prescribe a product's application directories.\n2. Pin the upstream base by digest (`repository@sha256:<64 lowercase hexadecimal characters>`). Check the actual resolved platform against metadata; for a multi-platform index, record index and platform-manifest relationships rather than silently comparing unlike digests.\n3. Assert exact runtime/tool versions, architecture, numeric non-root identity, writable workspace, CA trust, Git, shell and every other required tool. Static/unit checks inspect Dockerfile and metadata; they cannot alone prove live writability, effective UID, trust or executable behavior. The authorized runtime verifier must exercise those assertions on the **published digest** and record results separately. Never describe a static declaration as runtime proof.\n4. 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 or credentials into a generic base image. This does not waive the consumer's committed toolchain contract or exact-context preflight in `development-scripts/references/runtime-preflight.md`.\n\n## Candidate isolation and trusted publication\n\n- Build and perform static/unit validation on pull requests **without registry credentials**. Credential absence must be structural: no publication secret in workflow-global scope, candidate job environment, persistent runner home, Docker config, build args, cache or artifact. Skipping login does not remove an already available credential. Use an approved credential-free base acquisition path; if unavailable, stop rather than leak publication credentials to candidates.\n- Choose exactly one configured default integration branch, as in the pipeline owner (`test` or `main`), and publish only its exact trusted integration commit. PR, fork, branch-readiness and broad tag triggers cannot publish. Separately authorized release workflows must retain equivalent isolation, never broaden the ordinary candidate path.\n- Complete candidate execution before introducing a narrowly scoped Harbor robot secret in the isolated trusted publication job. Pass secrets via standard input only. Keep temporary Docker/Helm credential stores scoped to the job, clean on success and failure, and treat logout failure on persistent runners as failure after cleanup. Never pre-seed push credentials into the reusable job image or execute untrusted candidate hooks after authentication.\n\n## Immutable publication and direct readback\n\n1. Verify checkout identity before building. Tag the image with the full 40-character source revision; never publish `latest`, mutable version aliases or shortened SHAs for governed consumption. Enforce registry immutable-tag rules as well as workflow checks.\n2. Preserve the validated local image ID. Existing tags are reusable only when the remote OCI config digest equals that validated local image ID; different content is a hard failure, not an overwrite. For multiple platforms, verify each required platform's config identity and expected manifest/index membership. Missing or ambiguous remote evidence fails closed.\n3. After publication, read back the Harbor artifact directly: verify reference, source identity, platform and manifest digest. Record source URL/revision, workflow run/attempt/job, immutable tag, manifest digest, config digest/local image ID and canonical millisecond ISO-8601 UTC timestamp. Config digest is for retry content comparison; manifest digest is for consumption. Do not interchange either with source SHA or chart archive checksum.\n4. Require the final aggregate under `always()` to explicitly require every necessary build/publication/readback job's success. A green push step or skipped aggregate is not complete publication proof.\n\n## Consumer verification and forward repair\n\nConsume the image **by digest**, using the direct-readback manifest (or verified platform index) identity, not a mutable tag or unverified local name. Inspect each consuming workflow's actual job/container reference, resolve it against Harbor and compare to the recorded digest. Verify the runtime/platform and Node/pnpm toolchain match the consumer's committed contract inside that exact job context; matching YAML text alone is insufficient.\n\nKeep the first real Gitea build, trusted Harbor publication, digest readback and consumer workflow at the exact PR-head SHA as separate evidence layers. The base-image source/integration SHA and the consumer PR-head SHA are distinct fields; do not substitute one for the other. Runtime smoke remains a further independent acceptance result assigned by the project overlay. No layer implies deployment or live reconciliation.\n\nRepair 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 project acceptance. Do not overwrite old immutable tags, rewrite history or switch consumers on a publication claim alone. Record failed and replacement identities and verification results.\n\n## Fail-closed regression matrix\n\nContract-test generated workflows and helpers with both accepted and rejected fixtures. Reject:\n\n- broad publication triggers, non-default or wrong-head publication, and skipped required jobs;\n- missing/malformed/wrong upstream or consumer digests, mutable tags, shortened SHAs and content-mismatched retries;\n- secret access from PR paths (including inherited credentials), persisted checkout credentials and credential cleanup failures;\n- shell interpolation of candidate-controlled expressions: bind untrusted inputs as data, validate them, quote arguments and never `eval` them;\n- missing version/platform metadata, root or nonnumeric identity, missing tool/trust/workspace assertions;\n- reintroduced runtime setup actions or package-manager bootstrap and baked application dependencies;\n- evidence that collapses publication/readback/consumer/runtime gates or confuses digest kinds.\n\nRun `terminal(command=\"python3 scripts/test_base_image_contract.py\", workdir=\"\")` and `terminal(command=\"python3 scripts/test_pipeline_policy.py\", workdir=\"\")` for this owner's offline guidance regressions. They do not validate a generated workflow or claim a live build, publication, readback or runtime smoke. Exercise the matrix against actual consumer implementation and gather real layer-specific evidence before claiming adoption.\n" } }, "moved_clauses": [ { "clause": "version resolution, executable/version comparisons", "owner_key": "preflight", "section": "Required inputs; Procedure 1\u20132" }, { "clause": "presence-only environment and repository identity/state checks", "owner_key": "preflight", "section": "Procedure 3\u20134" }, { "clause": "same-context activation, inheritance failure classification and complete retry", "owner_key": "preflight", "section": "Procedure 5; Failure and repair" }, { "clause": "image folder/metadata, digest/tool/platform/user/workspace/trust assertions and lockfile parity", "owner_key": "base_images", "section": "Construction and static contract" }, { "clause": "credential-free candidates and isolated trusted publication", "owner_key": "base_images", "section": "Candidate isolation and trusted publication" }, { "clause": "full-source tags, direct Harbor readback, immutable retry and aggregates", "owner_key": "base_images", "section": "Immutable publication and direct readback" }, { "clause": "digest consumer verification and forward repair mechanics", "owner_key": "base_images", "section": "Consumer verification and forward repair" }, { "clause": "negative trigger/tag/secret/interpolation/digest/setup regression cases", "owner_key": "base_images", "section": "Fail-closed regression matrix" } ], "retained_local": [ "every foreground shell", "detached worktree", "background process", "worker", "Hermes main-session review command", "CI job", "Stop on failed preflight", "selected Task directory", "selected repository", "allowed command scope", "complete repository CI", "last known-good digest", "trusted `test` branch", "UAT", "exact PR-head SHA" ], "superseded_golden_rules": [ { "path": "references/runtime-and-ci.md", "pattern": "(?s)### Per-project reusable CI base images\\n.*?(?=### Gondor)", "hashes": [ "0c92e0521c57c357a62c8313c70527547427d98b7647ec8cd1a97c148b5ba4f1" ] }, { "path": "references/runtime-and-ci.md", "pattern": "(?s)Treat every foreground shell.*?(?=### Immutable|### Per-project)", "hashes": [ "8df9d2e952a6a8c48fd3d0a18357aea21d5ffbb1e06e53c7273c6e50e2545be5" ] } ] }