Specification

specification · v0.1.2

The AI Contributor Spec

Twenty-nine clauses across seven pillars. Five levels from baseline hygiene to autonomous AI operation. Use MUST / SHOULD / MAY in the RFC 2119 sense.

CC BY 4.0Creative Commons Attribution 4.0 International

I

🏗️Engineering Foundation

§1–4 · 4 clauses

§1required at L0

Reproducible environment

Anyone — human or agent — can stand up the project from a clean machine and arrive at a working state without tribal knowledge.

1. MUSTA clean clone `MUST` reach a working development state using documented steps.AIC-clean-clone-bootstrap
2. MUSTThe dependency lockfile `MUST` be committed to version control.AIC-lockfile-committed
3. MUSTThe package manager version `MUST` be pinned when the ecosystem allows it.AIC-package-manager-pinned
4. MUSTThe runtime version `MUST` be pinned.AIC-runtime-version-pinned
5. MUSTMulti-package repositories `MUST` have a deterministic build order.AIC-deterministic-build-order
6. MUSTCI `MUST` reject changes that would invalidate the committed lockfile (for example via `--frozen-lockfile`, `npm ci`, `pip --require-hashes`, or equivalent).AIC-lockfile-enforced-in-ci
7. MUSTDependency lockfiles `MUST` include integrity hashes where the ecosystem supports them, and CI `MUST` fail when integrity verification fails.AIC-lockfile-integrity-hashes
8. SHOULDHeavy builds `SHOULD` document memory, CPU, or platform prerequisites.AIC-heavy-build-prerequisites
9. SHOULDBrowser, runtime, and platform targets `SHOULD` be explicit.AIC-platform-targets-explicit
10. MAYThe repository `MAY` provide containerized or sandboxed development environments for stronger consistency.AIC-containerized-dev-env

§2required at L0

Static correctness

Mistakes are caught before they reach review. Static analysis runs locally and in CI on identical configuration.

1. MUSTFormatting `MUST` be automated and enforced.AIC-formatting-automated
2. MUSTUnused variables, dead code, import cycles, and unsafe dependency patterns `MUST` be surfaced automatically.AIC-dead-code-and-cycles-surfaced
3. MUSTLinting `MUST` include correctness rules, not only style rules.AIC-lint-correctness-rules
4. MUSTStrict typing or equivalent compile-time checks `MUST` be enabled.AIC-strict-typing-enabled
5. SHOULDThe repository `SHOULD` ban unsafe escape hatches such as untyped `any` unless explicitly justified.AIC-ban-unsafe-escape-hatches
6. SHOULDAd-hoc debug statements (for example `console.log`, `print`, `dump`, language-equivalent debug emitters) `SHOULD` be flagged or blocked by lint, leaving structured logging from §13 as the only sanctioned output path. Agents and humans alike scatter debug emitters during exploration and forget to remove them; without a lint-time backstop, the residue ships.AIC-debug-statement-lint
7. SHOULDIt `SHOULD` enforce naming and export conventions where consistency materially improves maintenance.AIC-naming-export-conventions
8. MAYThe repository `MAY` add repository-specific lint rules for domain conventions.AIC-domain-lint-rules

§3required at L1

Architecture boundaries

The shape of the codebase is legible. Modules have stated responsibilities and known import boundaries — both humans and agents can reason about scope.

1. MUSTArchitectural rules that can be machine-enforced `MUST` be automated.AIC-architecture-rules-automated
2. MUSTAllowed dependency directions `MUST` be explicit.AIC-dependency-directions-explicit
3. MUSTThe repository `MUST` define module, package, or layer responsibilities.AIC-layer-responsibilities-defined
4. MUSTSensitive or shared layers `MUST` be protected from importing implementation-specific or infrastructure-specific code when architectural separation depends on that boundary.AIC-shared-layer-import-protection
5. SHOULDThe repository `SHOULD` use boundary tests or scans in addition to linter rules.AIC-boundary-tests
6. SHOULDIt `SHOULD` include a review checklist for coupling risks that tooling cannot catch.AIC-coupling-review-checklist
7. MAYThe repository `MAY` model architecture constraints in dedicated analysis tools if the codebase is large enough to justify it.AIC-architecture-analysis-tools

§4required at L1

Pre-commit and CI gates

Verification cannot be skipped. The same checks run locally before commit and on every push.

1. MUSTCI `MUST` run the authoritative guardrail suite for protected branches.AIC-ci-guardrail-suite
2. MUSTCI `MUST` use the pinned toolchain and locked dependency state.AIC-ci-pinned-toolchain
3. MUSTProtected branches `MUST` require passing status checks before merge.AIC-protected-branch-status-checks
4. MUSTPre-commit hooks `MUST` run meaningful local checks.AIC-precommit-meaningful-checks
5. SHOULDExpensive jobs `SHOULD` be separated intentionally rather than omitted silently.AIC-expensive-jobs-explicit
6. SHOULDThe repository `SHOULD` expose a fast-iteration command path — for example scoped tests, changed-file lint, or per-package verify scripts — so intermediate work can be validated cheaply without running the full guardrail suite on every iteration. The full suite remains the authoritative gate; the fast path is for the iteration loop.AIC-fast-iteration-path
7. SHOULDThe local and CI quality bars `SHOULD` stay closely aligned.AIC-local-ci-aligned
8. MAYThe repository `MAY` use adaptive or staged CI when the distinction between fast and slow checks is explicit and documented.AIC-adaptive-staged-ci

II

🛡️Security

§5–9 · 5 clauses

§5required at L0

Secrets and credentials

Secrets never live in the repository, in chat with an agent, or in build artifacts.

