Daily Routine / AI Training

07 - Supply Chain Security Standard Draft

Mandatory Zero Trust software supply-chain governance standard for evaluating, approving, verifying, integrating, maintaining, reviewing, and retiring every external artifact introduced into platform repositories, including container images, packages, repositories, CI/CD components, AI models, MCP servers, IDE extensions, binaries, infrastructure modules, and external tooling.

Text size
Status: draftCreated: 2026-07-05Last updated: 2026-07-05

Document Scope

This document defines the mandatory supply-chain security standard for the platform. It governs how human operators, ChatGPT sessions, Codex sessions, AI-assisted development tools, automation workers, future AI agents, and future MCP/RAG systems evaluate, approve, acquire, verify, integrate, maintain, review, and retire external software artifacts.

This standard applies to every repository that belongs to the broader platform workspace. It applies to deployable application repositories, shared library repositories, server and infrastructure repositories, context/reference repositories, personal utility repositories, and any future repository class that receives, mirrors, executes, references, builds from, installs, packages, imports, transforms, publishes, or distributes third-party software or third-party source material.

This document is not limited to Docker. Docker is only one supply-chain surface. This standard applies to every artifact that can become part of the platform or influence platform behavior, including but not limited to:

  1. Container base images.
  2. Container runtime images.
  3. Container build images.
  4. Python packages.
  5. Python project managers.
  6. Python interpreters and runtime distributions.
  7. Node packages.
  8. Frontend build tools.
  9. Remote Git repositories.
  10. Git repository submodules, vendored source, copied examples, templates, snippets, patches, and generated scaffolds.
  11. CI/CD templates, reusable workflows, actions, includes, runners, and pipeline helper images.
  12. IDEs, IDE extensions, code-editor extensions, language servers, formatters, linters, and local development tools.
  13. Command-line tools and third-party binaries.
  14. Operating-system packages installed during local setup, CI/CD jobs, container builds, server provisioning, container runtime setup, or deployment work.
  15. Infrastructure modules, Kubernetes manifests, Helm charts, Terraform/OpenTofu modules, Ansible roles, service-unit templates, server bootstrap material, and deployment scaffolds.
  16. SDKs, API clients, authentication libraries, payment libraries, email libraries, object-storage libraries, bot-protection packages, and integration wrappers.
  17. AI models, AI SDKs, AI gateway packages, prompt-tooling packages, agent frameworks, MCP servers, and AI-agent tools.
  18. Browser extensions, local desktop helper programs, and any other external tool that can inspect, edit, execute, generate, transform, sync, publish, deploy, or analyze project material.

This document also governs reference and documentation artifacts when those artifacts are mirrored into context repositories for AI use. A documentation mirror can mislead a future AI session if the source is untrusted, stale, tampered with, incorrectly attributed, or copied from an unofficial source. Context/reference repositories therefore have a different supply-chain profile than deployable application repositories, but they are not outside this standard.

This document does not replace the Repository Classification Standard, Runtime Validation Standard, Git Checkpoint Standard, Git Commit Message Standard, Patch/Codex Workflow Standard, CI/CD Pipeline Standard, Architecture Standards, Technology Stack Guide, Python Backend Restructuring Standard, Docker implementation plans, Kubernetes implementation plans, release standards, or task-specific handoff. It adds the supply-chain trust layer that controls whether an external artifact may enter the project at all.

Standard

Document Type: Supply Chain Security Standards Document Applies To: External artifacts, third-party packages, container images, AI models, build tooling, CI/CD components, source repositories, local development tools, deployment tools, mirrored reference material, dependency updates, release artifacts, and future AI-agent software adoption decisions. Status: Authoritative project standard unless later superseded by a newer dated standards document. Primary Purpose: Establish a strict Zero Trust supply-chain model so no AI agent, coding assistant, automation worker, or human workflow silently introduces unverified external software or source material into the platform.

1. Purpose

The purpose of this standard is to prevent supply-chain compromise, dependency confusion, malicious package adoption, unsafe container-image selection, unverified tool installation, accidental trust of unofficial sources, silent artifact drift, AI-driven tool creep, stale dependency risk, unreviewed binary execution, unapproved model adoption, and unsafe CI/CD component use.

The platform is being built by one human operator with heavy AI assistance. That operating model creates unusual leverage and unusual risk. AI assistants can accelerate development, but they can also recommend packages, copy code, install tools, pull container images, adopt templates, use generated scaffolds, or follow examples without fully verifying the source. This standard exists to prevent that failure mode.

A future AI session must not treat convenience as permission. A package that appears popular is not automatically safe. A repository with many stars is not automatically trustworthy. A container image that builds successfully is not automatically approved. A tool mentioned in a tutorial is not automatically appropriate. A vendor's official status is relevant, but official status alone is not sufficient. An artifact becomes eligible for use only after it passes the supply-chain evaluation process and receives explicit operator approval.

This standard also protects the project from long-term architectural sprawl. Every external artifact increases the project's attack surface, maintenance burden, upgrade burden, licensing exposure, operational complexity, and recovery complexity. The first question is therefore not "Can this be installed?" The first question is:

What problem does this artifact solve that cannot already be solved using the current approved stack?

If the current approved stack already solves the problem, the artifact must not be adopted merely because it is fashionable, popular, newer, easier for an AI agent to use, or commonly recommended in tutorials.

The purpose of this standard is not to stop all adoption. The purpose is to make adoption deliberate, documented, reversible, reviewable, and safe enough for a long-lived platform that will be maintained by humans and AI agents over time.

2. Governing Philosophy: Zero Trust Software Supply Chain

The platform uses a Zero Trust software supply-chain model.

Every external artifact is untrusted by default. This rule applies even when the artifact is popular, official, open source, free, commercially supported, widely downloaded, used by large companies, included in tutorials, generated by a framework, or recommended by an AI assistant.

The default decision is No.

An artifact becomes eligible for adoption only after all required evidence has been gathered, reviewed, documented, and explicitly approved by the human operator. Until that approval occurs, the artifact must not be installed, imported, copied, vendored, mirrored, referenced in executable configuration, added to dependency files, added to a container build, added to a CI/CD pipeline, added to server setup, added to a context repository, added to a release process, or treated as part of the platform.

AI systems do not get trust authority. AI systems may gather evidence, compare alternatives, identify risks, prepare a recommendation, draft records, and propose commands. AI systems shall not make the final trust decision. The final trust decision belongs only to the human operator.

Every version is a new artifact. Approval of one version does not approve a later version. Approval of one package does not approve its plugins. Approval of one container image tag does not approve a later digest behind the same tag. Approval of one source repository does not approve all branches, all releases, all examples, all generated code, all forks, all dependencies, or all future versions.

This standard intentionally begins strict. The project may relax specific requirements later through a deliberate standards revision. The project shall not begin with loose standards and attempt to tighten them after untrusted artifacts have already entered the system.

3. Definitions

3.1 External Artifact

An external artifact is any software, source material, executable, package, container image, library, plugin, model, template, workflow, or reference material that originates outside the platform's own repositories and can influence development, build, validation, runtime, deployment, documentation, AI-agent behavior, or operator workflow.

Examples include Python packages, Docker images, container base images, package-manager installers, remote Git repositories, CI/CD templates, command-line tools, IDE extensions, AI models, MCP servers, Kubernetes manifests, infrastructure modules, and mirrored vendor documentation.

3.2 Approved Artifact

