Files
prometeu-studio/docs/specs/README.md

37 lines
2.0 KiB
Markdown

# Specification Guide
Specifications live under this tree and are organized by contract owner:
| Owner | Canonical corpus | Responsibility |
| --- | --- | --- |
| `compiler/general` | [General compiler](compiler/README.md) | Shared compilation, linking, typed handoff, emission and acceptance |
| `compiler/pbs` | [PBS language](compiler-languages/pbs/README.md) | PBS source, semantics, SDK and frontend projections |
| `packer` | [Packer](packer/README.md) | Assets, artifacts, packing and diagnostics |
| `studio` | [Studio](studio/README.md) | Shell, workspaces, adapters and visual/automation integration |
New compiler languages receive their own corpus under `compiler-languages/`.
Shared compiler policy stays in `compiler/`; PBS is not the root for other domains.
Each domain README provides a chapter index and reading order. Numbered chapters
are normative within their stated scope. Feature chapters own their detailed
contracts; cross-cutting chapters reference those rules rather than maintaining
competing versions. Write specifications and durable lessons in English.
The runtime repository owns PBX, ISA, admission and VM execution. Studio's
[VM architecture references and catalog mirrors](../vm-arch/README.md) retain
their separate provenance and synchronization policy. [Roadmaps](../roadmaps/)
describe cross-domain planning, not an alternative contract source.
The operational lifecycle is `agenda -> decision -> plan -> implement -> lesson`.
Keep its artifacts in `discussion/` and use the local `discussion` CLI for state
transitions, validation and housekeeping. See [repository instructions](../../AGENTS.md).
## Navigation verification
Run `python3 tools/documentation/verify.py` from the repository root to check local
links and anchors. Pass `--runtime ../runtime` to also check provider references
against an available read-only runtime checkout. The byte-exact architecture/ISA
mirrors retain the link context of their runtime originals; the checker resolves
them there. Ordinary builds and installed documentation reads do not require that
checkout.