Daily Routine / AI Training

03 - Repository Classification Standard Draft

Mandatory internal standard for classifying platform repositories, assigning repository-specific governance requirements, determining required state directories, supply-chain records, technology decision records, integration records, validation depth, CI/CD expectations, release records, reclassification controls, and AI-session obligations across deployable, shared, context, utility, infrastructure, experimental, archived, and future repository classes.

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

Document Scope

This document defines the repository classification standard for the modular workspace. It explains how each repository should be classified, which standards apply to each class, which state records are required, which validation expectations apply, which CI/CD expectations apply, which supply-chain controls apply, and how AI-assisted sessions must reason about repository class before making changes.

The platform is not a monorepo. It is a multi-repository system. Each repository has a distinct role, lifecycle, risk profile, validation requirement, and operational effect. A repository that runs the application does not need the same governance as a context repository that mirrors vendor documentation. A repository that contains deployment infrastructure does not need the same rules as a personal utility repository. A future shared library repository will have different release concerns than a public site repository.

This document is written for human operators, ChatGPT sessions, Codex sessions, AI-assisted development tools, automation workers, future AI agents, future MCP/RAG workflows, and maintainers who need to understand what type of repository they are working in before editing files, creating branches, writing prompts, running validation, updating CI/CD, drafting commit messages, preparing release artifacts, or recording governance state.

This standard does not list every repository that will ever exist. Repository classes are reusable templates. The current repositories are examples only. Additional repositories of every class are expected over the life of the platform.

This document does not replace the Workspace Structure Guide, Runtime Validation Standard, Git Checkpoint Standard, Git Commit Message Standard, Patch/Codex Workflow Standard, CI/CD Pipeline Standard, Supply Chain Security Standard, Architecture Standards, Technology Stack Guide, Python Backend Restructuring Standard, or task-specific handoffs. It routes repositories to the correct standards and defines the minimum governance expected for each repository class.

Standard

Document Type: Repository Classification Standards Document Applies To: All platform repositories, future repositories, AI-session onboarding, repository preflight, Git checkpoint work, Codex prompts, CI/CD review, supply-chain governance, runtime validation, release planning, state-directory governance, and future operations database ingestion. Status: Authoritative project standard unless later superseded by a newer dated standards document. Primary Purpose: Ensure that every repository is classified before work begins so the correct governance, validation, security, CI/CD, state-record, and release expectations are applied.

1. Purpose

The purpose of this standard is to prevent AI sessions from treating all repositories as if they have the same purpose.

A modular platform requires different repositories. Some repositories run production services. Some repositories contain internal tools. Some repositories contain public websites. Some repositories contain server configuration. Some repositories contain reference documentation used by AI agents. Some repositories may later contain shared libraries, infrastructure definitions, deployment templates, research experiments, reusable packages, or personal utilities.

If every repository receives the same process, two bad outcomes follow.

First, high-risk repositories may receive too little governance. A deployable repository that can affect customers, data, APIs, workers, containers, releases, scheduler behavior, or infrastructure must have strong validation, supply-chain records, technology decision records, integration records, release history, SBOMs where applicable, and controlled CI/CD.

Second, low-risk reference repositories may receive irrelevant governance. A context repository that only mirrors official documentation should not be forced into production-deployment workflows. Its risk is not runtime mutation; its risk is source provenance, stale documentation, incorrect mirroring, licensing ambiguity, and misleading AI guidance.

Repository classification solves this by routing each repository into the correct governance profile.

Before any repository work begins, the AI must determine the repository class.

2. Classification Principles

Repository classes are defined by purpose, risk, and operational effect.

The classification question is not:

What is this repository named?

The classification question is:

What can this repository affect?

A repository that can affect runtime behavior, deployment, customer-facing behavior, internal administrative behavior, server behavior, build artifacts, container images, release artifacts, data processing, production state, or infrastructure requires stronger controls than a repository that only stores reference documentation.

Repository names may provide clues, but names are not authoritative. If a repository's contents and purpose conflict with its name, the AI must stop and ask for classification.

The current repository list is not final. The platform may add more deployable application repositories, more shared libraries, more context repositories, more utility repositories, more infrastructure repositories, more experimental repositories, and more archived repositories. The standard must scale without rewriting the classification model.

Repository classification must remain implementation-agnostic where possible. The current remote Git host, current development machine, current deployment provider, current CI/CD system, current container runtime, and current infrastructure provider may change. The repository class should describe the repository's function and risk, not lock the repository to a vendor.

3. Required Classification Before Work

Before editing, patching, committing, pushing, merging, creating CI/CD jobs, adding dependencies, modifying Docker files, changing validation, writing Codex prompts, preparing release artifacts, or recommending architecture, the AI must classify the active repository.

The preflight classification should identify:

  1. Repository name.
  2. Repository path.
  3. Repository class.
  4. Whether the repository has more than one class.
  5. Whether the repository is deployable.
  6. Whether the repository can affect production runtime behavior.
  7. Whether the repository can affect public/customer-facing behavior.
  8. Whether the repository can affect internal/operator behavior.
  9. Whether the repository can affect server or infrastructure behavior.
  10. Whether the repository can affect external artifacts or supply-chain records.
  11. Whether the repository requires state governance records.
  12. Whether the repository requires release records.
  13. Whether the repository requires SBOM generation.
  14. Whether the repository may produce signed container images.
  15. Whether the repository should have deployment jobs.
  16. Whether the repository is read-only/reference-oriented by default.
  17. Whether the repository's classification is confirmed or uncertain.