An approved artifact is an external artifact that has passed the required evaluation process, has a documented Technology Decision Record where applicable, has a documented Supply Chain Record, has a documented Integration Record when integrated into a repository, and has received explicit operator approval.

An approved artifact is approved only for the specific version, source, repository class, integration method, and use case documented in the approval records.

3.3 Unapproved Artifact

An unapproved artifact is any artifact that lacks explicit operator approval or lacks required evidence. Unapproved artifacts shall not be installed, imported, added to dependency files, added to container builds, added to CI/CD configuration, used in deployment, mirrored into context repositories, or adopted by AI tooling.

3.4 Candidate Artifact

A candidate artifact is an artifact being evaluated. A candidate artifact is not approved. A candidate artifact may be discussed, researched, compared, and documented, but it shall not be integrated until approval occurs.

3.5 Artifact Version

An artifact version is the exact version, release, digest, commit SHA, model revision, package version, binary version, image digest, or other immutable identifier that defines what is being adopted. A mutable label is not a version for approval purposes.

3.6 Floating Reference

A floating reference is any reference that can point to different content over time. Floating references include latest, main, master, develop, nightly, edge, rolling, unstable, beta, preview, unpinned branch names, unpinned tags where the underlying artifact digest is not recorded, broad version ranges, and package specifications that allow uncontrolled upgrades.

Floating references are prohibited for production dependencies and production container images. They are also prohibited in any context where reproducibility, security, or operational recovery matters.

3.7 Immutable Reference

An immutable reference is a reference that identifies exact content. Examples include container image digests, Git commit SHAs, locked package hashes, release checksums, signed release artifacts, SBOM component identifiers, and other cryptographic or content-addressed identifiers.

3.8 Provenance

Provenance is the evidence showing where an artifact came from, who produced it, how it was built or published, and whether the artifact is the expected artifact from the expected upstream source.

3.9 Supply Chain Record

A Supply Chain Record is the permanent project record that documents why an artifact is trusted, where it came from, which version is approved, how it was verified, what risks exist, and how it should be reviewed or retired.

3.10 Technology Decision Record

A Technology Decision Record documents why a technology was selected, what alternatives were considered, what problem it solves, what risks were accepted, and what conditions would cause reconsideration.

3.11 Integration Record

An Integration Record documents how an approved artifact is integrated into a specific repository, build path, runtime process, CI/CD pipeline, server setup, container image, deployment process, context repository, or operator workflow.

3.12 Supply Chain Evaluation Report

A Supply Chain Evaluation Report is the AI-prepared evidence packet submitted to the operator before adoption. It is not an approval record. It is the artifact investigation summary that supports the operator's decision.

3.13 SBOM

An SBOM is a Software Bill of Materials. It is an ingredients label for software. It identifies software components included in a build or release, including versions, dependency relationships, licenses, suppliers, and sometimes hashes or vulnerability information.

3.14 Cosign

Cosign is a tool used to cryptographically sign and verify container images and related artifacts. In this project, production container images shall be signed and verified as part of the release and deployment process.

3.15 Key-Based Signing

Key-based signing uses a private signing key controlled by the project and a corresponding public key or certificate used for verification. It requires secure key generation, storage, backup, rotation, and access control.

3.16 Keyless Signing

Keyless signing uses identity-based signing through an external identity provider and a transparency log rather than a long-lived local private key. The signing identity, issuer, certificate, and transparency-log entry become part of the verification evidence.

3.17 Decision Status

Decision status is the formal adoption status assigned after evaluation. Approved, rejected, deferred, and experimental-only decisions must be recorded distinctly. An experimental-only decision is not production approval.

4. Authority Model

4.1 Operator Authority

The human operator is the only authority that may approve adoption of an external artifact.

The operator must approve:

  1. First adoption of a new artifact.
  2. Adoption of a new version.
  3. Upgrade or downgrade of an approved artifact.
  4. Replacement of an artifact.
  5. Removal of an approved artifact when removal affects runtime, build, validation, deployment, or documentation behavior.
  6. Acceptance of unresolved supply-chain risk.
  7. Any exception to this standard.
  8. Any experimental-only use of an unapproved production artifact.
  9. Any temporary exception involving unsigned, unpinned, unverified, or unverifiable artifacts.

4.2 AI Authority

AI assistants may perform investigation, comparison, documentation, and recommendation work. They may not approve adoption.

AI assistants may:

  1. Identify candidate artifacts.
  2. Search official sources.
  3. Compare alternatives.
  4. Review documentation.
  5. Identify publisher, license, version, release status, maintenance status, security history, and verification material.
  6. Prepare a Supply Chain Evaluation Report.
  7. Draft Technology Decision Records.
  8. Draft Supply Chain Records.
  9. Draft Integration Records.
  10. Draft commands for operator review.
  11. Draft CI/CD changes after approval.
  12. Draft Dockerfiles, dependency files, configuration examples, validation commands, SBOM generation commands, and signing commands after approval.
  13. Recommend rejection when evidence is insufficient.

AI assistants shall not:

  1. Install software automatically.
  2. Run package-manager install commands without operator approval.
  3. Pull container images without operator approval when adoption is being evaluated.
  4. Add dependencies to project files without approval.
  5. Add external templates, actions, includes, or scripts to CI/CD configuration without approval.
  6. Copy code from external repositories into project files without approval and attribution review.
  7. Approve a package because it is popular.
  8. Approve an image because it is official.
  9. Approve an artifact because it works.
  10. Silently substitute an unverified artifact for a verified one.
  11. Treat generated code from an unverified source as trusted.
  12. Treat examples from documentation as safe production code without review.
  13. Treat previously approved versions as approval for future versions.
  14. Treat experimental approval as production approval.
  15. Treat dependency resolution success as a security decision.

4.3 No Silent Installation Rule

Before any external software is installed, added, pulled, downloaded, imported, vendored, mirrored, or integrated, the AI must present a verification report to the operator.

The report must state:

  1. The exact artifact name.
  2. The exact proposed version.
  3. The artifact category.
  4. The problem it solves.
  5. The current approved stack alternatives.
  6. The official source.
  7. The publisher.
  8. The repository or registry location.
  9. The verification evidence gathered.
  10. The signatures, digests, hashes, or provenance evidence available.
  11. The license.
  12. The maintenance status.
  13. Known security history.
  14. Known risks.
  15. The recommended action.
  16. The actions the AI cannot verify and that require operator judgment.
  17. The proposed decision status.
  18. The required records that would need to be created or updated before integration.

The AI must stop after presenting the report and wait for operator approval.

5. Artifact Necessity Standard

No external artifact may be adopted until the following question is answered in full:

What problem does this artifact solve that cannot already be solved using the currently approved stack?

The answer must be specific. It must not say merely that the artifact is popular, standard, modern, convenient, common, recommended, or easier.

The answer must identify:

  1. The concrete problem.
  2. The current approved tools that were considered.
  3. Why those approved tools are insufficient.
  4. Why the proposed artifact solves the problem.
  5. Why the benefit outweighs the supply-chain risk.
  6. Whether the artifact introduces a new class of operational risk.
  7. Whether the artifact duplicates an existing tool.
  8. Whether the artifact creates migration, licensing, compatibility, security, maintenance, or vendor-lock-in concerns.
  9. Whether the artifact can be removed later without damaging architecture.
  10. Whether the artifact becomes part of runtime, build, validation, development-only tooling, documentation, release, or deployment.

If the artifact does not solve a real problem that the current approved stack cannot reasonably solve, it must be rejected.

