# Generated Output Policy

This repository distinguishes source artifacts from generated output, local
caches, provider exports, and deploy artifacts. The rule is simple: generated
or machine-local state should be reproducible from tracked source and should not
be committed unless it is explicitly listed as tracked source below.

## Categories

| Category | Examples | Git Policy | Cleanup |
| --- | --- | --- | --- |
| Product source | `src/`, `tools/`, `agentic/code/**`, root `templates/`, root `schemas/`, root `config/` | Tracked. | Not removed by cleanup commands. |
| Project records | `.aiwg/architecture/`, `.aiwg/requirements/`, `.aiwg/reports/`, `.aiwg/testing/`, and other paths listed in `.aiwg/README.md` | Tracked when they are intentional project evidence. | Not removed by cleanup commands. |
| Build/test output | `dist/`, `build/`, `coverage/`, `test-output/`, `test-results/`, `.pytest_cache/` | Ignored and not tracked. | `npm run clean:build` or `npm run clean:local`. |
| Provider exports | `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.factory/`, `.opencode/`, `.warp/`, `.windsurf/`, `.hermes/`, `.devin/`, `opencode.json` | Ignored and not tracked; generated by `aiwg use` or provider deployment tooling. | `npm run clean:providers` when the operator wants to remove local exports. |
| AIWG indexes/caches | `.aiwg/.index/`, `.aiwg/.storage-cache/`, `.rlm-prep/` | Ignored and not tracked; reproducible or host-local. | `npm run clean:local`. |
| AIWG runtime and local state | `.aiwg/working/`, `.aiwg/ralph/`, `.aiwg/ralph-external/`, `.aiwg/issues/`, `.aiwg/frameworks/*/`, `.aiwg/marketing/`, `.aiwg/forensics/`, `.aiwg/research/synthesis/` | Ignored for new files unless a documented project-record exception already exists. | Clean only with a task-specific review; some directories can contain active local work. |
| Static docs assets | `docs/.public/**` | Tracked. These are source-controlled static assets used by the docs site, not disposable build output. | Not removed by cleanup commands. |
| Published docs build output | `docs/.public` generated by downstream site tooling outside this repo, `tenants.json` from CI tenant registry generation | Do not track generated outputs unless the files are static docs assets intentionally committed here. | Regenerate in the docs publishing pipeline. |

## Cleanup Commands

| Command | Removes | Preserves |
| --- | --- | --- |
| `npm run clean` | Alias for `npm run clean:build`. | Source, project records, provider exports. |
| `npm run clean:build` | `dist`, `build`, `coverage`. | Local provider exports and AIWG cache state. |
| `npm run clean:local` | Build/test outputs plus `.aiwg/.index`, `.aiwg/.storage-cache`, and `.rlm-prep`. | Source, project records, provider exports. |
| `npm run clean:providers` | Local provider export directories and provider root files. | Source and project records. |

Do not make `clean` remove provider exports by default. Those directories are
generated, but they may be the local surface an operator is actively testing.

## Validation

`npm run lint:generated-artifacts` fails if git tracks generated/cache/provider
output paths such as `dist/`, `coverage/`, provider export directories,
`.aiwg/.index/`, `.aiwg/.storage-cache/`, or `.rlm-prep/`.

The CI workflow runs this check after schema linting. If a future generated path
must be tracked, add an explicit allowlist entry in
`tools/lint/tracked-generated-artifacts.mjs` and document the reason here.

`.aiwg/README.md` is the canonical taxonomy for project-state paths under
`.aiwg/`, including the distinction between tracked project records,
historical archive material, ignored working drafts, and local issue/runtime
state.

## Adding New Output Paths

When adding a command that writes files:

1. Decide whether each output is source, project evidence, generated output,
   cache, provider export, or deploy artifact.
2. Add ignored generated/cache/provider paths to `.gitignore`.
3. Add safe cleanup coverage to the narrowest cleanup command.
4. Add generated tracked-path protection to
   `tools/lint/tracked-generated-artifacts.mjs`.
5. Document any intentionally tracked generated-looking path in this policy.