1. MUSTCredential handling `MUST` be documented for contributors and automation.AIC-credential-handling-documented
2. MUST·whenWhen the repository requires contributor-supplied or runtime environment variables, example environment files `MUST` contain placeholders only.AIC-env-example-placeholders
3. MUSTSecret-bearing files `MUST` be excluded from version control.AIC-secret-vcs-exclude
4. MUST·whenPush protection `MUST` be enabled when supported and feasible for the repository's hosting platform.AIC-push-protection-enabled
5. MUSTAutomated secret scanning `MUST` be enabled.AIC-secret-scanning-enabled
6. SHOULDThe repository `SHOULD` document how contributors and automation obtain development credentials, how those credentials are rotated, and what triggers a rotation (suspected leak, contributor offboarding, scheduled cadence). This is particularly important for AI agents, which cannot complete interactive credential-issuance flows and otherwise accumulate static, long-lived tokens.AIC-credential-rotation-documented
7. SHOULDThe repository `SHOULD` define custom detection patterns for organization-specific secret formats.AIC-custom-secret-patterns
8. SHOULDIt `SHOULD` provide a safe mock mode or local fallback path that avoids requiring live secrets for common development flows.AIC-mock-mode-fallback
9. MAYThe repository `MAY` integrate secret rotation or secret lease validation into operational workflows.AIC-secret-rotation-automation

§6required at L1

Security scanning and dependency security

Third-party code is treated as untrusted input. Known vulnerabilities are surfaced and acted on.

1. MUST·whenDependency changes in pull requests `MUST` be visible to reviewers through automation or policy.AIC-dependency-review-visibility
2. MUST·whenDependency vulnerability detection `MUST` be enabled.AIC-dependency-vuln-detection
3. MUST·whenSecurity-focused static analysis `MUST` run in CI for supported languages and platforms.AIC-sast-in-ci
4. SHOULDThe repository `SHOULD` automate safe dependency update PRs.AIC-automated-dep-updates
5. SHOULDIt `SHOULD` automate license review if distribution or compliance requirements apply.AIC-license-review-automation
6. SHOULDIt `SHOULD` track and assign ownership for unresolved vulnerability alerts.AIC-vuln-alert-ownership
7. MAYInternet-facing applications `MAY` run dynamic application security testing (DAST) against a deployed environment to surface vulnerabilities that static analysis misses.AIC-dast-internet-facing
8. MAYHigh-risk systems `MAY` undergo periodic penetration testing by an independent reviewer.AIC-penetration-testing-periodic
9. MAYThe repository `MAY` apply stricter policies to new dependencies than to existing ones.AIC-strict-new-dep-policy

§7required at L1

Authorization and trusted boundaries

The build pipeline itself is a privileged surface. It runs untrusted code only with intent.

1. MUSTRepositories `MUST` have checks or tests that detect dangerous credential or role leakage into the wrong layers.AIC-credential-leakage-checks
2. MUSTData integrity constraints `MUST` exist where the persistence layer supports them.AIC-data-integrity-constraints
3. MUSTAuthorization `MUST` be enforced in a trusted layer such as the backend, API, or data layer.AIC-authz-trusted-layer
4. MUSTPrivileged credentials `MUST NOT` be present in untrusted client code.AIC-no-privileged-creds-in-client
5. SHOULDSecurity-sensitive write paths `SHOULD` have explicit ownership, auditability, and narrow interfaces.AIC-sensitive-write-paths-owned
6. MAYThe repository `MAY` add defense-in-depth client-side controls for UX, as long as they are not misrepresented as authoritative controls.AIC-defense-in-depth-client

§8required at L1

CI/CD workflow hardening

Privileged operations are gated by explicit authorization checks at the boundary, not at the call site.

1. MUST·whenProduction deployment paths `MUST` be protected from arbitrary execution and unauthorized triggering.AIC-prod-deploy-protected
2. MUST·whenDeployment credentials `MUST` be short-lived where the platform supports it.AIC-short-lived-deploy-creds
3. MUST·whenWorkflow tokens `MUST` use least privilege.AIC-workflow-token-least-privilege
4. SHOULDThird-party GitHub Actions `SHOULD` be referenced by a tagged version or release ref (for example `pnpm/action-setup@v6`) rather than a floating branch ref like `@main` or `@master`. A floating ref ships whatever is on that branch into CI on the next run; pinning to a release tag bounds what can change between deliberate bumps. Stronger SHA pinning is the `MAY` below, justified by threat model.AIC-action-version-pinned
5. SHOULDIt `SHOULD` protect deployment environments with approval rules or environment policies.AIC-deploy-env-approvals
6. SHOULDThe repository `SHOULD` use OIDC or equivalent identity federation instead of long-lived cloud secrets.AIC-oidc-federation
7. SHOULDIt `SHOULD` review workflow file changes with extra scrutiny.AIC-workflow-change-review
8. MAYThe repository `MAY` use reusable workflows or central workflow templates to reduce drift.AIC-reusable-workflows
9. MAYRepositories `MAY` SHA-pin third-party GitHub Actions when the threat model justifies it — production-deploy workflows, high-stakes tokens, or compliance regimes that require bit-exact reproducibility — paired with an automated bumper such as Renovate or Dependabot that keeps the pins current. Tag-pinning with an active bumper is the readable default; SHA-pinning without a bumper is worse than tag-pinning because pins go stale and stop receiving security patches.AIC-third-party-action-pinning

§9required at L1

Threat modeling and security design review

Security is reasoned about explicitly, not inferred. Trust boundaries are written down.

1. MUST·whenThreat modeling `MUST` produce a durable artifact identifying assets, trust boundaries, entry points, and likely attacker paths. A verbal agreement does not satisfy this requirement.AIC-threat-model-artifact
2. MUST·whenInternet-facing, multi-tenant, regulated, or high-impact systems `MUST` undergo threat modeling or security design review.AIC-threat-model-required
3. MUST·whenRepositories subject to this requirement `MUST` record when the threat model was last reviewed.AIC-threat-model-review-date
4. SHOULDThreat models `SHOULD` be revisited when authentication, deployment, storage, or trust boundaries change.AIC-threat-model-revisit
5. MAYLower-risk repositories `MAY` satisfy this requirement with lightweight design review rather than heavyweight formal exercises.AIC-threat-model-lightweight