This rule exists to prevent tool creep. AI assistants must not add dependencies merely because a tutorial, documentation page, generated scaffold, framework default, or common pattern includes them.

6. Decision Status Model

Every evaluated artifact must receive one of the following decision statuses.

6.1 Approved

Approved means the operator has explicitly approved the artifact for the documented use case, version, source, repository, and integration method.

Approval does not extend to future versions, different repositories, different uses, different sources, plugins, forks, or transitive expansions unless the approval record states that scope explicitly.

6.2 Rejected

Rejected means the artifact shall not be used.

A rejection record should explain why the artifact was rejected. Reasons may include unverifiable source, weak maintenance, unacceptable license, unnecessary tool creep, known vulnerabilities, better existing approved alternative, inappropriate architecture fit, excessive complexity, untrusted publisher, or insufficient operator need.

Rejected artifacts should remain visible in records when useful so future AI sessions do not repeatedly recommend the same rejected option.

6.3 Deferred

Deferred means the artifact is not approved now, but may be reconsidered later after missing evidence, maturity, compatibility, project need, or operational capacity changes.

Deferred status is not approval. A deferred artifact shall not be installed, integrated, or used.

6.4 Experimental Only

Experimental Only means the operator approves a limited isolated test, but the artifact is not approved for production, staging, CI/CD automation, release artifacts, customer-facing behavior, or durable architecture.

Experimental-only approval must define:

  1. Repository or scratch location.
  2. Allowed files.
  3. Forbidden files.
  4. Network permissions.
  5. Secret access restrictions.
  6. Data restrictions.
  7. Time limit.
  8. Cleanup requirement.
  9. Whether findings may support a future Technology Decision Record.

Experimental success does not convert the artifact into an approved artifact. A full evaluation is still required before adoption.

6.5 Retired

Retired means an artifact was formerly approved but has been removed from active use. Retirement must preserve enough history for future recovery, incident review, or audit.

7. Artifact Evaluation Workflow

The artifact evaluation workflow determines whether an artifact may become part of the platform.

Evaluation must occur before integration.

7.1 Step 1: Identify the Need

The AI must describe the need in operational terms.

A valid need may include:

  1. A required runtime capability.
  2. A required build capability.
  3. A required validation capability.
  4. A required deployment capability.
  5. A required security capability.
  6. A required interoperability capability.
  7. A required documentation-mirroring capability.
  8. A required AI-agent capability.
  9. A required operator-workflow capability.

A vague preference is not a need.

7.2 Step 2: Check the Current Approved Stack

The AI must check whether the platform already has an approved tool or layer that solves the problem.

If an existing approved tool can solve the problem safely, the new artifact must not be adopted.

If the existing approved tool is inadequate, the AI must explain why.

7.3 Step 3: Identify Candidate Artifacts

The AI may identify candidate artifacts, but it must clearly label unverified candidates as unverified.

The AI must not recommend adoption until verification has been completed.

7.4 Step 4: Verify Official Source

The AI must identify the official upstream source and explain why it is official.

Acceptable evidence may include:

  1. Official project website.
  2. Official documentation.
  3. Official registry listing.
  4. Verified publisher status from a recognized registry.
  5. Official organization-owned remote repository.
  6. Official release announcements.
  7. Maintainer-controlled signing keys or release verification material.
  8. Cross-links from the official website to the package registry or repository.

If official source cannot be established, the artifact must not be adopted without an explicit operator exception.

7.5 Step 5: Verify Publisher and Repository Control

The AI must verify who controls the artifact source.

The AI must identify:

  1. Publisher name.
  2. Organization or maintainer.
  3. Repository location.
  4. Registry location.
  5. Whether the registry publisher matches the project publisher.
  6. Whether the repository appears to be the canonical source.
  7. Whether forks, mirrors, or third-party repackaging are involved.

Forks and mirrors must not be treated as official unless the operator explicitly approves them.

7.6 Step 6: Verify Maintenance Status

The AI must evaluate maintenance status.

The report must address:

  1. Recent releases.
  2. Recent commits or official release activity.
  3. Security update history.
  4. Open issue volume where relevant.
  5. Maintainer responsiveness where visible.
  6. Whether the project appears abandoned.
  7. Whether the proposed version is still supported.
  8. Whether the artifact has a clear support lifecycle.

An abandoned artifact must not be adopted unless the operator explicitly approves a documented exception.

7.7 Step 7: Select the Version

The AI must not select the newest version merely because it is newest.

The AI must identify the most stable, appropriate, production-suitable version for this platform.

The evaluation must consider:

  1. Stability.
  2. Support status.
  3. Compatibility with the current stack.
  4. Security fixes.
  5. Known regressions.
  6. Community or maintainer guidance.
  7. Whether the version is a long-term-support or stable release.
  8. Whether the version is too new for safe adoption.
  9. Whether the version is nearing end of life.
  10. Whether the version has known vulnerabilities.

Release candidates, beta builds, nightly builds, preview builds, edge builds, unstable builds, and rolling builds are prohibited unless the operator explicitly approves a temporary exception for an isolated experiment.

7.8 Step 8: Verify License

The AI must identify the artifact license before recommending adoption.

The AI must report:

  1. License name.
  2. Whether the license is permissive, copyleft, commercial, source-available, unknown, or mixed.
  3. Whether the license creates distribution obligations.
  4. Whether the license creates attribution obligations.
  5. Whether the license conflicts with the intended use.
  6. Whether bundled dependencies have separate licenses.

If license cannot be identified, the artifact must not be adopted.

7.9 Step 9: Verify Security History

The AI must evaluate known security history.

The report should identify:

  1. Known vulnerabilities.
  2. Recent security advisories.
  3. Patch cadence.
  4. Vulnerability response behavior.
  5. Whether the proposed version includes security fixes.
  6. Whether the artifact has unresolved high-risk issues.
  7. Whether the artifact is frequently targeted in supply-chain attacks.
  8. Whether there are known malicious packages with similar names.

7.10 Step 10: Verify Provenance, Signature, Digest, and Hash Evidence

The AI must identify every available verification method.

Depending on artifact type, this may include:

  1. Container image digest.
  2. Container image signature.
  3. Release checksum.
  4. Signed release file.
  5. Signed Git tag.
  6. Package hash.
  7. Lockfile hash.
  8. SBOM.
  9. SLSA provenance.
  10. Sigstore/Cosign verification.
  11. Registry verified publisher status.
  12. Official package index metadata.

If signatures or provenance are not available, the AI must state that plainly. Lack of signature does not automatically approve adoption. It creates a risk item requiring operator review.

7.11 Step 11: Compare Alternatives

The AI must compare reasonable alternatives.

The comparison must include:

  1. Current approved stack option.
  2. Official upstream option.
  3. Popular but unofficial options, if relevant, labeled as unapproved.
  4. Lower-dependency option.
  5. No-new-dependency option.
  6. Rejection option.

The AI must not create an artificial comparison that makes the preferred artifact look better by ignoring reasonable alternatives.

7.12 Step 12: Prepare the Recommendation

The recommendation must be explicit.

Allowed recommendation outcomes are:

  1. Approve for adoption.
  2. Reject.
  3. Defer pending more evidence.
  4. Approve only for isolated experiment.
  5. Approve only for local development.
  6. Approve only for non-production reference use.
  7. Approve for production integration.

The AI may recommend, but the operator decides.

8. Supply Chain Evaluation Report Template

