singularity-forge/docs/specs

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
• AGENTS.md#sf-planning-state