# Source of Truth and Agent Learning

Open Orchestra should make context provenance explicit. Agents and subagents should know where to look before acting, and they should record repeatable failure lessons after an action fails.

## Source of Truth Catalog

The source catalog answers: which document, file, or external reference is authoritative for a decision?

Default source groups:

- `project-instructions`: `AGENTS.md`, `ORCHESTRA.md`, `CLAUDE.md`, Cursor rules, and local agent rules.
- `product-backlog`: GitHub issues, local backlog docs, acceptance criteria, user stories, and task graph state.
- `architecture`: ADRs, architecture docs, service boundaries, diagrams, domain models, and integration contracts.
- `codebase`: source files, tests, package manifests, config, generated types, and local command contracts.
- `quality-security`: static analysis config, pre-commit hooks, SAST reports, dependency scans, secret scans, QA plans, and Playwright evidence.
- `devops-runtime`: CI/CD workflows, deployment docs, IaC, observability, rollback, incident, and release artifacts.
- `vendor-docs`: official provider, framework, package, cloud, and browser documentation.
- `agent-memory`: decisions, handoffs, evidence, prompt registry entries, and lessons learned.

Rules:

- Prefer local project sources before generic external guidance.
- Prefer primary vendor documentation over blogs, examples, or generated answers.
- For current or fast-changing APIs, verify against official docs before implementation.
- Record which source group justified a material decision in decisions, handoffs, evidence, or final summaries.
- If sources conflict, stop and record the conflict instead of silently choosing one.

## Versioning Policy

- Track the schema, documentation, examples, and promoted rules or skills.
- Do not track the live `.agent-workflow/agent-lessons.jsonl` file by default; it is local runtime state and can contain machine-specific commands, timestamps, paths, or sensitive context.
- Do not track the live `.generated-prompts/` directory by default; prompt registers are generated local runtime memory unless a project explicitly promotes selected entries into versioned docs, rules, or skills.
- Track `source-of-truth.json` only when a project intentionally wants shared authoritative sources. Otherwise regenerate it through `orchestra init` and project config.
- Promote repeated lessons into versioned skills or rules after review.

## Agent Lessons Log

The lessons log captures operational mistakes that an agent can avoid next time. It is not a blame log; it is a repeat-prevention mechanism.

Store lessons as JSONL in `.agent-workflow/agent-lessons.jsonl`.

Example entry:

```json
{
  "timestamp": "2026-05-03T00:00:00.000Z",
  "taskId": "SKILL-001",
  "actor": "parent",
  "operation": "edit-doc-with-node-script",
  "failedAction": "embedded Markdown fences inside a JavaScript template literal",
  "errorSignature": "SyntaxError: Unexpected identifier",
  "rootCause": "unescaped backticks in generated script content",
  "fix": "build long Markdown content as an array of lines or escape fences explicitly",
  "prevention": "before running generated edit scripts, scan for nested template literals and Markdown fences",
  "appliesTo": ["node", "markdown", "code-generation"],
  "verifiedBy": ["reran edit script successfully"]
}
```

Record a lesson when:

- The same class of failure is likely to happen again.
- A command failed because of quoting, escaping, shell behavior, permissions, cwd, missing dependency, or stale assumption.
- A test failure revealed a reusable project convention.
- A provider, tool, or runtime behaved differently than expected.

Do not record a lesson for:

- One-off typos with no reusable prevention value.
- Secrets, raw credentials, private customer data, or sensitive prompt/response content.
- Failures already covered by a current lesson unless the prevention changed.

## Learning Flow

1. Before acting, select relevant source groups and load only the necessary files or docs.
2. Before repeating a risky operation, search `.agent-workflow/agent-lessons.jsonl` for matching operation, error signature, or tool.
3. After a failure, classify whether it is reusable knowledge.
4. If reusable, append one JSONL entry with root cause, fix, prevention, and verification.
5. If the same lesson appears repeatedly, promote it into the relevant skill or project rule.

## Memory Governance

Local memory is useful only while it stays bounded, current, and safe to load
into future agent context. Use `orchestra memory governance` to inspect active,
archived, stale, and sensitive lessons. Use `orchestra lessons prune --dry-run`
before applying retention cleanup, then run without `--dry-run` to archive stale
or overflow lessons.

Use `orchestra lessons archive --id <lesson-id>` when a lesson is superseded but
still useful as audit history. Use `orchestra lessons redact --id <lesson-id>`
when a stored lesson contains token-like or secret-shaped values. Use
`orchestra lessons delete --id <lesson-id>` only when the record should be
removed from local memory entirely.

## Relationship to Skills

Skills should declare which source groups they use and which lessons are relevant. The orchestrator should load lessons only for the selected skills and current operation, not the full historical log.