Before asking the operator to approve an artifact, the AI shall prepare a Supply Chain Evaluation Report using the following structure.

Supply Chain Evaluation Report

Artifact:
Artifact category:
Requested by:
Repository affected:
Repository class:
Proposed decision status:
Proposed scope of approval:

Operational need:
Explain the concrete problem this artifact solves.

Current approved stack review:
Explain which approved tools or patterns were considered and why they do or do not solve the problem.

Candidate artifact:
Name the exact artifact, proposed version, and source.

Official source verification:
Identify the official website, official documentation, official registry, canonical repository, verified publisher, and cross-links proving authenticity.

Publisher and maintainer:
Identify who publishes and maintains the artifact.

Version selection:
Explain why this version is the most stable and appropriate version for the platform. State whether it is current stable, long-term support, older stable, or experimental.

Immutable reference:
Record digest, commit SHA, checksum, or other immutable identifier where applicable.

Signature and provenance:
State whether signatures, Cosign verification, signed tags, release checksums, SLSA provenance, or other verification methods are available.

License:
Identify the license and any operational obligations.

Maintenance status:
Summarize release activity, support status, maintainer activity, and abandonment risk.

Security history:
Summarize known vulnerabilities, advisories, malicious-package confusion risk, and relevant security concerns.

Compatibility:
Explain compatibility with the current repository, operating systems, Python version, container base, CI/CD runner, runtime environment, and future Linux VPS deployment where relevant.

Alternatives evaluated:
Compare approved-stack option, no-new-dependency option, official alternatives, and rejected alternatives.

Risks:
List known risks in full sentences.

Mitigations:
List required controls such as digest pinning, Cosign signing, SBOM generation, non-root runtime, lockfile hashes, sandboxing, permission limits, or isolated experimentation.

Required records:
Identify Technology Decision Record, Supply Chain Record, Integration Record, Repository Classification Record, release history, and SBOM changes required.

Recommended decision:
Approved, rejected, deferred, or experimental only.

AI confidence:
State what the AI could verify and what the AI could not verify.

Operator decision:
Reserved for operator approval, rejection, deferral, or experimental-only approval.

This report must be written before installation or integration. The report may be committed as part of a state record after operator approval, or it may be summarized into the Supply Chain Record, Technology Decision Record, and Integration Record.

9. Required Supply Chain Records

Every approved artifact must have a Supply Chain Record.

Supply Chain Records belong under the repository's state directory:

state/supply_chain/artifacts/

When a repository does not yet have a state directory and the repository class requires one, the implementation task must create the appropriate state structure after operator approval.

The Supply Chain Record must be written in full explanatory sentences. It may include structured tables, but it must not rely on unexplained shorthand.

9.1 Required Supply Chain Record Fields

Each Supply Chain Record must include:

Artifact name:
Artifact category:
Repository class affected:
Repository path:
Purpose:
Problem solved:
Current approved version:
Version selection rationale:
Approved source:
Publisher:
Official website:
Canonical repository:
Registry or download location:
Immutable reference:
Digest or checksum:
Signature status:
Provenance evidence:
SBOM availability:
License:
Maintenance status:
Security history:
Known risks:
Approved use:
Forbidden use:
Integration locations:
Operational owner:
Date approved:
Approved by:
Review interval:
Next review date:
Replacement candidates:
Retirement procedure:
Related Technology Decision Record:
Related Integration Record:
Related commits:
Related release records:
Decision status:

9.2 Record Location

A typical deployable repository should store records in this shape:

state/
    supply_chain/
        README.md
        inventory.md
        artifacts/
            python.md
            uv.md
            docker.md
            ruff.md
            sqlalchemy-core.md
        sbom/
            release-YYYY-MM-DD.spdx.json

The exact file names should be stable, lowercase, descriptive, and vendor-neutral when possible. The file name should identify the artifact clearly enough for future AI sessions and operations database ingestion.

9.3 Inventory File

Each repository with supply-chain records shall maintain an inventory file:

state/supply_chain/inventory.md

The inventory file shall list approved artifacts, current approved versions, review dates, decision status, and record paths.

The inventory is not a substitute for individual Supply Chain Records. It is an index.

10. Sample Supply Chain Record

The following sample illustrates the expected depth and structure. It is an example only and does not approve the named artifact.

# Supply Chain Record – Example Container Base Image

Artifact name: Official Python runtime container image.

Artifact category: Container base image.

Repository class affected: Class A deployable application repository.

Repository path: <workspace-root>/app.

Purpose: This artifact provides the base Python runtime environment for the application container image.

Problem solved: The application needs a consistent Linux-based Python runtime that can be built and run on different host operating systems while preparing the platform for Linux VPS deployment.

Current approved version: Python 3.12 Debian slim image, exact version and digest to be filled after operator approval.

Version selection rationale: The Debian slim family provides a smaller runtime surface than a full distribution image while preserving broad Python package compatibility. Alpine is not selected by default because musl-based images can create compatibility and build issues for Python packages that expect glibc.

Approved source: Official Python container image source.

Publisher: Official Python image publisher.

Official website: Official Python project and official container image documentation.

Canonical repository: Official upstream source and official container image publishing location.

Registry or download location: Approved container registry path after verification.

Immutable reference: Exact sha256 digest required before production use.

Digest or checksum: Required before production use.

Signature status: Required to be verified where upstream signing exists. Platform-produced production images shall be signed using Cosign.

Provenance evidence: Official publisher evidence and registry metadata required.

SBOM availability: Platform release SBOM required for production release.

License: Python license and base image component licenses to be reviewed.

Maintenance status: Must be reviewed before approval. The selected version must be stable and supported.

Security history: Known vulnerabilities must be checked before approval and during periodic review.

Known risks: Base image tags are mutable. Production builds must use digest pinning. Containers must not run as root. Secrets must not be baked into images.

Approved use: Approved only as a production container base image after digest verification and operator approval.

Forbidden use: Floating tags, unverified mirrors, community repackages, and unsigned production runtime images are forbidden.

Integration locations: Dockerfile, container build pipeline, CI/CD image build job, release process, SBOM generation process, Cosign signing process.

Operational owner: Human operator.

Date approved: To be filled by operator.

Approved by: Human operator.

Review interval: Before every production image refresh and at least during scheduled supply-chain review.

Next review date: To be filled.

Replacement candidates: Other official Python slim images or approved hardened base images after separate evaluation.

Retirement procedure: Replace the base image through a controlled digest update, rebuild, scan, sign, validate, update SBOM, update this record, and commit the change with a supply-chain impact statement.

Related Technology Decision Record: state/technology_decisions/containerization.md

Related Integration Record: state/integration_records/docker-runtime.md

Related commits: To be added after implementation.

Related release records: To be added when released.

Decision status: Candidate until operator approval.

11. Technology Decision Records

A Technology Decision Record answers why a technology was selected.

It is different from a Supply Chain Record.

A Technology Decision Record answers:

Should this technology be part of the architecture?

A Supply Chain Record answers:

Can we trust this specific artifact and version?

An Integration Record answers:

How is this approved artifact used in this specific repository?

Before an external artifact becomes part of the platform, these three questions must be answered when applicable.

Technology Decision Records belong under:

state/technology_decisions/

11.1 Technology Decision Record Template

# Technology Decision Record – <Technology Name>

Status: Proposed, approved, rejected, deferred, experimental only, superseded, or retired.

Decision date:

Repository or platform scope:

Decision owner:

Problem:
Explain the concrete problem being solved.

Decision:
State the selected technology or rejected technology.

Current approved stack review:
Explain why existing approved tools do or do not solve the problem.

Alternatives considered:
List meaningful alternatives and the no-new-dependency option.

Why selected:
Explain why this technology is the correct architectural choice.

Why alternatives were not selected:
Explain why each major alternative was rejected or deferred.

Security considerations:
Explain supply-chain, runtime, permission, data, secret, and operational security concerns.

Portability considerations:
Explain operating-system, container, CI/CD, deployment, and future migration effects.

Operational considerations:
Explain maintenance, validation, observability, support, backup, recovery, and staffing effects.

Exit strategy:
Explain how the platform can remove or replace the technology later.

Related Supply Chain Records:

Related Integration Records:

Related commits:

Review interval:

Next review date:

11.2 Sample Technology Decision Record

# Technology Decision Record – Containerization

Status: Proposed pending operator approval.

Decision date: To be filled.

Repository or platform scope: Class A deployable repositories and future production deployment.

Decision owner: Human operator.

Problem:
The platform is developed across multiple host operating systems and is intended to run production services on a Linux VPS. The application needs a consistent runtime environment so development, validation, staging, and production do not require multiple OS-specific versions of the same project.

Decision:
Adopt Linux containers as the standard production packaging and runtime portability layer for deployable repositories.

Current approved stack review:
Relative paths, operating-system-neutral documentation, and the Python project manager improve portability, but they do not fully standardize the runtime operating-system environment, system packages, container image build path, or production deployment shape.

Alternatives considered:
Use host-specific setup only; use virtual machines; use direct Linux VPS deployment without containers; use a different container runtime; defer containerization.

Why selected:
Containers provide a repeatable Linux runtime that can run on Windows, macOS, and Linux hosts while preparing the project for a Linux VPS. They also give the project a path toward signed images, SBOMs, runtime isolation, and future orchestration.

Why alternatives were not selected:
Host-specific setup would preserve OS drift. Virtual machines are heavier. Direct VPS deployment is simpler initially but does not create the same reproducible artifact. Deferral would push portability problems later into the production-readiness phase.

Security considerations:
Container images become supply-chain artifacts. Base images require official-source verification, digest pinning, vulnerability scanning, SBOM generation, non-root runtime configuration, no embedded secrets, and Cosign signing for production images.

Portability considerations:
The container runtime should use Linux containers. The preferred Python base should be Debian slim unless a later record approves a different base.

Operational considerations:
Containerization requires Dockerfile maintenance, image builds, CI/CD support, release records, health checks, resource expectations, signing, and SBOMs.

Exit strategy:
The application should remain runnable through approved Python project commands so the runtime can be moved away from Docker if necessary.

Related Supply Chain Records:
state/supply_chain/artifacts/docker.md
state/supply_chain/artifacts/python-container-base.md

Related Integration Records:
state/integration_records/docker-runtime.md

Related commits:
To be filled after implementation.

Review interval:
Review before production container release and during scheduled architecture review.

Next review date:
To be filled.

12. Integration Records

An Integration Record documents how an approved artifact is actually used in a repository.

Integration Records belong under:

state/integration_records/

Integration Records must exist when an artifact is integrated into:

  1. Runtime code.
  2. Build process.
  3. CI/CD pipeline.
  4. Container build.
  5. Deployment process.
  6. Local development workflow.
  7. Server provisioning.
  8. Scheduled jobs.
  9. Monitoring or observability.
  10. AI-agent workflow.
  11. Context/reference mirror update process.
  12. Release process.

12.1 Integration Record Template

# Integration Record – <Artifact or Capability>

Status:

Repository:

Repository class:

Integrated artifact:

Approved version:

Related Technology Decision Record:

Related Supply Chain Record:

Purpose:
Explain what this integration does in this repository.

Files affected:
List files and explain the role of each file.

Configuration affected:
List configuration keys, environment variables, templates, protected variables, secret references, and runtime settings.

Commands introduced:
List new commands and explain when they are used.

Build behavior:
Explain build effects.

Runtime behavior:
Explain runtime effects.

CI/CD behavior:
Explain pipeline effects.

Security controls:
List controls such as non-root runtime, digest pinning, signature verification, lockfile hashes, protected variables, no-secret policy, sandboxing, or permission limits.

Validation:
List local validation and remote validation required.

Failure modes:
Explain how this integration can fail.

Rollback:
Explain how to safely remove or revert the integration.

Operations database impact:
Explain whether future ingestion is required.

Review interval:

Related commits:

12.2 Sample Integration Record

# Integration Record – Docker Runtime Packaging

Status: Proposed pending implementation.

Repository: <workspace-root>/app.

Repository class: Class A deployable application repository.

Integrated artifact: Docker container runtime and approved Python base image.

Approved version: To be filled after operator approval.

Related Technology Decision Record:
state/technology_decisions/containerization.md

Related Supply Chain Record:
state/supply_chain/artifacts/docker.md
state/supply_chain/artifacts/python-container-base.md

Purpose:
This integration packages the application runtime into a Linux container so the same runtime shape can be used from Windows, macOS, Linux development hosts, staging, and future Linux VPS production deployment.

Files affected:
Dockerfile defines the application image.
.dockerignore excludes local files, secrets, caches, virtual environments, logs, temporary files, and local databases.
compose configuration defines local runtime wiring after approval.
CI/CD configuration builds and validates the image after pipeline adoption.

Configuration affected:
Runtime configuration must come from approved environment variables, protected variables, or runtime secret mechanisms. Secrets must not be baked into the image.

Commands introduced:
docker build or docker buildx build commands after approval.
docker compose commands after approval.
SBOM generation commands.
Cosign signing and verification commands.

Build behavior:
Dependency layers must be separated from frequently changed source-code layers. Production runtime image must not retain build-only dependencies unless justified.

Runtime behavior:
The container must run as a non-root user and expose only approved ports. Health checks must test real application health.

CI/CD behavior:
Pipeline jobs may build, scan, generate SBOM, sign, and validate the image. Production deployment requires manual approval gates unless a later deployment standard changes that rule.

Security controls:
Official source verification, digest pinning, non-root runtime, no secrets in image, vulnerability scan, SBOM generation, Cosign signing, and signature verification.

Validation:
Local build validation, application smoke test, health check test, image scan, SBOM generation, Cosign sign/verify, CI/CD build job, and deployment dry-run where applicable.

Failure modes:
Build cache invalidation, dependency install failure, base image vulnerability, health check false positives, missing environment variables, secret exposure, signature verification failure, registry access failure.

Rollback:
Revert Docker integration files or restore previous image digest through a controlled commit, rebuild, rescan, regenerate SBOM, resign, and validate.

Operations database impact:
Future ingestion should index image digest, SBOM metadata, signature status, release date, and deployment status.

Review interval:
Before production image release and during scheduled supply-chain review.

Related commits:
To be filled after implementation.

13. Container Image Requirements

Container images are high-risk supply-chain artifacts because a base image is the first dependency in every container build.

13.1 Base Image Rule

Container base images must come from official, authenticated, verified upstream publishers or explicitly approved trusted registries.

The preferred Python container base for the current backend direction is a Debian slim Python image or an approved Python/uv image based on Debian slim. Alpine-based images may be considered only after compatibility and security review. Raw general-purpose distribution images may be used only when the application requires them.

The project shall avoid bloated base images unless there is a documented reason.