III

🎯Quality & Reliability

§10–14 · 5 clauses

§10required at L1

Runtime validation and invariants

Inputs at process boundaries are validated. Bad data is rejected loudly, not propagated.

1. MUSTCritical invariants `MUST` be documented in one authoritative place.AIC-invariants-documented
2. MUSTCritical invariants `MUST` be executable through tests, assertions, or validators wherever practical.AIC-invariants-executable
3. MUSTExternal inputs, configuration, and machine-readable product metadata `MUST` be validated before use.AIC-input-validation
4. SHOULDThe repository `SHOULD` fail fast on invalid inputs and emit actionable diagnostics.AIC-fail-fast-diagnostics
5. SHOULDValidation layers `SHOULD` separate structural validity from semantic validity.AIC-structural-vs-semantic-validation
6. MAYThe repository `MAY` downgrade suspicious but non-fatal states to warnings if the product can continue safely.AIC-non-fatal-warning-downgrade

§11required at L1

Testing strategy

There is a stated testing strategy, and CI runs the tests it implies. Tests are fast enough to be run on every change.

1. MUST·whenCoverage thresholds `MUST` exist if the team uses coverage as a guardrail, and those thresholds `MUST` be treated as a minimum rather than a target.AIC-coverage-as-minimum
2. MUSTCritical business behavior `MUST` be covered by automated tests.AIC-critical-behavior-tested
3. MUSTThe repository `MUST` use multiple test layers rather than relying on a single style of testing.AIC-multiple-test-layers
4. SHOULDEnvironment-specific or excluded test suites `SHOULD` be explicitly documented.AIC-excluded-suites-documented
5. SHOULDEnd-to-end and acceptance tests `SHOULD` execute against the same artifact the repository ships (for example the production build output, a built container image, or the published package), not the development server alone. Bundling, tree-shaking, asset rewriting, and environment-variable inlining produce divergence between dev and prod that only appears when the built artifact is exercised.AIC-e2e-built-artifact
6. SHOULDWhere coverage is used as a gate, the repository `SHOULD` assess test-suite strength through an independent mechanism such as mutation testing, property-based tests, or independent review. Coverage alone does not distinguish effective assertions from ones that pass trivially.AIC-test-strength-independent
7. SHOULDTest environments `SHOULD` be deterministic where possible. Tests at the integration and end-to-end layers `SHOULD NOT` reach live external networks or shared production-like services by default; they `SHOULD` run against in-process mocks, recorded fixtures, or sandboxed substitutes, with any deviation explicitly opted in. Network nondeterminism amplifies AI-generated flakiness and erodes the signal of every gate that depends on the suite.AIC-test-network-isolation
8. SHOULDTests `SHOULD` be located close to the code they protect.AIC-tests-colocated
9. MAYParser-heavy or security-sensitive components `MAY` use fuzzing to surface input-domain failures that example-based tests routinely miss.AIC-fuzzing-parsers
10. MAYThe repository `MAY` use differential or risk-based test selection in CI if the full quality bar remains intact before release.AIC-risk-based-test-selection

§12required at L1

Accessibility

User-facing surfaces are usable by people with disabilities. Accessibility is part of verification, not a follow-up.

1. MUST·whenShared UI components `MUST` be checked for serious accessibility failures.AIC-a11y-component-checks
2. MUST·whenAccessibility expectations for semantics, focus, and labeling `MUST` be part of normal review and testing.AIC-a11y-review-testing
3. SHOULDThe repository `SHOULD` provide shared accessibility test helpers.AIC-a11y-helpers
4. SHOULDKeyboard behavior and focus management `SHOULD` be covered where interaction complexity warrants it.AIC-a11y-keyboard-focus
5. MAYThe repository `MAY` enforce additional accessibility gates such as motion, contrast, or localization-specific checks.AIC-a11y-extra-gates

§13required at L1

Failure handling and observability

When things break, the system says so. Logs, metrics, and traces are deliberate, not accidental.

1. MUST·whenProduction code `MUST` handle failure explicitly, not only through happy-path logic.AIC-failure-handling-explicit
2. MUST·whenRetries, backoff, and fallback behavior `MUST` be deliberate where transient failure is expected.AIC-retries-backoff-deliberate
3. MUST·whenWhen the repository operates a service, app, worker, proxy, or production runtime that emits logs, telemetry, traces, or error reports, observability outputs `MUST` redact secrets, credentials, and personally identifiable information, and `MUST` avoid leaking unnecessary personal data. §22 extends this requirement to AI-specific surfaces such as prompts, agent transcripts, and tool outputs.AIC-observability-redaction
4. SHOULDIt `SHOULD` provide clear ownership for alerts, logs, and operational visibility.AIC-alert-ownership
5. SHOULDIt `SHOULD` preserve user work locally or durably when silent data loss would be unacceptable.AIC-preserve-user-work
6. SHOULDThe repository `SHOULD` define structured error handling patterns.AIC-structured-error-patterns
7. MAYThe repository `MAY` include richer diagnostic breadcrumbs, tracing, or client event telemetry where privacy and value justify it.AIC-rich-diagnostics

§14required at L1

Performance and reliability

Performance and reliability targets are stated, measured, and defended.

1. MUST·whenUser-facing systems `MUST` define performance budgets if speed materially affects user experience.AIC-performance-budgets
2. MUST·whenServices and critical applications `MUST` define reliability expectations if downtime or latency materially affects users.AIC-reliability-expectations
3. SHOULDReliability targets `SHOULD` have clear consequences or escalation paths when missed.AIC-reliability-consequences
4. SHOULDPerformance budgets `SHOULD` be measurable in automation.AIC-budgets-automated
5. MAYTeams `MAY` use SLOs, SLIs, error budgets, or equivalent models according to operational maturity.AIC-slo-sli-error-budgets

