hamid
3.2 KiB
Balinyaar docs
The entry point. Start here, follow one link, stop reading.
Built by the clarify chain, phases 0–7, 2026-07-29 → 2026-08-02. The chain's own plan — inventory, contradiction log, phase files, and their progress table — is now history, kept at
archive/clarify-chain/. Phase 7 (skills & guardrails) is done: three playbooks live in.claude/skills/; the anti-drift convention below is enforced by review rather than a git hook (an MVP-stage call — see decisions.md).
The rule that keeps three trees apart
| Tree | Answers | Example |
|---|---|---|
product/ |
What the business is | escrow holds funds until check-out is confirmed |
docs/ (here) |
What we built, and how we work | the escrow ledger is implemented; here is how to test it |
archive/ |
How we got here | the phase-10 prompt that built the ledger, and its report |
A file belongs in exactly one. If you are about to write a business rule into docs/, it belongs in
product/. If you are about to obey something in archive/, stop — it is a record, not an instruction.
archive/ holds the executed build-chain prompts, reports, and the pre-cleanup docs/_plan/. Start at
archive/README.md.
Map
| Section | What it holds | Status |
|---|---|---|
| rules/ | What must never be broken — the tiered rule set behind the CLAUDE.md files |
written · phase 1 |
| integration/ | The client↔server seam in one place: contract, config, topology, OpenAPI | written · phase 2 |
| flows/ | What is implemented, and how to test it — one file per user journey | written · phase 3 |
| status/ | Where the project actually is: implemented, backlog, decisions | written · phase 4 |
| roadmap/ | Where it goes next, and what gates a launch | written · phase 5 |
Still elsewhere
Two documents stay outside this tree on purpose:
DEPLOY.md— the deploy procedure, at the repo root where an operator will look for it. The runtime topology it implies moves todocs/integration/topology.md.product/— untouched by this chain.docs/status/implemented.mdoverlays build state onto its 14 business areas rather than restating them.
Conventions
- Every status or flow doc carries
> Last verified: <date> against <commit>. A doc without one is a claim, not a fact. - Verify, don't copy. A load-bearing claim is checked against code or run. If it cannot be checked,
it is written with an explicit
UNVERIFIED:prefix. - Write short. A reference doc over ~400 lines should be split. One deliberate exception: flows/testing-setup.md is the single page you hand a new tester, and splitting it would defeat that.
- English throughout, including in files that describe Persian UI copy.
The full convention is in docs/rules/documentation.md — enforced by review, not tooling (an MVP-stage call; see git-and-gates.md).