13.2 Immutable Digest Pinning

Production container images shall be pinned by digest.

A tag alone is not sufficient because tags are mutable. A tag may point to different content over time.

A production Dockerfile or build definition shall not rely only on:

python:3.12-slim

It shall record the exact digest used for the approved base image.

13.3 Cosign Signing Requirement

Every production container image produced by the platform shall be cryptographically signed using Cosign before publication or deployment.

A production deployment shall verify the image signature before use when the deployment path supports verification.

If Cosign signing or verification is not yet technically implemented, the repository shall not treat production container release automation as complete. The missing signing path must be recorded as a blocking production-readiness item, not as optional cleanup.

13.4 Keyless Cosign Signing

Keyless signing may be appropriate when the platform's CI/CD identity, repository identity, and operator workflow can support identity-based signing and verification.

When keyless signing is used, the Integration Record must document:

  1. Signing identity.
  2. Identity provider.
  3. Certificate issuer.
  4. Transparency log behavior.
  5. Verification command.
  6. CI/CD job or release step that performs signing.
  7. Who is authorized to trigger signing.
  8. How unauthorized signing is prevented.
  9. How the project verifies that the image was signed by the expected identity.

Keyless signing does not remove the need for digest pinning, SBOM generation, vulnerability scanning, release records, or operator approval.

13.5 Key-Based Cosign Signing

Key-based signing may be appropriate when the operator wants direct control over signing keys.

When key-based signing is used, the Integration Record must document:

  1. Key generation method.
  2. Private-key storage location.
  3. Public-key storage location.
  4. Backup process.
  5. Rotation process.
  6. Revocation process.
  7. Access control.
  8. Passphrase handling.
  9. CI/CD access rules.
  10. Recovery procedure if the key is lost or compromised.

Private signing keys must not be committed to any repository. Private signing keys must not be placed in container images. Private signing keys must not be exposed to untrusted AI tools.

13.6 Signing Mode Decision

The project must choose a signing mode before production image release.

The Technology Decision Record for container signing must explain whether keyless signing or key-based signing is selected and why. The decision must consider simplicity, operator burden, CI/CD compatibility, key custody, recovery, auditability, and long-term maintainability.

13.7 Non-Root Runtime

Production containers shall run as a non-root user unless a documented technical reason requires root.

If root is required, the reason must be recorded in the Integration Record, and compensating controls must be documented.

13.8 Layer Order and Build Cache

Dockerfiles must order layers so that low-change inputs are copied before high-change application code.

Dependency files, lockfiles, and project metadata should be copied before application source code. Dependency installation should occur before copying frequently changed source files when practical.

This rule exists to preserve build-cache efficiency and avoid rebuilds that reinstall dependencies merely because application code changed.

13.9 Multi-Stage Builds

Production container builds should use multi-stage builds where this reduces attack surface, image size, or build-tool exposure.

Build tools, compilers, package-manager caches, test artifacts, temporary files, and development-only dependencies should not remain in production runtime images unless explicitly required.

13.10 Health Checks

Container health checks must test real application health.

A health check that only proves the process exists is insufficient.

For API services, health checks should validate the application's ability to respond correctly and, where appropriate, check database connectivity, queue availability, storage access, configuration state, or other critical dependencies. Health checks must not mutate production state.

13.11 Resource Limits

Containerized services should define reasonable resource expectations. Future orchestrators should use these expectations to prevent runaway behavior.

13.12 .dockerignore

Every repository with a Docker build shall include a .dockerignore file that excludes unnecessary local files, secrets, caches, virtual environments, logs, test outputs, Git metadata where appropriate, temporary files, and local databases.

13.13 No Secrets in Images

Secrets shall not be baked into container images.

Secrets must be injected through approved runtime secret mechanisms, environment variables, protected CI/CD variables, secret stores, or operator-approved deployment configuration.

13.14 Explicit Docker Example

When evaluating a Docker base image, the AI must not say only:

Use python:3.12-slim.

The AI must evaluate and record:

  1. Why a container is needed.
  2. Why a Linux container is appropriate.
  3. Why Debian slim is preferred.
  4. Why Alpine is not the default.
  5. Which exact image version is selected.
  6. Which exact digest is selected.
  7. Whether upstream signatures are available.
  8. Whether the platform-produced image will be signed using Cosign.
  9. Whether the runtime user is non-root.
  10. Whether a real health check exists.
  11. Whether a .dockerignore exists.
  12. Whether an SBOM will be generated.
  13. Whether the image is scanned.
  14. Whether the CI/CD pipeline validates the image.
  15. Whether release records will capture image digest, SBOM path, and signature status.

14. Python Package Requirements

Python packages must be added only through the approved Python project manager and project metadata workflow after approval.

Python package adoption must identify:

  1. Official package index location.
  2. Canonical source repository.
  3. Publisher or maintainer.
  4. License.
  5. Version.
  6. Hash or lockfile record where supported.
  7. Dependency tree impact.
  8. Security history.
  9. Compatibility with the approved Python version.
  10. Whether the package is runtime or development-only.
  11. Whether the package is needed in production or only for local validation.
  12. Whether the package introduces compiled dependencies or operating-system packages.
  13. Whether the package affects container build time or runtime image size.

The AI must not add a package merely because an example import fails. It must first determine whether the package is already intended, whether the project has adopted the dependency, whether the import should be removed, or whether an existing approved tool already provides the needed functionality.

14.1 Explicit Python Package Example

When evaluating a Python package, the AI must prepare a report such as:

Artifact:
Ruff.

Need:
The project needs a Python linting and formatting layer so AI-generated and human-written code follow a consistent quality standard.

Current approved stack review:
No existing approved tool currently provides the selected linting and formatting layer for Python.

Official source verification:
Identify official project site, package index entry, canonical repository, publisher, and documentation.

Version selection:
Identify the stable version appropriate for the repository rather than selecting newest blindly.

Supply-chain controls:
Add through the approved Python project manager, record lockfile changes, document whether it is development-only, and update CI/CD validation where applicable.

Decision:
Recommend approval only after operator review.

This example is illustrative. It does not approve Ruff or any specific version by itself.

15. Remote Git Repository Requirements

Remote Git repositories are supply-chain artifacts when they are used as dependencies, copied from, mirrored, vendored, templated, or used as source material.

The project may use different remote Git hosting services over time. Examples include GitLab, GitHub, Codeberg, self-hosted Git services, and other providers. Durable documentation should use generic terms such as remote Git host, source repository, canonical repository, or upstream repository unless the specific provider matters.

The AI must distinguish between:

  1. The platform's own repositories.
  2. Official upstream repositories.
  3. Forks.
  4. Mirrors.
  5. Example repositories.
  6. Personal repositories.
  7. Archived repositories.
  8. Generated scaffolds.

A Git branch is not a trusted version reference for third-party adoption. Branches move. A Git commit SHA is an immutable reference. A signed release or signed tag may provide additional evidence, but tags can be moved unless protected and verified.

When copying or basing work on external repository material, the AI must identify the source, license, commit, and purpose. It must not copy substantial code from external repositories without operator approval.

15.1 Explicit Remote Git Repository Example

If an AI wants to use source from a public repository, it must not say:

This GitHub repo looks good.

It must say:

This is an external remote Git repository. It is not approved. I identified the official upstream source, license, maintainer, release status, commit SHA, and security history. The repository is a candidate only. No code should be copied or installed until the operator approves the evaluation report.