If classification is uncertain, the AI must ask before proceeding.

A repository may be provisionally classified for inspection-only work. A provisional classification does not authorize implementation, dependency adoption, CI/CD changes, release work, deployment work, or governance record changes.

4. Repository Class Overview

The platform recognizes the following repository classes:

  1. Class A – Deployable Application Repository
  2. Class B – Shared Library Repository
  3. Class C – Context/Reference Repository
  4. Class D – Utility or Standalone Tool Repository
  5. Class E – Infrastructure Repository
  6. Class F – Experimental or Research Repository
  7. Class G – Archive or Retired Repository

Classes may be added later. Existing classes may be refined later. The AI must not invent a new class during an implementation task unless the task is explicitly to revise this standard.

A repository may have a primary class and one or more secondary classes. Multi-class repositories require the strictest applicable controls from every class they fit.

5. Repository Class Decision Tree

Use this decision tree before repository work begins.

1. Does the repository run, build, package, serve, deploy, or release a platform application, worker, site, API, dashboard, or runtime service?
   If yes, it is Class A or has a Class A component.

2. Does the repository provide reusable code intended to be imported, packaged, or consumed by other platform repositories?
   If yes, it is Class B or has a Class B component.

3. Does the repository primarily mirror, curate, store, or organize reference material for humans and AI sessions?
   If yes, it is Class C unless it also executes code or controls infrastructure.

4. Does the repository contain a standalone utility or personal/operator tool separate from the main platform runtime?
   If yes, it is Class D unless its operational permissions make it production-adjacent.

5. Does the repository define, configure, provision, deploy, or mutate infrastructure, server behavior, networking, tunnels, orchestration, services, scheduled jobs, or environment setup?
   If yes, it is Class E or has a Class E component.

6. Is the repository intentionally isolated for experiments, research, benchmark work, or proof-of-concept work?
   If yes, it is Class F and must be clearly marked.

7. Is the repository retained only for history, recovery, audit, or migration?
   If yes, it is Class G and must be clearly marked.

If more than one answer is yes, the repository is multi-classed. Apply the multi-class rules in this document.

6. Minimum Required State Folders by Class

The following table defines minimum state-directory expectations. These are minimums, not maximums. A repository may have additional state folders when justified by its role.

Repository class Minimum required state folders Notes
Class A – Deployable Application state/supply_chain/, state/technology_decisions/, state/integration_records/, state/handoffs/, state/release_history/, state/repository_classification.md SBOM records required for production releases. Cosign/signing records required for production container images.
Class B – Shared Library state/supply_chain/, state/technology_decisions/, state/integration_records/, state/handoffs/, state/release_history/, state/repository_classification.md Release history may be package/version history rather than deployment history.
Class C – Context/Reference state/source_inventory/, state/mirror_state/, state/update_history/, state/license_review/, state/handoffs/, state/repository_classification.md Full supply-chain records required only if the repo uses executable tooling or mirrors high-risk source material.
Class D – Utility/Standalone Tool state/handoffs/, state/release_history/, state/repository_classification.md Add supply-chain, technology decision, and integration records when the utility has operational impact.
Class E – Infrastructure state/supply_chain/, state/technology_decisions/, state/integration_records/, state/handoffs/, state/release_history/, state/environment_records/, state/repository_classification.md Production mutation requires the strongest controls and operator approval.
Class F – Experimental/Research state/experiment_records/, state/handoffs/, state/repository_classification.md Must clearly mark no-production-use boundaries.
Class G – Archive/Retired state/archive_status.md, state/repository_classification.md Generally no active development unless explicitly approved.

If a repository already has a different state structure, the AI must not reorganize it casually. The AI should identify the gap and propose a scoped governance-alignment task.

7. Standards Applicability Matrix

The following table identifies which standards normally apply by repository class. "Mandatory" means the standard applies before work can be considered complete. "Conditional" means the standard applies when the repository contains the relevant capability. "Minimal" means a lighter subset applies.

Standard / Requirement Class A Class B Class C Class D Class E Class F Class G
Human-AI Operating Dynamic Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory
Workspace Structure Guide Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory
Runtime Validation Standard Mandatory Mandatory Minimal/conditional Conditional Mandatory Conditional Minimal
Backend Tooling Standard Conditional Conditional Conditional Conditional Conditional Conditional Usually no
Git Checkpoint Standard Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Conditional
Git Commit Message Standard Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Conditional
Patch/Codex Workflow Standard Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Conditional
CI/CD Pipeline Standard Mandatory/expanding Mandatory/packaging Minimal/reference validation Conditional Mandatory/dry-run first Minimal/conditional Usually no
Supply Chain Security Standard Mandatory Mandatory Mandatory for source provenance; conditional for executable tooling Conditional by risk Mandatory Mandatory for experiments Conditional
Repository Classification Standard Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory
Architectural Impact Review Mandatory Mandatory Conditional Conditional Mandatory Conditional Conditional
Supply Chain Impact Review Mandatory Mandatory Mandatory for source updates Conditional by risk Mandatory Mandatory for candidate artifacts Conditional
Repository Governance Review Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Conditional
SBOM Generation Required for releases Required for package releases where applicable Usually no Conditional Conditional Usually no No
Cosign/Image Signing Required for production images Required if producing images No Conditional Required if producing images Experimental only if approved No
Release History Mandatory Mandatory Update history instead of release history Conditional Mandatory Experiment log Archive status
Production Deployment Controls Mandatory No unless deployable No No unless production-adjacent Mandatory Prohibited Prohibited

