42 lines
1.7 KiB
Markdown
42 lines
1.7 KiB
Markdown
# 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)
|