The same rule applies to GitLab, Codeberg, self-hosted Git services, vendor-hosted repositories, mirrors, forks, and personal repositories.

16. CI/CD Component Requirements

CI/CD configuration can execute commands, consume secrets, publish artifacts, deploy services, modify infrastructure, run database migrations, or mutate environments.

External CI/CD components must be treated as high-risk artifacts.

This includes:

  1. Reusable workflows.
  2. Pipeline templates.
  3. CI/CD includes.
  4. Container images used by jobs.
  5. Third-party actions.
  6. Runner images.
  7. Scripts downloaded during jobs.
  8. Deployment helpers.
  9. Build-cache tools.
  10. Security scanning tools.

A CI/CD component must not be added unless it has passed supply-chain review and has an Integration Record.

Pipeline configuration shall not download and execute remote scripts without explicit approval and verification.

17. IDE, Editor, and Local Tool Requirements

IDEs, editor extensions, language servers, formatters, linters, local CLI tools, browser extensions, and local development helpers can read and modify source code. They are supply-chain artifacts.

The AI must not recommend installing an IDE extension or local development tool without evaluation.

The report must identify:

  1. Official marketplace or download source.
  2. Publisher.
  3. Permissions or capabilities.
  4. Maintenance status.
  5. License.
  6. Why the tool is needed.
  7. Whether an existing approved tool already solves the need.

18. AI Model, AI Tool, and MCP Server Requirements

AI models, AI SDKs, MCP servers, agent tools, and model-serving containers are supply-chain artifacts.

The AI must evaluate:

  1. Source.
  2. Publisher.
  3. Model license.
  4. Model weights source.
  5. Container image source if applicable.
  6. Security implications.
  7. Data exposure.
  8. Local execution requirements.
  9. Network behavior.
  10. Prompt or tool permissions.
  11. Whether the tool can read files, write files, execute commands, access secrets, access browsers, access remote services, or mutate repositories.
  12. Whether the tool can exfiltrate content.
  13. Whether the tool can access customer data, operational data, logs, tokens, or private project files.
  14. Whether the tool runs locally, remotely, or through a third-party service.
  15. Whether the tool stores or trains on project data.

An MCP server must not be installed or run merely because it is packaged as a container. It must be evaluated as a privileged tool interface.

18.1 Explicit AI Model Example

If the AI proposes a local model, it must evaluate:

  1. Model publisher.
  2. Model license.
  3. Model weights source.
  4. Model file hash or registry digest.
  5. Runtime container image if applicable.
  6. Hardware requirements.
  7. Data exposure.
  8. Quality suitability.
  9. Whether the model is needed when approved API providers already exist.
  10. Whether it is experimental-only or production-approved.

18.2 Explicit MCP Server Example

If the AI proposes an MCP server, it must evaluate:

  1. What tools the MCP server exposes.
  2. Whether it can read files.
  3. Whether it can write files.
  4. Whether it can execute commands.
  5. Whether it can access remote services.
  6. Whether it can access secrets.
  7. Whether it is packaged as a container.
  8. Whether the container image is official and verified.
  9. Whether the MCP server is necessary.
  10. Whether it should be isolated.
  11. Whether it should be experimental-only.

19. Infrastructure Module Requirements

Infrastructure modules, orchestration files, deployment templates, Kubernetes manifests, Helm charts, Terraform/OpenTofu modules, Ansible roles, service-unit templates, and server bootstrap scripts are high-impact supply-chain artifacts when copied from or based on external sources.

The AI must not copy infrastructure examples into the platform without review.

Infrastructure material must be evaluated for:

  1. Source.
  2. License.
  3. Version.
  4. Provider assumptions.
  5. Security defaults.
  6. Secret handling.
  7. Network exposure.
  8. Production mutation.
  9. Rollback path.
  10. Compatibility with current and future operating environments.
  11. Whether the material is example code or production-ready code.

20. Context Repository Requirements

Context repositories exist to provide local reference material for humans, ChatGPT sessions, Codex sessions, and future AI agents. They are not runtime dependencies, but they can influence runtime work because AI agents may read them and act on their content.

Context repositories must document:

  1. Official source URLs.
  2. Source selection criteria.
  3. Update method.
  4. Update date.
  5. License or usage status where available.
  6. Whether content is official documentation, examples, API schemas, SDK references, community material, release notes, or local commentary.
  7. What content is intentionally excluded.
  8. Whether generated files are safe to rely on.
  9. Whether the repository is read-only reference material.

Context repositories should not contain deployment jobs unless their class changes.

21. SBOM Policy

Every production release shall generate an SBOM.

SBOM files shall be stored under:

state/supply_chain/sbom/

SBOMs shall not be overwritten. Each release shall have its own SBOM file.

21.1 Accepted SBOM Formats

The project may use SPDX, CycloneDX, or both.

SPDX is suitable where license and component inventory compatibility matters. CycloneDX is suitable where security tooling, dependency relationships, and vulnerability management workflows benefit from its structure.

The selected SBOM format for a repository must be recorded in the relevant Integration Record.

If the repository produces container images and application packages, the SBOM strategy should define whether the SBOM covers:

  1. Application dependencies.
  2. Container image components.
  3. Operating-system packages.
  4. Build-time dependencies.
  5. Runtime-only dependencies.
  6. Development-only dependencies.
  7. Transitive dependencies.

21.2 SBOM Naming

Recommended naming pattern:

release-YYYY-MM-DD.spdx.json
release-YYYY-MM-DD.cyclonedx.json

When release identifiers exist, the release identifier should be included:

release-v1.2.0-YYYY-MM-DD.spdx.json
release-v1.2.0-YYYY-MM-DD.cyclonedx.json

21.3 SBOM Requirements

The SBOM must be treated as a release artifact. It should be committed or archived according to the repository's release-history standard.

The SBOM helps future operators and AI workers answer:

  1. What shipped?
  2. Which versions shipped?
  3. Which licenses shipped?
  4. Which dependencies were present?
  5. Which component is affected by a later vulnerability?
  6. Which releases need remediation?

21.4 SBOM and Operations Database

A future operations database integration should ingest SBOM metadata, not replace SBOM files.

The repository SBOM files remain durable release records. The database can index components, versions, vulnerabilities, review dates, and affected releases.

22. Periodic Review Policy

Approved artifacts shall be reviewed periodically.

The review interval must be recorded in each Supply Chain Record.

Periodic review should check:

  1. Whether the artifact is still maintained.
  2. Whether the approved version is still supported.
  3. Whether security advisories have appeared.
  4. Whether the artifact has been abandoned.
  5. Whether a better approved-stack alternative now exists.
  6. Whether the artifact remains necessary.
  7. Whether license terms changed.
  8. Whether publisher control changed.
  9. Whether signing keys or verification methods changed.
  10. Whether the artifact should be upgraded, replaced, or retired.
  11. Whether the artifact's Integration Record still matches the repository.
  12. Whether the artifact still matches the repository class and deployment model.

Periodic review may be implemented later through operations database jobs or AI worker routines. Until then, the review schedule must still be documented.

23. Artifact Retirement Policy

Artifacts must be retired deliberately.

An artifact should be retired when:

  1. It is no longer needed.
  2. It duplicates another approved tool.
  3. It is abandoned.
  4. It has unacceptable vulnerabilities.
  5. Its license becomes unacceptable.
  6. It creates more operational cost than value.
  7. A safer approved alternative exists.
  8. The related platform feature is removed.
  9. The repository class changes and no longer requires it.