This table is a routing aid, not a substitute for judgment. When a repository's operational effect is higher than its nominal class, apply the stricter standard.

8. Class A – Deployable Application Repository

8.1 Definition

A Class A repository contains software that can be built, packaged, deployed, served, executed, or operated as part of the platform.

A Class A repository may contain:

  1. Backend application code.
  2. API code.
  3. Public website code.
  4. Internal admin site code.
  5. Worker code.
  6. Scheduled processing code.
  7. Runtime services.
  8. Dashboards.
  9. Container builds.
  10. Deployment definitions.
  11. Release artifacts.
  12. Runtime configuration examples.
  13. Production-adjacent validation.
  14. Monitoring and observability tools.
  15. Customer-facing pages or flows.
  16. Internal operator pages or dashboards.
  17. Runtime database access.
  18. Runtime integration wrappers.

A Class A repository may affect customers, operators, data, reports, content delivery, authentication, payments, notifications, AI provider calls, object storage, database access, server processes, or deployment behavior.

8.2 Current Examples

Current examples may include repositories such as:

  1. app when it contains the backend application, workers, processors, service modules, database access, monitoring, and runtime behavior.
  2. site when it contains public customer-facing website code, customer pages, checkout flows, dashboards, static site material, or frontend build behavior.
  3. admin when it contains private admin/operator dashboards, internal command-center pages, internal documentation publishing, report surfaces, or internal workflow tooling.
  4. server when it contains executable startup behavior, service definitions, scheduled jobs, deployment scripts, or production-adjacent runtime support.

These examples are illustrative only. Future Class A repositories may be created for additional services, APIs, workers, customer applications, internal applications, or platform components.

8.3 Required State Structure

A Class A repository shall maintain the following state structure when the relevant capability exists or is being introduced:

state/
    supply_chain/
        README.md
        inventory.md
        artifacts/
        sbom/
    technology_decisions/
    integration_records/
    handoffs/
    release_history/
    repository_classification.md

Additional repository-specific state folders may exist when needed.

8.4 Required Governance Records

Class A repositories require:

  1. Supply Chain Records for approved external artifacts.
  2. Technology Decision Records for major technology choices.
  3. Integration Records for approved artifacts integrated into the repository.
  4. Handoff records for significant AI-assisted implementation sessions.
  5. Release history when the repository participates in releases.
  6. SBOM records for production releases.
  7. Container-signing records when the repository produces production container images.
  8. Repository Classification Record.
  9. Governance follow-up records when reviews reveal unresolved issues.

8.5 Required Validation

Class A validation must follow affected behavior.

Validation may include:

  1. Syntax checks.
  2. Import checks.
  3. Unit tests.
  4. Integration tests.
  5. API contract checks.
  6. Build checks.
  7. Container build checks.
  8. Runtime smoke tests.
  9. Database access checks.
  10. No-mutation checks.
  11. Scheduler or worker checks.
  12. Monitoring checks.
  13. Frontend build checks.
  14. Static-site checks.
  15. Security checks.
  16. Supply-chain checks.
  17. CI/CD pipeline checks.
  18. Docker image checks where applicable.
  19. SBOM generation checks where applicable.
  20. Cosign signing/verification checks where applicable.

Validation must be recorded before commit readiness.

8.6 Required CI/CD

A Class A repository should have repository-specific CI/CD appropriate to its maturity.

The CI/CD path should begin with safe validation jobs and may later expand to build, package, artifact handling, staging deployment, manual production deployment gates, release automation, rollback support, SBOM generation, and image signing.

Production deployment must not be automated casually. Production deployment should require manual gates unless a later deployment standard explicitly changes the rule.

8.7 Container and Release Requirements

When a Class A repository produces a production container image:

  1. The image shall be built from approved base images.
  2. The base image shall be pinned by digest.
  3. The resulting production image shall be signed using Cosign.
  4. The release shall generate an SBOM.
  5. The image shall run as non-root unless a documented exception exists.
  6. The Dockerfile shall be structured for efficient caching.
  7. The image shall not contain secrets.
  8. The image shall have real health checks where applicable.
  9. The image shall be scanned before production use.
  10. The Integration Record shall document the build and release path.

8.8 Git Checkpoint Requirements

Before a Class A commit, the AI shall perform:

  1. Runtime Validation Review.
  2. Architectural Impact Review.
  3. Supply Chain Impact Review.
  4. Repository Governance Review.
  5. CI/CD Impact Review.
  6. Documentation and state-record review.
  7. Workflow weakness review.

If the review identifies a record that can be updated before commit, the AI shall update it before commit readiness. If the review identifies an issue requiring operator approval, the AI shall stop and ask or record a structured follow-up when appropriate.

9. Class B – Shared Library Repository

9.1 Definition

A Class B repository contains reusable code intended to be imported, packaged, versioned, shared, or consumed by other platform repositories.

A Class B repository may contain:

  1. Shared Python libraries.
  2. Shared frontend packages.
  3. Shared validation helpers.
  4. Shared API clients.
  5. Shared model definitions.
  6. Shared integration wrappers.
  7. Shared CI/CD templates.
  8. Shared runtime utilities.
  9. Shared configuration helpers.
  10. Shared types, schemas, contracts, or generated clients.