IV

🚀Release

§15–16 · 2 clauses

§15required at L1

Supply-chain transparency and artifact integrity

What ships is what was reviewed. Provenance is verifiable.

1. MUST·whenRepositories that publish artifacts `MUST` be able to identify what dependencies went into a release.AIC-release-dependency-identification
2. MUST·whenRepositories that publish artifacts to external consumers `MUST` generate an SBOM if the ecosystem and tooling support it reasonably.AIC-sbom-generation
3. SHOULDSource, build instructions, and outputs `SHOULD` be linked through immutable references where practical.AIC-build-immutable-refs
4. SHOULDRepositories `SHOULD` provide provenance or attestations when downstream consumers need build trust.AIC-build-provenance-attestation
5. SHOULDPublished artifacts `SHOULD` be built from CI rather than developer workstations.AIC-release-from-ci
6. MAYRepositories `MAY` sign artifacts, verify attestations downstream, or adopt stronger supply-chain frameworks when their distribution model warrants it.AIC-artifact-signing
7. MAYRepositories `MAY` enforce admission control or attestation verification in downstream deployment environments so unsigned or unprovenanced artifacts cannot run.AIC-policy-enforcement-admission-control

§16required at L1

Branch protection, ownership, and release governance

The default branch is sacred. Releases happen through documented rituals, not by accident.

1. MUSTThe default branch `MUST` be protected.AIC-default-branch-protected
2. MUSTRequired checks and required reviews `MUST` be enabled for protected branches.AIC-required-checks-and-reviews
3. MUSTRisky or sensitive changes `MUST` have clear ownership.AIC-risky-change-ownership
4. MUST·whenRepositories `MUST` identify sensitive paths — for example, authentication and authorization code, CI/CD workflow files, deployment configuration, dependency manifests, and policy documents — and define path-level ownership for them when platform support exists.AIC-sensitive-path-ownership
5. MUSTRequired-review approvals on protected branches `MUST` come from human reviewers; bot or agent accounts `MUST NOT` satisfy required-review counts and `MUST NOT` merge their own pull requests.AIC-human-review-required
6. MUST·whenPublic or externally consumed repositories `MUST` provide a vulnerability disclosure path such as `SECURITY.md`.AIC-vuln-disclosure-path
7. SHOULDPath-level ownership `SHOULD` cover auth, infrastructure, workflow, deployment, and policy files (for example, a `CODEOWNERS` file on platforms that support it).AIC-codeowners-coverage
8. SHOULDThe ownership manifest itself `SHOULD` have an owner.AIC-codeowners-self-owned
9. SHOULDPreview and production deployments `SHOULD` be separated.AIC-deployment-separation
10. MAYThe repository `MAY` add merge queues, release trains, or additional policy layers for high-throughput teams.AIC-merge-queue-policy-layers

V

🤖AI Agents

§17–20 · 4 clauses

§17required at L2

AI operating model

Agents need a README written for them. AGENTS.md is the entry point: how to run, test, and contribute, in machine-readable form.

1. MUSTIt `MUST` identify actions the AI is not allowed to perform automatically.AIC-ai-forbidden-actions
2. MUSTIt `MUST` define architectural boundaries, coding conventions, non-negotiable invariants, and approval requirements.AIC-ai-instruction-boundaries
3. MUSTThat instruction source `MUST` describe how to build, test, lint, run, review, contribute, and determine when a change is ready to merge.AIC-ai-instruction-coverage
4. MUSTThe repository `MUST` provide one authoritative, versioned instruction source for AI agents.AIC-ai-instruction-authoritative
5. MUSTThe path of the authoritative source `MUST` be documented in `CONTRIBUTING.md` or `README.md` so contributors and AI tools can resolve it without guessing. Any tool-specific instruction files that exist alongside it `MUST` contain only a pointer to the authoritative source — they `MUST NOT` re-declare or contradict its content.AIC-tool-specific-pointer-only
6. SHOULDIt `SHOULD` keep AI-facing instructions concise, current, and linked from contributor documentation. As a working ceiling, the authoritative instruction source `SHOULD` stay under roughly 300 lines: longer files stop being read end-to-end by either humans or model context windows, and the seven coverage areas in `AIC-ai-instruction-coverage` collapse into prose rather than scannable rules. Push detail into linked policy docs rather than growing the instruction file.AIC-ai-instructions-discoverable
7. SHOULDThe repository `SHOULD` standardize common AI workflows such as implementation, review, PR preparation, release preparation, and incident fix handling.AIC-ai-workflow-standardization
8. MAYThe repository `MAY` provide specialized task templates or commands for recurring workflows.AIC-ai-task-templates
9. MAYMulti-package repositories `MAY` add path-scoped instruction files in subdirectories so rules that apply to only one package live next to the code they govern. Path-scoped files `MUST` extend the root authoritative source, `MUST NOT` contradict it, and `MUST NOT` re-declare approval boundaries or forbidden actions — the root file remains authoritative for those.AIC-scoped-ai-instructions

§18required at L2

Skills and shared workflow modules

Recurring agent workflows live in the repo, not in chat history.

1. MUST·whenRepositories that use shared skills, slash commands, or reusable AI workflow modules `MUST` version them in the repository.AIC-shared-skills-versioned
2. MUST·whenShared skills `MUST` be reviewed like code when they can change files, invoke tools, affect releases, or alter external systems.AIC-skill-code-review
3. MUST·whenShared skills `MUST` define their purpose, expected inputs, expected outputs, and meaningful side effects.AIC-skill-contract-defined
4. MUST·whenShared skills `MUST NOT` contain secrets, tokens, or environment-specific credentials.AIC-skill-no-secrets
5. SHOULDRepositories `SHOULD` separate project-shared skills from personal-only helpers.AIC-skill-shared-vs-personal
6. SHOULDShared skills `SHOULD` include usage examples for high-risk or non-obvious workflows.AIC-skill-usage-examples
7. MAYRepositories `MAY` group skills by domain such as implementation, review, release, migration, or incident response.AIC-skill-domain-grouping
8. MAYShared skills `MAY` include lightweight sample inputs or fixtures to make behavior easier to validate.AIC-skill-sample-fixtures

