singularity-forge/docs/dev/generated-artifact-policy.md

# Generated Artifact Policy

SF keeps operational generated artifacts out of the project root unless a human
explicitly promotes them into durable project documentation.

## Default Locations

- `.sf/` stores SF-local operational state, generated harness notes, scaffold
  manifests, runtime caches, locks, temporary agent files, and generated
  orientation caches such as `.sf/repo-map/`.
- `docs/plans/`, `docs/specs/`, and `docs/adr/` store promoted or generated
  human-facing exports for review and git history.
- `docs/generated/` stores explicitly promoted generated documentation when a
  project wants a generated artifact in version control.
- Generated docs may change by design. Git keeps their human-facing history;
  SF-owned operational history belongs in `.sf`/SQLite when runtime replay,
  ledgers, memory, or drift analysis matter.
- Root files such as `AGENTS.md`, `ARCHITECTURE.md`, and `.siftignore` are
  allowed only when they are part of the versioned scaffold contract.

## Resource Layers

SF follows the same separation as Copilot-style agent customization:

| Layer | Path | Git ownership | Purpose |
|---|---|---|---|
| Bundled SF resources | `src/resources/skills/`, `src/resources/workflow-skills/`, `src/resources/agent-overlays/`, `src/resources/extensions/sf/prompts/`, `src/resources/extensions/sf/` | tracked source | Product-shipped defaults. Change these to change SF itself. Workflow skills are hidden system patterns, not a general skill catalog. |
| Repo agent overlay | `.agents/` | tracked project policy | Project-owned prompts, policies, and optional user skill overrides. Same-name skills override non-locked bundled skills. |
| Repo instructions | `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | tracked project policy | Agent-facing repo guidance. Keep short, durable, and non-runtime. |
| Runtime generated context | `.sf/repo-map/`, `.sf/traces/`, `.sf/backups/`, `.sf/metrics.db*` | gitignored | Local cache, observability, recovery, and orientation. Safe to delete/regenerate. |
| Promoted generated docs | `docs/generated/` | tracked after review | Durable generated docs that humans chose to version. |

`.sf/repo-map/` is not a source of truth. It is a generated context cache for
agent orientation. If a repo-map page becomes valuable as documentation, promote
it to `docs/generated/repo-map/` or rewrite it into normal `docs/`.

## Prompt and Instruction Layers

Prompt resources follow the same split:

- **Built-in prompts:** `src/resources/extensions/sf/prompts/` and other
  bundled resource directories. These ship with SF and should be edited only
  when changing product behavior.
- **Built-in repo defaults:** `src/resources/agent-overlays/` contains product
  defaults that SF ships, including default repo prompts and default policies.
- **Repo prompts and instructions:** `.agents/prompts/`, root `AGENTS.md`,
  root `CLAUDE.md`, and compatible tool files such as
  `.github/copilot-instructions.md`. `.agents/prompts/` is for repo-owned
  overrides only; root instruction files remain durable human-readable pointers.
- **Path-specific instructions:** use repo instruction files when behavior
  should apply only to part of the tree. Keep them stable and reviewable.
- **Generated context:** `.sf/repo-map/` and other `.sf/` runtime outputs are
  not prompt source. They may be injected as context when fresh, but they are
  ignored and regenerable.

Do not promote generated `.sf` context by copying it into prompt overlays
verbatim. Summarize the durable rule, link the canonical source, and keep the
overlay short enough to be loaded every run.

## SF `.agents` Overlay

Until the external `.agents` specs settle, this repo uses
`sf-agents-overlay/v1`:

- `.agents/manifest.yaml` is the repo-owned machine index for optional prompt,
  policy, mode, adapter, and project skill overrides.
- `.agents/prompts/`, `.agents/policies/`, `.agents/modes/`,
  `.agents/adapters/`, `.agents/scopes/`, and `.agents/profiles/` are empty by
  default. Defaults live in `src/resources/`.
- `.agents/skills/<name>/SKILL.md` is the canonical skill payload and follows
  the Agent Skills specification.
- `.agents/skills/` is empty by default. SF product-owned user skills live under
  `src/resources/skills/`; automatic workflow guidance lives under
  `src/resources/workflow-skills/` as hidden system pattern skills.
- SF self-learning is per repo: runtime evidence and candidate variants belong
  in `.sf` / SQLite first, reviewed repo-specific improvements are proposed as
  `.agents/` overrides, and bundled defaults under `src/resources/` change only
  when the improvement is product-wide.
- `.agents/skills/<name>/skill.yaml` is optional compatibility metadata for
  projection tools. It may point at `SKILL.md`, but it must not replace it as
  the instruction source.
- `.agents/state/state.yaml` is local convenience state and must remain
  gitignored.
- `.sf/` remains SF runtime state. Structured SF state stays DB-first.

## Harness

Generated harness material belongs under `.sf/harness/`.

Top-level `harness/` is not created by SF by default. If a project intentionally
owns a top-level harness, SF leaves it alone unless the files still carry
pending `sf-doc` markers proving they are old SF-generated residue.

## Doctor Cleanup

`/sf doctor --fix` may remove root-level generated residue only when all of the
following are true:

- the file is under a legacy SF-generated path such as `harness/specs/`;
- the file has an `sf-doc` marker;
- the marker template matches the file path;
- the marker state is `pending`;
- the current body hash still matches the marker hash.

Anything edited, completed, unmarked, or project-owned is reported conservatively
or left untouched.