Class B repositories may not be independently deployed, but they can affect multiple downstream repositories. That makes them high leverage and high risk.

9.2 Required State Structure

Class B repositories should maintain:

state/
    supply_chain/
        README.md
        inventory.md
        artifacts/
        sbom/
    technology_decisions/
    integration_records/
    handoffs/
    release_history/
    repository_classification.md

SBOM and release-history depth depends on whether the library is packaged, published, or consumed through releases.

9.3 Required Governance

Class B repositories require strong supply-chain and versioning discipline because changes may propagate to multiple repositories.

Governance must document:

  1. Public or internal package identity.
  2. Versioning policy.
  3. Compatibility policy.
  4. Consumer repositories.
  5. Breaking-change procedure.
  6. Release procedure.
  7. Supply-chain dependencies.
  8. Integration expectations.
  9. Deprecation policy.
  10. Migration guidance for consuming repositories.

9.4 CI/CD

Class B repositories should have CI/CD that validates tests, packaging, linting, formatting, type checks where applicable, API/schema compatibility where applicable, and compatibility with consuming repositories where practical.

A shared library pipeline should not deploy services unless the repository also becomes deployable. If a Class B repository starts deploying runtime services, it must be reclassified or dual-classed with explicit operator approval.

10. Class C – Context/Reference Repository

10.1 Definition

A Class C repository contains reference material used by humans, ChatGPT sessions, Codex sessions, future AI agents, and local retrieval workflows.

A Class C repository may contain:

  1. Official vendor documentation.
  2. API schemas.
  3. SDK references.
  4. selected source excerpts.
  5. examples.
  6. release notes.
  7. metadata.
  8. source inventories.
  9. update scripts.
  10. documentation manifests.
  11. local notes that explain source-selection decisions.
  12. generated indexes.

Class C repositories do not run the platform. They do not deploy customer services. They do not mutate production data. Their primary risk is that untrusted, stale, unofficial, or incorrectly mirrored information may mislead future work.

10.2 Current Examples

Current examples may include context repositories whose names begin with ctx-, such as repositories for authentication tools, email providers, infrastructure providers, documentation tools, object storage providers, and other selected platform dependencies.

These examples are illustrative only. Future Class C repositories may be created for any tool, vendor, framework, service, protocol, standard, or technology that requires local reference material.

10.3 Required State Structure

Class C repositories should maintain a smaller governance structure:

state/
    source_inventory/
    mirror_state/
    update_history/
    license_review/
    handoffs/
    repository_classification.md

A Class C repository may also maintain supply-chain records if it uses scripts, package managers, container images, or external tooling to update the mirror.

10.4 Required Governance

Class C governance must document:

  1. Official source URLs.
  2. Source type.
  3. Source selection criteria.
  4. Mirrored content boundaries.
  5. Excluded content.
  6. Update process.
  7. Update date.
  8. License or usage status.
  9. Whether material is official, community, generated, copied, or locally authored.
  10. Whether the repository is read-only reference material.
  11. Whether content is English-only, API-only, release-note-only, selected excerpts, or complete documentation.
  12. Whether the repository contains generated manifests or indexes.

10.5 CI/CD

Class C repositories should use minimal validation.

Appropriate checks include:

  1. Markdown/frontmatter checks.
  2. Manifest checks.
  3. Source inventory checks.
  4. Duplicate file checks.
  5. Link checks where useful and not noisy.
  6. No-secret checks.
  7. File-size sanity checks.
  8. Documentation structure checks.
  9. Required README checks.
  10. Source attribution checks where practical.

Class C repositories should not have deployment jobs unless their purpose changes and the repository is reclassified.

10.6 Supply-Chain Review

A Class C repository must still follow supply-chain standards when it pulls or mirrors external source material.

The question is not whether the repository runs code. The question is whether future AI agents may rely on its content. If the content can guide future implementation, then provenance matters.

10.7 Context Repository Boundaries

Class C repositories should normally be read-only reference material during ordinary platform work.

AI sessions may inspect Class C repositories for guidance. They must not modify Class C repositories as part of unrelated application, site, admin, server, or utility work.

If a context repository needs updating, that update should be its own scoped repository task.

11. Class D – Utility or Standalone Tool Repository

11.1 Definition

A Class D repository contains a utility, support tool, backup script, local helper, operator tool, diagnostic tool, or standalone project that is not part of the main platform runtime.

A Class D repository may be low risk or high risk depending on what it can access.

A personal backup utility that can read, copy, archive, delete, encrypt, upload, or restore files is not automatically low risk merely because it is personal. Its risk depends on its permissions and operational effect.

11.2 Required State Structure

Class D repositories should maintain governance proportional to risk.

A low-risk Class D repository may need:

state/
    handoffs/
    release_history/
    repository_classification.md

A higher-risk Class D repository may also need:

state/
    supply_chain/
    technology_decisions/
    integration_records/

11.3 Classification Questions

Before reducing governance for a Class D repository, the AI must ask:

  1. Can this tool read important files?
  2. Can this tool write important files?
  3. Can this tool delete files?
  4. Can this tool access secrets?
  5. Can this tool upload or download data?
  6. Can this tool affect backups?
  7. Can this tool affect recovery?
  8. Can this tool run automatically?
  9. Can this tool affect production-adjacent material?
  10. Can this tool create irreversible effects?
  11. Can this tool access object storage, remote repositories, databases, email services, or messaging services?
  12. Can this tool be run by schedulers or automation workers?

