Pillar — Documentation & Knowledge

Prefix: DOC- Catalog: v1.1 deltas (additive to v1.0 Documentation & Knowledge). What it measures: whether an agent spawned at the root of a product portfolio can find the map, the per-application rules, the shared-package contracts, and the decisions that bind those applications together — without inferring them from scattered files.

v1.0 already covers a substantive README, stated purpose, a root AGENTS.md / CLAUDE.md, environment docs, ADRs, runbooks, API references, and a changelog. These v1.1 criteria add the portfolio-scale documents an agent needs once it is changing more than one application in the same product.

Criteria in this pillar

DOC-100 — Per-application agent-context file

Level: 2 · Scope: portfolio · Check: deterministic
Every application directory in the portfolio has an AGENTS.md, CLAUDE.md, or equivalent agent-context file that names that application's stack, commands, and constraints. A root-only context file does not satisfy this criterion.
Rationale: DOC-030 at the repository root is necessary and not sufficient once an agent hops between applications. Conventions that live only at the root are overwritten by the last application the agent read.
Evidence expected: each application path has a context file; CI or a lint script fails an application added without one; a root file may exist and MUST NOT be the only one.

DOC-110 — Portfolio map in the root README

Level: 2 · Scope: portfolio · Check: deterministic
The repository-root README lists every application in the subject, with a one-line purpose, the path, and the primary start or assess command. The list is the same set of applications the scorecard scores.
Rationale: agents spawned at the root need a map, not a scavenger hunt. A README that describes one application in a six-application product sends the agent into the wrong tree.
Evidence expected: README table or list of applications; paths resolve; the set matches the portfolio manifest or scorecard subject list.

DOC-120 — Shared-package consume contract documented

Level: 3 · Scope: portfolio · Check: deterministic
Every published workspace package (or equivalent shared library) has a README or docs page that states how to import it, the supported surface, and the compatibility policy. An undocumented package is not a contract an agent may extend.
Rationale: portfolio subjects share code. An agent that "fixes" a package without a consume contract will invent a new public surface and break every application that imported the old one.
Evidence expected: README or docs path per published package; at least one import example; compatibility or semver policy named.

DOC-130 — Environment inventory classifies secrets

Level: 3 · Scope: application · Check: deterministic
The environment table (DOC-040) classifies each variable as compile-time, runtime, or secret. Secret names appear; secret values do not. Compile-time entries match the set used for secret-free build proof (BLD-110).
Rationale: a flat list of env names does not tell an agent which values it may put in CI and which must stay in the vault. Misclassification is how credentials leak into build logs.
Evidence expected: env table or .env.example comments with the three classes; no secret values committed; compile-time names match the documented build-time manifest.

DOC-140 — Cross-application decisions recorded

Level: 3 · Scope: portfolio · Check: deterministic
Architecture decision records (DOC-050) include at least one decision that names two or more applications in the portfolio (shared auth, shared data store, deploy topology, or equivalent). An ADR folder that only records single-application choices does not cover the product.
Rationale: the hard constraints in a portfolio live between applications. Agents re-litigate those boundaries unless a decision record says they are settled.
Evidence expected: docs/adr (or equivalent) contains a cross-application ADR; the ADR names the applications; the index lists it.

v1.0 Documentation & Knowledge — the published DOC-010 through DOC-080 criteria.
v1.1 pillars — draft catalog, including these deltas and the six new pillar stubs.
v1.0 specification — the published standard.

Criteria in this pillar

Level: 2 · Scope: portfolio · Check: deterministic

Every application directory in the portfolio has an AGENTS.md, CLAUDE.md, or equivalent agent-context file that names that application's stack, commands, and constraints. A root-only context file does not satisfy this criterion.

Rationale: DOC-030 at the repository root is necessary and not sufficient once an agent hops between applications. Conventions that live only at the root are overwritten by the last application the agent read.

Evidence expected: each application path has a context file; CI or a lint script fails an application added without one; a root file may exist and MUST NOT be the only one.

Level: 2 · Scope: portfolio · Check: deterministic

The repository-root README lists every application in the subject, with a one-line purpose, the path, and the primary start or assess command. The list is the same set of applications the scorecard scores.

Rationale: agents spawned at the root need a map, not a scavenger hunt. A README that describes one application in a six-application product sends the agent into the wrong tree.

Evidence expected: README table or list of applications; paths resolve; the set matches the portfolio manifest or scorecard subject list.

Level: 3 · Scope: portfolio · Check: deterministic

Every published workspace package (or equivalent shared library) has a README or docs page that states how to import it, the supported surface, and the compatibility policy. An undocumented package is not a contract an agent may extend.

Rationale: portfolio subjects share code. An agent that "fixes" a package without a consume contract will invent a new public surface and break every application that imported the old one.

Evidence expected: README or docs path per published package; at least one import example; compatibility or semver policy named.

Level: 3 · Scope: application · Check: deterministic

The environment table (DOC-040) classifies each variable as compile-time, runtime, or secret. Secret names appear; secret values do not. Compile-time entries match the set used for secret-free build proof (BLD-110).

Rationale: a flat list of env names does not tell an agent which values it may put in CI and which must stay in the vault. Misclassification is how credentials leak into build logs.

Evidence expected: env table or .env.example comments with the three classes; no secret values committed; compile-time names match the documented build-time manifest.

Level: 3 · Scope: portfolio · Check: deterministic

Architecture decision records (DOC-050) include at least one decision that names two or more applications in the portfolio (shared auth, shared data store, deploy topology, or equivalent). An ADR folder that only records single-application choices does not cover the product.

Rationale: the hard constraints in a portfolio live between applications. Agents re-litigate those boundaries unless a decision record says they are settled.

Evidence expected: docs/adr (or equivalent) contains a cross-application ADR; the ADR names the applications; the index lists it.