Retirement must update:

  1. Dependency files.
  2. Container build files.
  3. CI/CD configuration.
  4. Documentation.
  5. Technology Decision Record.
  6. Supply Chain Record.
  7. Integration Record.
  8. Release history when relevant.
  9. Operations database copy when that integration exists.
  10. SBOM strategy when relevant.

24. Supply Chain Impact Review During Git Checkpoints

Every Git checkpoint shall include a Supply Chain Impact Review.

The AI must ask:

  1. Did this change introduce a new external artifact?
  2. Did this change remove an external artifact?
  3. Did this change upgrade, downgrade, or replace an artifact?
  4. Did this change alter a container image, base image, runtime image, build image, digest, tag, or registry?
  5. Did this change alter Python dependencies, lockfiles, package metadata, or project manager behavior?
  6. Did this change alter frontend dependencies or build tooling?
  7. Did this change alter CI/CD components, runner images, job templates, includes, actions, scripts, or deployment helpers?
  8. Did this change alter an IDE, local tool, CLI tool, or development setup dependency?
  9. Did this change alter an AI model, AI SDK, MCP server, or AI-agent tool?
  10. Did this change alter mirrored reference sources in a context repository?
  11. Did this change require an SBOM update?
  12. Did this change require a Cosign signature or verification update?
  13. Did this change require a Technology Decision Record update?
  14. Did this change require a Supply Chain Record update?
  15. Did this change require an Integration Record update?
  16. Did this change reveal a weakness, ambiguity, missing safeguard, or repetitive manual step in supply-chain governance?
  17. Can any discovered issue be fixed now before commit?

The review is not merely informational. If the review identifies a record that can be updated safely within scope, the AI must update it before commit readiness. If the review identifies an issue that requires operator approval or a separate task, the AI must record it as a structured follow-up.

25. Commit Message Requirements

When a commit affects supply-chain matters, the commit message must include a supply-chain impact section.

The section must explain:

  1. Whether external artifacts were introduced, changed, removed, rejected, or deferred.
  2. Which records were created or updated.
  3. Which records were reviewed but did not need changes.
  4. Whether SBOM generation was required.
  5. Whether Cosign signing was required.
  6. Whether container digests changed.
  7. Whether dependency lockfiles changed.
  8. Whether any supply-chain risk remains.
  9. Whether operator approval occurred.
  10. Whether any follow-up task was generated.

The commit message must also include the workflow-improvement subsection required by the Git Commit Message Standard:

Workflow weakness, ambiguity, missing safeguard, or repetitive manual step discovered:

If the supply-chain review revealed a weakness in the standard, the AI must determine whether the weakness can be fixed before commit. If it can be fixed within scope, it should be fixed before commit. If not, it must be recorded as a structured follow-up.

26. Operations Database Integration

The repository state files are the initial authoritative working record for supply-chain governance.

The future operations database may ingest these records and provide query, alerting, review, and AI-worker coordination. The database should be treated as an operational index and workflow surface unless a later standard explicitly changes the source-of-truth model.

The repository remains critical because Git provides review history, diffs, branching, recovery, and merge records. If the database must be rebuilt, the repository records should be able to reconstruct the approved artifact inventory.

A future database integration task should define:

  1. Schema for artifacts.
  2. Schema for technology decisions.
  3. Schema for integration records.
  4. Schema for SBOM metadata.
  5. Ingestion workflow.
  6. Reconciliation workflow.
  7. Conflict resolution.
  8. AI worker tasks.
  9. Review reminders.
  10. Security alert handling.
  11. Release-to-SBOM mapping.
  12. Artifact-to-commit mapping.
  13. Artifact review queue.
  14. Vulnerability alert queue.
  15. Retired artifact tracking.

27. Prohibited Conduct

The following actions are prohibited unless the operator explicitly approves a documented exception:

  1. Installing software automatically.
  2. Adding a package because an example requires it.
  3. Pulling an unverified container image.
  4. Using latest in production.
  5. Using mutable branch references for third-party dependencies.
  6. Using unsigned or unverified production container images when signing is required.
  7. Copying code from an external repository without source and license review.
  8. Adding CI/CD external components without review.
  9. Adding MCP servers without security review.
  10. Adding AI models without license, source, and data-exposure review.
  11. Treating official status as sufficient.
  12. Treating popularity as sufficient.
  13. Treating successful local execution as approval.
  14. Treating a previous approval as approval for a new version.
  15. Treating experimental approval as production approval.
  16. Hiding an unresolved supply-chain concern in vague commit-message language.
  17. Deferring an immediately fixable supply-chain issue until after commit.
  18. Allowing a temporary exception to become permanent architecture.
  19. Downloading and executing remote scripts during CI/CD without review.
  20. Baking secrets into images.
  21. Allowing container health checks that only prove process existence.
  22. Allowing root runtime in production containers without documented exception.
  23. Allowing unreviewed package-manager changes into dependency files.
  24. Allowing context repositories to mirror unofficial documentation without labeling it as unofficial.
  25. Allowing AI tools with file, command, browser, or remote-service access without supply-chain review.

28. Exception Process

Exceptions are allowed only when explicitly approved by the operator.

An exception must document:

  1. Rule being waived.
  2. Artifact affected.
  3. Reason for exception.
  4. Risk accepted.
  5. Duration.
  6. Compensating controls.
  7. Required follow-up.
  8. Review date.
  9. Exit plan.
  10. Whether the exception is local-only, experimental-only, staging-only, or production-affecting.

Temporary exceptions must be tracked as follow-up work.

No exception may be treated as a permanent standard unless a later standards revision explicitly adopts it.

29. Required AI Behavior Summary

When supply-chain questions arise, the AI must act as an investigator, not an authority.

The AI must gather evidence, report uncertainty, recommend rejection when evidence is weak, and stop before adoption.

The AI must preserve security boundaries even when the operator asks for speed. The AI must not use loose language as permission to bypass verification. The AI must not treat supply-chain work as a routine dependency update. Every artifact is a trust decision.

The AI must use direct, full-sentence records that can be understood by future humans, future ChatGPT sessions, Codex sessions, automation workers, operations database ingestion, and AI-agent repair workflows.

30. Relationship to Other Standards

This standard interacts with other project standards as follows:

  1. The Repository Classification Standard determines which repositories require which supply-chain records.
  2. The Git Checkpoint Standard requires Supply Chain Impact Review before commit readiness.
  3. The Git Commit Message Standard must record supply-chain impact when applicable.
  4. The CI/CD Pipeline Standard must treat pipeline components as supply-chain artifacts.
  5. The Runtime Validation Standard must validate changed behavior after approved integration.
  6. The Patch/Codex Workflow Standard must prohibit Codex from introducing unapproved artifacts.
  7. The Architecture Standards must treat external artifacts as architectural decisions, not casual implementation details.
  8. The Technology Stack Guide must distinguish selected tools from approved artifact versions.
  9. The Python Backend Restructuring Standard must ensure Python package changes follow this standard.
  10. Future Docker, Kubernetes, deployment, and release standards must inherit this supply-chain policy.

31. Final Rule

No external artifact enters the platform by accident.

An artifact enters the platform only when it is necessary, verified, approved, documented, integrated deliberately, validated, recorded, reviewable, and removable.

A future AI agent must be able to inspect the repository state records and understand not only what artifact was used, but why it was selected, how it was verified, how it was integrated, how it can be reviewed, and how it can be removed.