If the answer to any of those questions is yes, the repository requires stronger governance.

11.4 Non-Platform Utilities

A repository may exist under the same remote Git account but not belong to the platform. A non-platform utility should not be mixed into platform governance unless the operator explicitly classifies it as platform-related.

If the operator identifies a repository as unrelated to the project, the AI must not apply platform tasks to it.

12. Class E – Infrastructure Repository

12.1 Definition

A Class E repository contains infrastructure definitions, server configuration, deployment templates, container orchestration definitions, Kubernetes manifests, Terraform/OpenTofu modules, Ansible roles, service-unit definitions, networking configuration, tunnel configuration, bootstrap scripts, scheduled-job definitions, or other material that can affect runtime environments.

Some current server/environment repositories may fit Class E or may be treated as Class A when they contain deployable runtime behavior. The operator must classify the repository according to actual content and operational effect.

12.2 Required State Structure

Class E repositories should maintain:

state/
    supply_chain/
    technology_decisions/
    integration_records/
    handoffs/
    release_history/
    environment_records/
    repository_classification.md

12.3 Required Controls

Infrastructure repositories require strong controls because they can mutate environments.

Class E repositories must treat the following as high impact:

  1. Server bootstrap scripts.
  2. Container orchestration files.
  3. Kubernetes manifests.
  4. Infrastructure modules.
  5. Tunnel routes.
  6. Access policies.
  7. Service units.
  8. Scheduled-job definitions.
  9. Secret references.
  10. Deployment scripts.
  11. Production resource mutation.
  12. Database migration commands.
  13. Object storage lifecycle rules.
  14. Firewall rules.
  15. Service restart behavior.
  16. Certificate or key material references.
  17. Identity provider configuration.
  18. DNS or routing configuration.

12.4 CI/CD

Class E CI/CD should begin with validation and dry-run checks.

Production infrastructure mutation must not occur automatically unless explicitly authorized by a later deployment or infrastructure standard and protected by manual gates.

12.5 Server Repository Treatment

The server repository requires special care because it may contain more than one class of material.

It may be Class E when it contains machine/server/environment configuration, startup scripts, scheduled-task exports, service units, tunnel configuration, bootstrap material, deployment notes, or future infrastructure definitions.

It may also have Class A characteristics when it contains active runtime support that directly starts, controls, deploys, packages, or operates platform services.

The AI must not assume the server repository is only documentation. It must inspect the actual task and affected files.

If a server task changes a script, service definition, scheduled job, tunnel route, Docker deployment, Kubernetes manifest, environment variable, production path, or startup behavior, the task must use the stronger Class E or Class A controls that apply.

If a server task updates only explanatory documentation, the AI may use a lighter validation path, but the repository remains infrastructure-adjacent and must still receive careful diff review.

13. Class F – Experimental or Research Repository

13.1 Definition

A Class F repository is used for experiments, prototypes, research, benchmarks, proofs of concept, or isolated trials.

Experimental repositories shall not become production dependencies by accident.

13.2 Required Marking

A Class F repository must clearly state:

  1. Experimental status.
  2. Purpose.
  3. Forbidden production use.
  4. Data restrictions.
  5. Secret restrictions.
  6. Cleanup expectations.
  7. Whether results may influence future Technology Decision Records.
  8. Whether the repository may access real project data.
  9. Whether the repository may access the network.
  10. Whether the repository may use unapproved candidate artifacts.

13.3 Promotion

If an experimental repository produces work that should become part of the platform, the relevant artifact must pass the full Supply Chain Security Standard, Technology Decision Record process, Integration Record process, and repository classification review.

Experimental success is not approval.

14. Class G – Archive or Retired Repository

14.1 Definition

A Class G repository is retained for history, recovery, reference, audit, or migration purposes but is not active.

14.2 Required Marking

A retired repository must clearly state:

  1. Retired status.
  2. Date retired.
  3. Reason retired.
  4. Replacement repository, if any.
  5. Whether the repository contains secrets or sensitive history.
  6. Whether it should be excluded from active AI-session work.
  7. Whether it may be deleted later.
  8. Whether it should remain accessible for audit or recovery.

AI sessions must not modify retired repositories unless the task explicitly authorizes archive maintenance.

15. Multi-Class Repositories

A repository may fit more than one class.

Multi-class repositories are allowed, but they must be explicit. The Repository Classification Record must identify the primary class and all secondary classes.

The rule for multi-class repositories is:

Apply the strictest applicable control from every class that fits the repository.

Examples:

  1. A server repository that stores infrastructure configuration and deployable startup scripts may be Class E with Class A characteristics.
  2. A shared library repository that also publishes a documentation site may be Class B with Class A release behavior for the documentation site.
  3. A context repository that includes executable update scripts may be Class C with conditional supply-chain and utility-tool controls.
  4. A utility repository that controls backups may be Class D with stronger operational controls.
  5. An experimental repository that pulls AI models may be Class F with Supply Chain Security Standard requirements for candidate artifacts.

The AI must not use the lower-risk class to avoid the higher-risk controls.

If the repository's class combination is unclear, the AI must ask the operator before proceeding.

16. Repository Classification Record

Every active repository should eventually have a Repository Classification Record.

Recommended path:

state/repository_classification.md

