# Docs Reference Contract

How `docs/*` paths inside `.claude/agents`, `.claude/skills`, `.claude/commands`, `.claude/memory`, `.claude/hooks`, `.claude/scripts`, `.claude/rules`, `.claude/rules-conditional`, and `.claude/modes` are resolved at runtime, and which paths are allowed to appear.

## Two-Tier Resolution

`.claude/` is the project-local agent tree that exists in this project (and is shipped into other projects by the kit's installer). Files outside `.claude/` (under any `docs/` tree at the kit's source repo) are NOT shipped. Every `docs/*` reference inside a shipped file resolves under one of two interpretations:

1. **Target-project doc** — the path is read from (or written to) the USER's project root, not the source kit's repo. These are generated by `mk:docs-init`, `mk:project-context`, `mk:document-release`, `mk:ui-ux-designer`, `mk:architect`, `mk:journal-writer`, `mk:retro`, `mk:ship`, `mk:plan-ceo-review`, and similar producer skills. Reading agents MUST handle the absent case gracefully (see Graceful-Degradation Pattern below).

2. **Kit-internal doc** — the path points at a file that lives in the source kit repo but does NOT ship into projects. **This form is forbidden in shipped files.** Internal policy belongs in `.claude/rules/`; load-bearing snippets must be inlined into the consuming file; attribution belongs in plain prose without a path.

## Type-1 Allowlist (target-project docs)

These paths and prefixes are allowed in `.claude/` files because consumers and producers agree on the convention.

<!-- ALLOWLIST-START -->
docs/project-context.md
docs/project-overview.md
docs/project-changelog.md
docs/codebase-summary.md
docs/code-standards.md
docs/deployment-guide.md
docs/development-roadmap.md
docs/usage.md
docs/changelog.md
docs/api-reference.md
docs/components.md
docs/modules.md
docs/setup.md
docs/cost-report.md
docs/design-guidelines.md
docs/architecture/
docs/architecture/adr/
docs/architecture/system-architecture.md
docs/architecture/NNNN-title.md
docs/architecture/adr/YYMMDD-title.md
docs/journal/
docs/journal/YYMMDD-title.md
docs/wireframe/
docs/designs/
docs/retros/
docs/rollback/
<!-- ALLOWLIST-END -->

The block above is parsed by the validator. One path per line. Comment lines (starting `#`) are ignored. Prefix matches use the trailing `/`.

### Reserved future paths (WARN, not ERROR)

<!-- RESERVED-START -->
<!-- (none today — add here when a producer skill ships a new generated path before the consumer is updated) -->
<!-- RESERVED-END -->

## Banned Patterns

### Banned — kit-internal-doc paths in shipped files

Do NOT reference any of the following from `.claude/`:

- `docs/dead-weight-audit.md`
- `docs/red-team-overview.md`
- `docs/operations/harness-runbook.md`
- `docs/memory-system.md`
- `docs/branding-style-guide.md`
- `docs/research/<anything>`
- `docs/reference/<anything>`
- `docs/explanation/<anything>`
- `docs/jira-as/<anything>`
- `docs/governance/<anything>`
- `docs/archive/<anything>`
- Any other path under a `docs/` tree that is not on the Type-1 allowlist above

If load-bearing content from one of these files is needed at runtime, choose ONE:

- Inline the relevant snippet directly into the SKILL.md / rule file (preferred when ≤30 lines)
- Move the snippet into a new file under `.claude/rules/` (when ≥30 lines and policy-shaped)
- Drop the link entirely if the surrounding prose already conveys the necessary context

### Banned — citation paths

A path that exists only to credit a source (footnote citation) is banned. Replace with plain prose:

```
Bad:  Source: effective-context-engineering (docs/research/effective-context-engineering-for-ai-agents.md)
Good: Source: Anthropic — Effective Context Engineering for AI Agents
```

### Banned — relative paths up into a non-shipped `docs/` tree

`../../../docs/<anything>` (or any number of `../`) is banned. The same Type-1/kit-internal contract applies regardless of how the path is written.

## Graceful-Degradation Pattern

When an agent or skill reads a Type-1 target-project doc, it MUST handle the absent case without stalling or hallucinating content. The canonical pattern is from `agents/project-manager.md`:

```
- docs/project-context.md — project conventions (may be absent; proceed without it, note in report)
```

Tag missing reads as `(CF-C5)` in any output that depends on the missing data.

This contract does NOT mandate that all existing agents adopt the pattern in one PR — that's a separate generalization task. New skills MUST follow it.

## Skill-Author Checklist

Before adding a `docs/*` reference to any file under `.claude/`:

1. Is the target generated in the USER's project by a producer skill? → Type-1. Add the path to the allowlist if missing, otherwise just use it.
2. Is the target a kit-internal policy file? → Banned. Inline the policy or drop the link if context is enough.
3. Is the target a research / attribution source? → Banned. Use plain prose ("Source: <Author> — <Title>").
4. Is the target a template placeholder example? → Use an angle-bracket placeholder `<path-to-related-doc-in-your-project>`, not a literal path.
5. Run the validator after editing: `.claude/scripts/check-docs-references.py` (Python CLI), or the equivalent native check exposed by the kit's `validate` command.

## Validator

Two implementations consume this contract:

- A TypeScript-native check exposed by the kit's `validate` command (runs without any external dependency).
- A standalone Python script at `.claude/scripts/check-docs-references.py` (CI convenience and direct CLI use).

Both parse the `<!-- ALLOWLIST-START -->` / `<!-- ALLOWLIST-END -->` block above as the single source of truth. They must produce identical output on identical input — a cross-implementation parity test in CI guards against drift.

## Cross-References

- `.claude/rules/skill-authoring-rules.md` Rule 5 — mandates compliance with this contract for every new skill or agent