§19required at L2

MCP servers and external tool governance

Agents only get the tools they're meant to have. Tool catalogs are explicit and auditable.

1. MUST·whenRepositories that use MCP servers `MUST` explicitly approve which servers are allowed for team workflows.AIC-mcp-allowlist
2. MUST·whenEvery approved MCP server `MUST` have a defined owner and purpose.AIC-mcp-owner-purpose
3. MUST·whenOAuth- or token-based MCP integrations `MUST` use secure token handling and redirect validation appropriate to the platform.AIC-mcp-auth-security
4. MUST·whenMCP tools and servers `MUST` use least privilege.AIC-mcp-least-privilege
5. MUST·whenWrite-capable MCP servers `MUST` be distinguishable from read-only ones.AIC-mcp-write-vs-read-distinguishable
6. MUST·whenFilesystem roots and other exposed resources `MUST` be scoped deliberately to approved workspaces or data sources.AIC-mcp-root-scoping
7. SHOULDTeams `SHOULD` be able to identify which external systems an AI agent can read or mutate through MCP.AIC-mcp-auditability
8. SHOULDDev, staging, and production MCP connectors `SHOULD` be separated when they touch operational systems.AIC-mcp-env-separation
9. SHOULDMCP servers `SHOULD` be pinned to known versions or controlled deployment channels where possible.AIC-mcp-pinned-versions
10. SHOULDMCP prompts exposed as slash commands `SHOULD` be reviewed before being relied on operationally.AIC-mcp-prompt-review
11. SHOULDTeams `SHOULD` prefer read-only MCP access by default.AIC-mcp-read-only-default
12. SHOULDUsers `SHOULD` be prompted before exposing roots or other sensitive resources to MCP servers.AIC-mcp-root-prompt
13. MAYTeams `MAY` apply additional sandboxing, network isolation, or execution controls to third-party MCP servers.AIC-mcp-extra-sandboxing
14. MAYTeams `MAY` use the official MCP Registry for discovery, but they remain responsible for server vetting.AIC-mcp-registry-discovery

§20required at L2

Agents and delegation governance

Agents that act without per-step human approval are first-class subjects: they have identities, scopes, and audit trails.

1. MUST·whenParallel agents `MUST NOT` edit overlapping files unless the workflow explicitly defines coordination for that case.AIC-agent-parallel-isolation
2. MUST·whenAgents `MUST` have explicit tool, write, and approval limits.AIC-agent-permission-limits
3. MUST·whenAgent-produced changes `MUST` pass the same quality gates as any other code contribution.AIC-agent-quality-gates
4. MUST·whenRepositories that use autonomous or delegated agents `MUST` define agent roles, scope boundaries, ownership, and success conditions.AIC-agent-scope-defined
5. MUST·whenEvery material agent action `MUST` produce a record with, at minimum: agent identity, model identifier and model-version ID, prompt or skill version, ISO 8601 timestamp with seconds, and action category (read / write / merge / deploy / settings-change / external-call). The record location `MUST` be the same one documented for `AIC-prompt-audit-trail`. The record `MUST` be queryable: an auditor `MUST` be able to list material actions by agent, action category, or time range with one command or API query. Prose-only attribution ("our agents log to Linear") does not satisfy this rule.AIC-agent-action-traceability
6. SHOULDDelegation `SHOULD` be limited to bounded, well-scoped tasks.AIC-agent-bounded-delegation
7. MUST·whenRepositories that operate an autonomous runner `MUST` define and enforce escalation triggers before the runner performs destructive, security-sensitive, release-affecting, high-volume, or repeatedly failing actions. The triggers `MUST` include per-window action limits, a named escalation owner, and a response expectation or SLA for paused work.AIC-agent-escalation-trigger-enforcement
8. MUST·whenRepositories that operate an autonomous runner (any agent that can merge, deploy, release, rotate settings, or otherwise act without per-change human approval) `MUST` provide a kill switch: a single documented action that immediately halts the runner, by both disabling its execution path (workflow, scheduled job, agent harness) and revoking or expiring the runner's credentials so a residual process cannot continue acting. The kill switch `MUST` be exercisable without a code change to the repository. This complements `AIC-agent-cost-ceiling`, which addresses cost runaway; this clause addresses content runaway.AIC-agent-kill-switch
9. SHOULDTeams `SHOULD` define escalation paths for uncertainty around security, production systems, data handling, or architecture changes.AIC-agent-escalation-paths
10. SHOULDTeams `SHOULD` define standard agent roles such as implementer, reviewer, researcher, or release helper.AIC-agent-standard-roles
11. MUST·whenRepositories that operate an autonomous runner `MUST` document a rollback procedure for content the runner has already merged, deployed, or released. The procedure `MUST` rely on the authorship-traceability mechanism from `AIC-ai-authorship-traceability` so that runner-authored commits, releases, or settings changes are mechanically identifiable for revert without manual archaeology. Incident response (§29) may invoke this procedure.AIC-agent-rollback-procedure
12. SHOULDAgent outputs `SHOULD` be structured enough for safe handoff between agents and humans.AIC-agent-structured-outputs
13. SHOULDAgents `SHOULD` rely on repository-versioned instructions rather than hidden session state.AIC-agent-versioned-instructions
14. MAYTeams `MAY` benchmark agent roles on representative tasks.AIC-agent-benchmarking
15. MAYTeams `MAY` apply stronger sandboxing to higher-risk agents.AIC-agent-extra-sandboxing
16. MAYTeams `MAY` define trust tiers such as read-only, code-write, or release-capable agents.AIC-agent-trust-tiers

