# Current Repo Sync Matrix

Use this matrix to decide where the real edit belongs and which copies must be refreshed afterwards.

If the target repository is a thin install project and `docs/harness/*`, `docs/testing/*`, or `docs/knowledge/*` are absent from the project root, inspect the same relative paths under `packageRoot` from `.codex-harness/state/config.json`.

## 1. Root Runtime And Driver Truth Sources

Canonical source:

- repo root:
  - `AGENTS.md`
  - `bootstrap-codex-harness.ps1`
  - `codex-loop.ps1`
  - `doctor.ps1`
  - `verify.ps1`
  - `.codex/task-run-profile.json`
  - `.codex/prompts/*.md`
  - `project-task-template.json`
  - `docs/harness/*`
  - `docs/testing/*`

Typical mirrors:

- `agent/*`
- `.agents/*`
- `agent/docs/codex-harness-engineering/templates/runtime/*`
- `.agents/docs/codex-harness-engineering/templates/runtime/*`
- `agent/docs/codex-harness-engineering/templates/docs/*` or `templates/testing/*` when the source is under `docs/harness/*` or `docs/testing/*`

Special runtime-governance case:

- `scripts/harness/harness-governance-check.ps1` is a root runtime governance script.
- Required mirrors:
  - `docs/codex-harness-engineering/templates/scripts/harness/harness-governance-check.ps1`
  - `docs/codex-harness-engineering/templates/package-assets/scripts/harness/harness-governance-check.ps1`
- If its behavior changes subdirectory `AGENTS.md` auto-refresh, also refresh:
  - `docs/codex-harness-engineering/templates/docs/governance-auto-repair.md`
  - `docs/codex-harness-engineering/templates/package-assets/docs/harness/governance-auto-repair.md`
  - `agent/docs/codex-harness-engineering/implementation-flow.md`
  - `agent/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/implementation-flow.md`

## 2. Active Role Rules

Canonical source:

- `.codex/rules/agents.md`

Typical mirrors:

- `agent/.codex/rules/agents.md`
- `agent/docs/codex-harness-engineering/templates/config/rules/agents.md`
- `agent/docs/codex-harness-engineering/templates/package-assets/rules/agents.md`
- `.agents/docs/codex-harness-engineering/templates/config/rules/agents.md`
- `.agents/docs/codex-harness-engineering/templates/package-assets/rules/agents.md`

## 3. Human-Facing Harness And Package Docs

Canonical source:

- `agent/docs/codex-harness-engineering/*.md`

Typical mirrors:

- `agent/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/*.md`
- `.agents/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/*.md`
- `cli/package-source/docs/codex-harness-engineering/*.md` after syncing CLI package source

Special case:

- `docs/harness/spec-to-ui-to-code-workflow.md` often also feeds:
  - `agent/docs/harness/spec-to-ui-to-code-workflow.md`
  - `agent/docs/codex-harness-engineering/spec-to-ui-to-code-workflow.md`
  - `agent/docs/codex-harness-engineering/templates/docs/spec-to-ui-to-code-workflow.md`
  - package-assets doc mirrors

## 4. Template Config

Canonical source:

- `agent/docs/codex-harness-engineering/templates/config/*`

Typical mirrors:

- `.agents/docs/codex-harness-engineering/templates/config/*`
- `cli/package-source/docs/codex-harness-engineering/templates/config/*` after syncing CLI package source

Common targets:

- `codex-config.toml`
- `codex-readme.md`
- `codex-agent-roles.md`
- `global-AGENTS.md`
- `agents/*.toml`

## 5. Package-Assets Workflows

Canonical source:

- `agent/docs/codex-harness-engineering/templates/package-assets/workflows/*`

Typical mirrors:

- `.agents/docs/codex-harness-engineering/templates/package-assets/workflows/*`
- `cli/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/*` after syncing CLI package source

## 6. Package-Assets Root Docs

Canonical source:

- `agent/docs/codex-harness-engineering/templates/package-assets/root/*`

Typical mirrors:

- `.agents/docs/codex-harness-engineering/templates/package-assets/root/*`
- `cli/package-source/docs/codex-harness-engineering/templates/package-assets/root/*` after syncing CLI package source

## 7. Repo Skills

Canonical source for active usage:

- `.agents/skills/<skill-name>/...`

Distribution mirrors:

- `agent/skills/<skill-name>/...`
- `agent/docs/codex-harness-engineering/templates/package-assets/skills/<skill-name>/...`
- `.agents/docs/codex-harness-engineering/templates/package-assets/skills/<skill-name>/...`

When a skill is created or updated, refresh the `agent/skills` copy and both package distribution copies before considering the task done.

## 8. CLI Package Source

Canonical source:

- repo root files included by `cli/lib/release/package-source-layout.js`

Required refresh step:

- run `node tools/release/sync-cli-package-source.mjs`

Expected targets:

- `cli/package-source/install-manifest.json`
- `cli/package-source/tools/install/*`
- `cli/package-source/docs/codex-harness-engineering/templates/context/*`
- `cli/package-source/docs/codex-harness-engineering/templates/docs/*`
- `cli/package-source/docs/codex-harness-engineering/templates/package-assets/*`

If a change is intended to ship through the npm CLI package, updating root templates alone is incomplete until `cli/package-source/` is refreshed.