The record should be written in full explanatory sentences. Tables are allowed, but the record must not be reduced to unexplained checkboxes.

16.1 Repository Classification Record Template

# Repository Classification Record

Repository name:

Repository path:

Remote repository:

Primary class:

Secondary classes:

Classification status:
Confirmed, provisional, disputed, pending operator approval, or retired.

Classification date:

Classified by:

Approved by:

Reason for classification:
Explain why this repository belongs in the assigned class.

Operational role:
Explain what the repository does in the broader platform.

Deployable:
Yes or no. Explain.

Produces container images:
Yes, no, or future. Explain.

Produces release artifacts:
Yes, no, or future. Explain.

Can affect production runtime:
Yes or no. Explain.

Can affect public/customer-facing behavior:
Yes or no. Explain.

Can affect internal/operator behavior:
Yes or no. Explain.

Can affect infrastructure:
Yes or no. Explain.

Can affect reference material used by AI:
Yes or no. Explain.

Requires supply-chain records:
Yes, no, or conditional. Explain.

Requires technology decision records:
Yes, no, or conditional. Explain.

Requires integration records:
Yes, no, or conditional. Explain.

Requires SBOM:
Yes, no, or conditional. Explain.

Requires Cosign:
Yes, no, or conditional. Explain.

Requires release history:
Yes, no, or conditional. Explain.

Requires CI/CD:
Yes, no, or conditional. Explain.

Required validation depth:
Explain the minimum validation expected before commits.

Required state folders:
List required folders.

Known exclusions:
Identify work this repository does not own.

Related repositories:
List related repositories and explain the relationship.

Reclassification triggers:
List conditions that would require review.

Review interval:

Next review date:

Open governance follow-up:
List unresolved classification or state-structure work.

16.2 Classification Status Values

The classification status must be one of:

  1. Confirmed – operator-approved and current.
  2. Provisional – used only for inspection or initial setup until operator approval.
  3. Disputed – conflicting evidence exists.
  4. Pending operator approval – classification appears clear but has not been approved.
  5. Retired – repository is archive/retired.

A provisional classification shall not authorize high-impact changes.

17. Current Repository Examples

The following examples reflect current repository patterns and are not exhaustive.

17.1 app

The app repository is expected to be a Class A deployable application repository when it contains the core SaaS backend, processors, workers, database access, service logic, monitoring, Telegram integration, AI provider calls, reports, operations workflows, or runtime application behavior.

It may later include Docker runtime packaging, API layers, release artifacts, SBOMs, and signed production container images. When those capabilities are introduced, the Class A state and governance requirements apply.

17.2 site

The site repository is expected to be a Class A deployable application repository when it contains the public customer-facing website, static public pages, frontend build behavior, account pages, checkout flows, pricing pages, subscription pages, or customer dashboard surfaces.

Its validation may differ from the backend application repository. It may require frontend build checks, static-site checks, public wording review, link checks, accessibility checks, and customer-facing behavior validation.

17.3 admin

The admin repository is expected to be a Class A deployable application repository when it contains private admin/operator dashboards, internal command-center pages, internal documentation publishing, report surfaces, protected internal pages, AI-agent work surfaces, or operational tooling.

It may have stronger access-control and internal-data restrictions than the public site. It may also contain rendered documentation output and Markdown source. The AI must distinguish source documentation from generated output.

17.4 server

The server repository may be Class E, Class A, or both.

It is Class E when it stores machine/server/environment configuration, scheduled-task definitions, startup scripts, tunnel configuration, bootstrap material, service units, deployment notes, or future infrastructure definitions.

It has Class A characteristics when it actively supports deployment, startup, runtime service operation, Docker deployment, Kubernetes deployment, or production service control.

The AI must classify server tasks by affected files and operational effect. Documentation-only updates do not create deployment authority. Script, scheduler, tunnel, service, secret, environment, Docker, Kubernetes, or startup changes require stronger infrastructure controls.

17.5 ctx-*

Repositories with the ctx- prefix are expected to be Class C context/reference repositories when their purpose is to mirror selected official documentation, API schemas, source material, examples, release notes, or vendor/tool references for AI and human use.

They should normally be read-only during unrelated work. They should not deploy. They should not receive runtime application code. They should maintain source inventory, mirror state, update history, and license review records.

If a ctx-* repository contains executable update tooling, that tooling must follow conditional supply-chain and utility controls.

17.6 Utility Repositories

Utility repositories may be Class D when they contain standalone tools, backup utilities, diagnostics, operator scripts, or non-platform projects.

A repository under the same remote Git account is not automatically part of the platform. The operator may mark a repository as unrelated. Unrelated repositories should not be modified during platform work.

18. Repository Governance Review

Every Git checkpoint shall include a Repository Governance Review.

The AI must review whether the implementation changed or invalidated:

  1. Repository classification.
  2. Supply Chain Records.
  3. Technology Decision Records.
  4. Integration Records.
  5. Handoff records.
  6. Release history.
  7. Repository Classification Record.
  8. CI/CD pipeline expectations.
  9. Runtime validation expectations.
  10. SBOM requirements.
  11. Cosign requirements.
  12. Deployment expectations.
  13. Context/source inventory.
  14. Environment records.
  15. Operational documentation.
  16. Required state folder structure.
  17. Reclassification triggers.
  18. Related repository expectations.

The AI shall update only records affected by the implementation.

The AI shall not create governance churn by touching records that remain accurate.