VI

⚠️AI Risk

§21–22 · 2 clauses

§21required at L2

AI-specific risks

Anything an agent reads can become an instruction. Untrusted sources are gated and marked.

1. MUST·whenRepositories that retain AI conversation context, tool outputs, or training-adjacent data `MUST` state retention limits and sanitization rules.AIC-ai-context-retention
2. MUST·whenRepositories whose AI workflows can introduce dependencies `MUST` define how those dependency additions are verified before use, including whether the package exists in the canonical registry and who owns it.AIC-ai-dependency-verification
3. MUST·whenRepositories that route work to external AI providers or models `MUST` maintain an explicit allowlist. Each entry `MUST` record its approval scope — permitted data classifications (consistent with §22) and action categories (read-only research, code authoring, release-affecting automation). Agent workflows `MUST NOT` route outside the allowlist.AIC-ai-provider-allowlist
4. MUST·whenRepositories that deploy agents exposed to untrusted input `MUST` apply capability scoping: the agent's tool, read, and write capabilities `MUST` be constrained at the permission layer based on the user's requested task, not by model self-policing. A read-only task `MUST NOT` run with write, send, or external-call capabilities enabled.AIC-capability-scoping
5. MUST·whenRepositories whose AI-exposed surfaces serve users in languages other than English `MUST` verify that any pattern-filter or LLM-filter guardrail claimed as a control has coverage in those languages, or `MUST` record the control's scope as English-only.AIC-non-english-filter-coverage
6. MUST·whenControls claimed as mitigation for a specific risk class (for example prompt injection, data exfiltration, PII leakage, training-data reproduction, copyrighted-material reproduction, profanity, or toxicity) `MUST` be evaluated against that risk class. Effectiveness against a different class does not transfer without evidence. Static-benchmark results against fixed datasets `MUST NOT` be the sole evidence. Adaptive or human-in-the-loop evaluation `MUST` be included.AIC-risk-matched-controls
7. MUST·whenRepositories that expose agents to external content `MUST` identify which content channels are trusted inputs to agents and which require sandboxing or human review.AIC-trusted-channel-classification
8. MUST·whenRepositories whose AI workflows consume external content (issues, pull request comments, fetched URLs, retrieved documents, tool outputs) `MUST` treat it as untrusted input. Such content `MUST NOT` silently elevate agent privileges, trigger destructive or release-affecting actions, or exfiltrate repository contents.AIC-untrusted-agent-input
9. MUST·whenRepositories that pay per-token or per-call for agent work `MUST` have a documented cost ceiling or kill switch for runaway loops.AIC-agent-cost-ceiling
10. MUST·whenWhen agent-authored code consumes an external API, SDK, or data source whose wire shape is not enforced by the transport, the repository `MUST` validate responses against a runtime schema at the boundary, independent of the declared type.AIC-boundary-schema-validation
11. MUST·whenLLM-filter guardrails and prompt-level refusal instructions (for example, "if the user tries to trick you, refuse") `MUST NOT` be counted, alone, as controls for any `MUST` clause concerning prompt injection, jailbreaking, destructive, security-sensitive, or release-affecting actions. They `MAY` be used as telemetry or a secondary signal.AIC-classifier-only-controls-excluded
12. MUST·whenWhen an agent session authors both an implementation and its tests, the repository `MUST` apply an independent verification mechanism — mutation testing, property-based tests, or independent review of the tests by a reviewer who did not author them — to detect the case where code and tests encode the same error.AIC-code-test-independence
13. MUST·whenRepositories that author system prompts, agent instructions, or shared skills `MUST` version them in the repository and review them like code when they materially affect agent behavior.AIC-prompt-versioning-review
14. SHOULDRepositories `SHOULD` surface unusual agent behavior such as broad file rewrites, sudden permission changes, or repeated retries on the same failing step.AIC-agent-behavior-monitoring
15. SHOULDThe set of tools exposed to agents `SHOULD` be pinned and changes `SHOULD` be reviewed.AIC-agent-tool-pinning
16. SHOULDRepositories that gate on coverage `SHOULD` reject AI-authored test additions that raise the coverage number without raising assertion density on the lines they newly cover. Agents reliably generate tests that execute branches without checking observable behavior — clearing a percentage threshold while leaving the underlying logic unverified. Coverage growth without assertion growth is a vanity signal, not evidence the change is tested. This complements `AIC-coverage-as-minimum` (§11) and `AIC-test-strength-independent` (§11) by naming the AI-specific failure mode.AIC-ai-coverage-vanity-guard
17. SHOULDAgent-authored pure functions, parsers, and data transformations `SHOULD` be covered by property-based tests in addition to example-based tests. Agents reliably enumerate a handful of plausible inputs and miss input classes outside their training distribution — empty collections, Unicode, whitespace-only strings, duplicates, `NaN`, negatives, overlong inputs. Stating the invariant forces the coverage that sampling skips.AIC-input-domain-property-coverage
18. SHOULDAgent workflows `SHOULD` derive the minimum required capability set from the user's requested task before the agent runs. Tasks that would combine read-from-untrusted-source and write-to-sensitive-sink capabilities in a single agent context `SHOULD` be rejected without an explicit approval step.AIC-minimum-capability-set
19. MAYRepositories `MAY` run agents in isolated workspaces, containers, or sandboxes when the blast radius of a mistake would be large.AIC-agent-isolated-workspaces
20. MAYRepositories `MAY` adopt model-output attestation or signing as agent-provenance tooling matures.AIC-model-output-attestation

§22required at L2

Data protection and privacy

Sensitive data does not leak into model providers, telemetry, or logs without intent.

