singularity-forge/docs/specs/README.md

# docs/specs/

Human-readable specifications and exported contracts.

SF plans and executes from `.sf`, database first. `.sf/sf.db` is the canonical
structured store for initialized repos; `.sf/*.md` files are working guidance,
knowledge, generated projections, or recovery inputs.

`docs/specs/` is for humans: reviewable exports, reports, public contracts, and
git-history artifacts. SF may read these files as repo evidence during analysis,
but any fact required for SF's own future operation must be captured into
`.sf`/DB-backed state before it is treated as operational knowledge.

Generated docs in this directory are allowed to change. That is part of their
purpose: Git keeps the human-facing history of exported contracts and reports.
SF can keep its own operational history in `.sf`/SQLite when it needs runtime
memory, ledgers, replay, or drift analysis.

## What belongs here

- Long-lived human-readable behavior contracts, APIs, or protocols.
- Generated or promoted exports from `.sf` working state.
- Reports that should be visible in git history for reviewers and future humans.
- Documents that outlive any single implementation plan but remain downstream
  from `.sf` when SF needs to use them operationally.

## What does NOT belong here

- SF working plans, state, knowledge, or task control files. Keep those in
  `.sf` and use runtime tools to mutate DB-owned records.
- Architecture decisions (use `docs/adr/`).
- Implementation plans (use `docs/plans/`).
- A parallel `BASE_SPEC.md` or product-spec hierarchy for new SF work.

## Naming convention

`<topic>.md` — e.g., `promote-command-spec.md`

## See also

- [SF operating model export](./sf-operating-model.md)
- [AGENTS.md#sf-planning-state](../../AGENTS.md#sf-planning-state)