The AI shall not skip governance updates merely because the code works.

If the review identifies a record that can be updated before commit, the AI must update it before commit readiness. If the review identifies work requiring operator approval or a separate task, the AI must record it as a structured follow-up.

19. Repository Governance Review Template

Before commit readiness, the AI should be able to produce the following review summary:

Repository Governance Review

Repository:
Repository path:
Current branch:
Repository class:
Classification status:

Governance records reviewed:
- Repository Classification Record:
- Supply Chain Records:
- Technology Decision Records:
- Integration Records:
- Handoff records:
- Release history:
- Environment records:
- Source inventory or mirror state:

Records updated before commit:
-

Records not updated:
-

Reason records were not updated:
Explain why each unaffected record remains accurate.

Reclassification needed:
Yes or no. Explain.

State folder changes needed:
Yes or no. Explain.

SBOM impact:
Yes, no, or not applicable. Explain.

Cosign impact:
Yes, no, or not applicable. Explain.

CI/CD impact:
Explain.

Follow-up tasks generated:
List structured follow-up tasks, including cause, location, reason, and priority.

Workflow weakness, ambiguity, missing safeguard, or repetitive manual step discovered:
Explain whether the task revealed a process problem and whether it was fixed now or recorded for later.

This review is not a substitute for the full commit message. It is the review that supports commit readiness.

20. Relationship to Architectural Impact Review

Repository Governance Review is related to, but distinct from, Architectural Impact Review.

Architectural Impact Review asks:

What did this change affect architecturally?

Repository Governance Review asks:

Do the repository's governance records still accurately describe the repository after this change?

A commit may pass runtime validation and still fail governance review if records are stale, misleading, incomplete, or inconsistent with the implementation.

21. Relationship to Supply Chain Security

Repository class determines supply-chain depth.

Class A and Class E repositories generally require the strongest supply-chain controls because they affect deployable runtime or infrastructure.

Class B repositories require strong supply-chain controls because they can affect multiple consuming repositories.

Class C repositories require source provenance and mirror governance because AI agents may rely on their content.

Class D repositories require controls proportional to operational effect.

Class F repositories require isolation and no-production-use marking.

Class G repositories require archive controls.

No repository class is exempt from supply-chain reasoning. The depth differs by class.

22. Relationship to CI/CD

Repository class determines CI/CD expectations.

Class A repositories should move toward validation, build, package, staging, release, SBOM, signing, and controlled deployment.

Class B repositories should validate tests, packaging, compatibility, and release artifacts where applicable.

Class C repositories should validate documentation/reference structure and source inventories.

Class D repositories should validate according to operational effect.

Class E repositories should validate and dry-run infrastructure changes before any mutation.

Class F repositories may have minimal CI/CD but must not publish production artifacts.

Class G repositories generally should not run active CI/CD unless archive validation is required.

23. Relationship to State Directory

The state directory is durable operational memory.

It is not disposable scratch space. It is not a log dump. It is not generated noise. It is where AI sessions, human operators, future automation workers, and future operations database ingestion can find durable repository state.

The specific required state subdirectories depend on repository class.

A future task may standardize the state directory structure across repositories. Until then, repository class determines the minimum required structure.

If a required state folder is missing, the AI should not create it casually during unrelated work. The AI should identify the missing folder as a governance alignment item unless the current task explicitly includes state-structure setup.

24. Relationship to Operations Database

Repository state files are the initial source records for repository governance.

A future operations database may ingest repository classification, supply-chain records, technology decisions, integration records, release history, handoffs, SBOM metadata, and governance follow-up tasks.

The repository remains the reviewable record because Git provides history, diffs, branches, merge commits, and recovery. The operations database provides query, automation, alerting, and AI-worker coordination.

A later standard may define the exact source-of-truth relationship. Until then, repository state files are the authoritative working records and the operations database is the future operational index.

25. Required AI Behavior

When working in a repository, the AI must:

  1. Confirm the repository path.
  2. Confirm the repository class.
  3. Confirm whether the repository is single-class or multi-class.
  4. Confirm the branch.
  5. Confirm the working tree state.
  6. Identify applicable standards.
  7. Apply validation depth appropriate to the class.
  8. Apply supply-chain controls appropriate to the class.
  9. Apply CI/CD review appropriate to the class.
  10. Update affected state records before commit readiness.
  11. Record unresolved governance issues as structured follow-up.
  12. Avoid applying deployment requirements to context repositories unless reclassification is required.
  13. Avoid treating utility repositories as low risk without reviewing operational effect.
  14. Avoid treating current examples as the complete repository list.
  15. Ask the operator when classification is ambiguous.
  16. Avoid reclassification without operator approval.
  17. Avoid modifying unrelated repositories.

26. Reclassification

A repository may be reclassified when its purpose changes.

Triggers for reclassification include:

  1. A context repository begins running code.
  2. A utility becomes production-adjacent.
  3. A shared library becomes independently deployable.
  4. A server repository begins managing infrastructure as code.
  5. An experimental repository becomes a planned production component.
  6. A deployable repository is retired.
  7. A repository begins producing container images.
  8. A repository begins producing release artifacts.
  9. A repository begins affecting production runtime behavior.
  10. A repository begins deploying services.
  11. A repository begins controlling infrastructure.
  12. A repository begins storing source material that AI agents rely on for implementation.
  13. A repository begins publishing packages.
  14. A repository begins consuming secrets.
  15. A repository begins mutating data, backups, storage, or remote systems.