1. MUSTRepositories `MUST` classify the data that flows through AI agents and tools: source code, secrets, customer data, regulated data, telemetry.AIC-ai-data-classification
2. MUST·whenRepositories whose AI workflows can expose regulated or secret data to provider context windows `MUST` prevent that data from entering any provider that is not explicitly approved for that data class.AIC-regulated-data-provider-gate
3. MUSTSecrets, credentials, and personally identifiable information `MUST` be redacted from AI-specific surfaces (prompts, agent transcripts, tool outputs, and AI-related error reports), extending the observability requirements of §13 to AI workflows.AIC-ai-surface-redaction
4. MUST·whenRepositories with data-residency requirements `MUST` verify that AI providers, MCP servers, and external tools respect those requirements.AIC-data-residency-verified
5. MUST·whenRepositories handling regulated data (health, finance, government, minors, and similar) `MUST` document the legal basis and controls for sending any such data to AI providers or external tools.AIC-regulated-data-controls
6. SHOULDRepositories `SHOULD` provide a safe, scrubbed fixture set for AI workflows that would otherwise require real data.AIC-ai-fixtures
7. SHOULDAccess to production data through AI workflows `SHOULD` be read-only unless a write path is explicitly designed and approved.AIC-ai-prod-data-readonly
8. MAYRepositories `MAY` adopt data minimization, synthetic-data generation, or differential-privacy techniques for AI workflows that require representative data.AIC-data-minimization-techniques

VII

🧭Oversight

§23–29 · 7 clauses

§23required at L1

Human approval and manual checkpoints

At every level above L1, humans hold the gate. What requires approval, and from whom, is written down.

1. MUSTThe repository `MUST` define which actions require explicit human confirmation. The baseline list `MUST` include every action that meets the Definitions of _destructive_, _security-sensitive_, or _release-affecting_; repositories may add more, but may not silently narrow these categories.AIC-human-approval-baseline
2. MUSTAI agents `MUST NOT` be allowed to silently perform destructive, security-sensitive, or release-affecting actions that the repository policy reserves for humans.AIC-no-silent-destructive-actions
3. MUST·whenRepositories that accept contributions from outside the documented contributor group `MUST` publish a disclosure policy for materially AI-authored pull requests and `MUST` enforce it during intake review. The policy `MUST` define what "materially AI-authored" means for the repository, how authorship is declared in the pull request, and how missing or incorrect declarations are handled.AIC-ai-authorship-disclosure-policy
4. SHOULDThe disclosure policy for materially AI-authored pull requests `SHOULD` specify the verification evidence expected — reproducible test output, screenshots of behavior, API traces, or equivalent — so reviewers can verify the change rather than re-generate it.AIC-disclosure-evidence
5. SHOULDThe repository `SHOULD` escalate approval requirements for migrations, deployment changes, auth changes, or repository-wide rewrites.AIC-escalated-approval-categories
6. SHOULDHuman approval `SHOULD` be required before commit or push in workflows where AI can generate large or cross-cutting changes.AIC-human-approval-large-changes
7. MAYTeams `MAY` add stronger sign-off requirements for regulated or high-impact systems.AIC-stronger-signoff-regulated

§24required at L1

Guardrail documentation and evidence

Claims about what agents can and cannot do are backed by evidence in the repository.

1. MUSTThe repository `MUST` document guardrails in one authoritative place.AIC-authoritative-guardrail-doc
2. MUSTAn automated check `MUST NOT` be counted as enforcing a requirement from this document unless its failure blocks merge on the change path it evaluates. Jobs configured to continue on evaluation failure, or to otherwise mask non-zero results from the protected-branch status, `MUST` be labelled as advisory in the guardrail documentation.AIC-gate-enforcement
3. MUSTIt `MUST` identify where each guardrail is defined and how failure is surfaced.AIC-guardrail-failure-surface
4. MUSTThat document `MUST` clearly state what is enforced automatically and what depends on review or process.AIC-machine-vs-manual-guardrails
5. MUSTA threshold, budget, or limit declared in configuration `MUST NOT` be counted as an automatic guardrail unless an automated check evaluates it on every change path that claims it.AIC-threshold-enforcement
6. SHOULDThe repository `SHOULD` maintain lightweight evidence that important guardrails are actually active, such as CI configuration, security settings, or documented repository policy.AIC-guardrail-active-evidence
7. MAYTeams `MAY` map this document to maturity models or external standards if organizational compliance requires it.AIC-guardrail-doc-maturity-mapping

§25required at L1

Policy governance

Someone, by name or role, owns the AI policy. It is not orphaned.

1. MUSTChanges to the adopted specification `MUST` go through the same review process as code, including required reviewers.AIC-policy-change-review
2. MUSTWhen a new AI-era risk becomes credible, the repository `MUST` decide whether to add or revise guardrails rather than treating the specification as frozen.AIC-policy-living-document
3. MUSTThe adopted specification itself `MUST` have a named owner and a documented review cadence.AIC-policy-owner-cadence
4. SHOULDThe repository `SHOULD` record the effective date and last review date of the adopted specification.AIC-policy-effective-dates
5. SHOULDThe repository `SHOULD` link each checklist item to the specific automation, configuration, or review step that enforces it, so conformance is auditable in practice.AIC-policy-evidence-links
6. MAYTeams `MAY` map this document to external standards or maturity frameworks when organizational compliance requires cross-referencing.AIC-policy-external-mapping

§26required at L2

AI-generated content: licensing and attribution

AI-authored work is attributed and licensed clearly.

1. MUSTWhere the hosting platform or CI allows it, the repository `MUST` provide a way to identify materially AI-authored commits or pull requests after the fact — for example a commit trailer, PR label, or metadata field. The mechanism `MUST` be documented in the same place as the licensing declaration.AIC-ai-authorship-traceability
2. MUSTThe repository `MUST` declare its position on license and ownership for AI-generated content in a durable document (for example `CONTRIBUTING.md`, `LICENSING.md`, or the authoritative AI instruction file from §17). The declaration `MUST` say whether AI-generated code, documentation, and tests are accepted, and under what license they are contributed.AIC-ai-output-licensing-declaration
3. MUST·whenRepositories where AI materially authors code that ships `MUST` record, for every material AI-generated change: the model identifier, the prompt or system-prompt version, and any skill version used. The record location (commit trailer, PR body field, release manifest, audit-log row, or equivalent) `MUST` be documented with the `AIC-ai-authorship-traceability` mechanism. The record `MUST` be queryable: an auditor `MUST` be able to list AI-authored changes by model, prompt version, or skill version with one command or API query. This makes `AIC-ai-authorship-traceability` concrete for L3+ and supports `AIC-agent-rollback-procedure`.AIC-prompt-audit-trail
4. SHOULDThe repository `SHOULD` record the model identifier on material AI-generated changes so provenance can be reconstructed if a downstream licensing question arises. Below L3 this remains a SHOULD; at L3+ it is covered by `AIC-prompt-audit-trail`.AIC-ai-model-provenance
5. SHOULDThe repository `SHOULD` align its AI-authorship disclosure policy (§23) with the licensing declaration in this section so contributors see a single, consistent story for both attribution and legal status.AIC-licensing-disclosure-alignment
6. MAYThe repository `MAY` require contributors to retain prompts, tool outputs, or other inputs that produced material AI-generated changes for a defined period, where audit or regulatory needs justify it.AIC-ai-input-retention

§27required at L3

AI credential lifecycle

Credentials issued to agents are short-lived, scoped, and revocable.

1. MUST·whenAn agent `MUST NOT` be the sole approver of a credential rotation or revocation that affects production systems or any sensitive sink. Approval `MUST` come from a human reviewer per §23.AIC-agent-credential-not-sole-approver
2. MUST·whenAgent-initiated credential creation, rotation, and revocation `MUST` produce a durable audit record naming the agent, the human approver (per §23), the credential class, and the scope of the change.AIC-agent-credential-audit
3. MUST·whenRepositories whose agents can create, rotate, or revoke credentials `MUST` enumerate which credential classes the agent is allowed to operate on. Agent operations on classes outside that enumeration `MUST NOT` be permitted.AIC-agent-credential-class-scope
4. SHOULDRepositories `SHOULD` rotate any credential the agent demonstrably read from a transcript, tool output, or context window before continuing operations. The §22 redaction rules limit exposure; this rule treats observed exposure as a rotation trigger.AIC-agent-observed-credential-rotation
5. SHOULDCredentials issued or rotated by an agent `SHOULD` be short-lived where the platform supports it, consistent with §8's deployment-credential rule.AIC-agent-credential-short-lived
6. MAYRepositories `MAY` constrain agent credential operations to a separate role or harness identity distinct from the human-operator identity, so agent operations are distinguishable in audit logs.AIC-agent-credential-distinct-identity

§28required at L3

AI model and provider deprecation

Switching the model is a code change, not a config tweak slipped past review.

1. MUST·whenWhen a vendor changes the data classifications or action categories an entry was approved for under §21 and §22, the entry's approval scope `MUST` be re-evaluated before agent workflows continue using it.AIC-allowlist-rescope-on-terms-change
2. MUST·whenAgent workflows `MUST NOT` continue routing to a deprecated or sunset entry past its end-of-life date without explicit re-approval recorded against the §21 allowlist.AIC-no-routing-past-eol
3. MUST·whenThe repository `MUST` define a procedure for evaluating an allowlist entry when the vendor announces deprecation, sunset, ownership change, or material terms-of-service change. The procedure `MUST` state who decides, on what evidence, and within what window.AIC-provider-deprecation-procedure
4. SHOULDThe repository `SHOULD` track the published end-of-life or deprecation status of allowlisted models and providers in the same place as the allowlist itself, so the dependency on third-party lifecycles is visible.AIC-provider-eol-tracked
5. SHOULDThe repository `SHOULD` plan a fallback path — an alternative allowlisted entry, a documented degradation mode, or an explicit pause of the affected workflow — before relying on a model or provider whose continuity is uncertain.AIC-provider-fallback-path
6. MAYRepositories `MAY` subscribe to vendor deprecation channels and surface notices in repository tooling rather than relying on out-of-band communication.AIC-provider-deprecation-feed

§29required at L3

AI incident response and guardrail-update loop

AI-driven incidents are first-class. There is a known way to stop, investigate, and learn from them.

1. MUST·whenRepositories that operate AI agents in production paths `MUST` define what counts as an AI-attributable incident, who triages it, and what evidence is preserved.AIC-ai-incident-definition
2. MUST·whenAfter an AI-attributable incident, the repository `MUST` run a review that identifies the agent action that caused the harm, the control that should have prevented it, and whether that control existed, was bypassed, or was missing.AIC-ai-incident-review
3. MUST·whenIf the incident review identifies a missing or weakened control, the guardrail documentation under §24 `MUST` be updated to reflect the new or strengthened control before similar agent work resumes.AIC-incident-guardrail-update
4. SHOULDIncident reviews `SHOULD` record the model identifier, prompt or skill version, and tool set involved, consistent with `AIC-prompt-audit-trail` (§26, MUST when applicable for L3+) and `AIC-ai-model-provenance`, so the review is reproducible against the same operating context.AIC-incident-context-recorded
5. SHOULDRepositories `SHOULD` cross-link the incident record from the affected guardrail's evidence under §24, so future readers see the lineage from incident to control change.AIC-incident-evidence-lineage
6. MAYRepositories `MAY` operate a public or internal post-mortem cadence for AI-attributable incidents to share lessons across teams.AIC-incident-postmortem-cadence

end of specification · v0.1.2