Reclassification requires operator approval and a Repository Classification Record update.

26.1 Reclassification Procedure

When reclassification may be required, the AI must:

  1. Stop before implementation if the classification affects task safety.
  2. Explain the current classification.
  3. Explain the proposed classification.
  4. Explain what changed.
  5. Identify standards that would newly apply.
  6. Identify state folders that would need to be created.
  7. Identify CI/CD changes that may be required.
  8. Identify supply-chain record changes that may be required.
  9. Ask for operator approval.
  10. Update the Repository Classification Record after approval.
  11. Record the reclassification in the commit message.

26.2 No Silent Reclassification

The AI shall not silently reclassify a repository.

If a task reveals that the repository's current classification is inaccurate, the AI must surface the issue to the operator.

27. Prohibited Classification Errors

The AI shall not:

  1. Treat the entire platform as one repository.
  2. Treat the application backend repository as the whole project.
  3. Treat context repositories as deployable repositories by default.
  4. Treat deployable repositories as documentation-only.
  5. Treat utility repositories as harmless without reviewing permissions.
  6. Treat infrastructure files as low risk because they are text files.
  7. Apply Docker, SBOM, or Cosign requirements to repositories that do not produce containers, except as future-readiness notes.
  8. Skip supply-chain review because a repository is not deployable.
  9. Skip governance review because a change is small.
  10. Use current repository examples as an exhaustive list.
  11. Reclassify a repository silently.
  12. Start work when repository class is ambiguous.
  13. Apply Class C light governance to a repository that can mutate runtime behavior.
  14. Apply Class D light governance to a utility that can delete or upload important files.
  15. Apply deployment automation to a repository whose class does not allow deployment.

28. Commit Message Requirements

When repository classification or governance is relevant, commit messages shall record:

  1. Repository class.
  2. Classification status.
  3. Governance records reviewed.
  4. Governance records updated.
  5. Governance records not updated and why.
  6. Supply-chain impact.
  7. CI/CD impact.
  8. Runtime validation impact.
  9. Release impact.
  10. SBOM or Cosign impact where applicable.
  11. Reclassification impact.
  12. State directory impact.
  13. Workflow weakness, ambiguity, missing safeguard, or repetitive manual step discovered.
  14. Follow-up tasks generated.

This information must be written in full explanatory sentences so future AI workers and operations database ingestion can understand the result without the original chat transcript.

29. Example Classification Summaries

29.1 app

Repository class:
Class A deployable application repository.

Reason:
The repository contains backend application behavior, runtime processing, workers, monitoring, database access, provider integrations, and future container/release behavior.

Required governance:
Supply Chain Records, Technology Decision Records, Integration Records, Handoffs, Release History, Repository Classification Record, SBOM records for releases, Cosign records for production container images.

Validation posture:
Strong runtime validation, backend validation, CI/CD validation, supply-chain review, and release controls.

29.2 site

Repository class:
Class A deployable application repository.

Reason:
The repository contains customer-facing website behavior and may contain frontend build, checkout, account, pricing, subscription, or dashboard surfaces.

Required governance:
Supply Chain Records, Technology Decision Records, Integration Records, Handoffs, Release History, Repository Classification Record, SBOM records where applicable, CI/CD build validation, and public-facing review.

Validation posture:
Frontend/static build validation, link checks where useful, public wording review, accessibility review where applicable, CI/CD validation, and deployment controls.

29.3 admin

Repository class:
Class A deployable application repository.

Reason:
The repository contains internal admin/operator surfaces, command-center documentation routes, dashboards, report access, private internal pages, and operational workflows.

Required governance:
Supply Chain Records, Technology Decision Records, Integration Records, Handoffs, Release History, Repository Classification Record, internal-access controls, CI/CD validation, and deployment controls.

Validation posture:
Internal route validation, documentation source/render validation, access-control awareness, dashboard validation, and CI/CD validation.

29.4 server

Repository class:
Class E infrastructure repository with possible Class A characteristics depending on task scope.

Reason:
The repository may contain server configuration, environment setup, scheduled task definitions, startup scripts, tunnel configuration, deployment support, future service definitions, or infrastructure automation.

Required governance:
Supply Chain Records, Technology Decision Records, Integration Records, Handoffs, Release History, Environment Records, Repository Classification Record, and dry-run validation where infrastructure mutation is possible.

Validation posture:
Script syntax checks, configuration validation, dry-run checks, no-production-mutation default, explicit operator approval before infrastructure mutation, and CI/CD validation appropriate to infrastructure work.

29.5 ctx-*

Repository class:
Class C context/reference repository.

Reason:
The repository mirrors selected source material for AI and human reference. It is not a runtime application repository and should not deploy platform services.

Required governance:
Source Inventory, Mirror State, Update History, License Review, Handoffs, Repository Classification Record, and supply-chain records only if executable update tooling or high-risk source acquisition exists.

Validation posture:
Documentation/reference validation, source provenance checks, no-secret checks, manifest checks, and no deployment.

30. Final Rule

Every repository must be understood before it is changed.

Repository classification is the first routing decision that determines which standards apply, how much validation is required, which governance records must be maintained, which supply-chain controls apply, and what a safe commit means.

A future AI agent must not guess the class, collapse the platform into one repository, or apply a convenient standard instead of the correct standard. If classification is unclear, the correct action is to stop and ask.