Project Layout (schema v2)

Project Layout (schema v2)

Directory structure

docs/
├── arrows/
│   ├── index.yaml              # segment graph — statuses, blocks, taxonomy
│   └── <segment>/
│       └── *.md                # arrow detail docs (HLDs, LLDs)
└── intent/
    └── <segment>/
        ├── <segment>-specs.md  # spec lines  (- [ ] **ID**: text)
        └── <segment>-design.md # design docs

`index.yaml`

Minimal shape:

schema_version: 2
arrows:
  auth:
    status: MAPPED
    detail: auth/core.md

Full example with dependencies and taxonomy:

schema_version: 2
arrows:
  auth:
    status: OK
    detail: auth/core.md
    blocks: [api]
  api:
    status: MAPPED
    detail: api/core.md
    parent: platform
  platform:
    status: AUDITED
    detail: platform/core.md
    children: [api]

Segment statuses

Status	Meaning
`UNMAPPED`	Intent not yet described
`MAPPED`	Intent described, not yet audited
`AUDITED`	Intent audited against implementation
`OK`	Fully implemented and verified
`MERGED`	Absorbed into another segment

Spec line format

Spec lines live in docs/intent/<segment>/<segment>-specs.md. The file may start with an optional YAML frontmatter block declaring the authoritative spec-ID prefix for the segment:

---
prefix: AUTH
---

- [ ] **AUTH-001**: the system shall authenticate users via password.
- [x] **AUTH-002**: sessions shall expire after 30 minutes of inactivity.
- [D] **AUTH-003**: biometric login is deferred to v2.

The prefix: field is optional. When present, lidc check (spec-id-format check) warns on any spec ID in that file whose prefix does not match.

Marker	Status
`[ ]`	Open — not yet implemented
`[x]`	Implemented — must have at least one `@spec` citation
`[D]`	Deferred — must not have `@spec` citations

Spec ID format

<PREFIX>-<NNN> where <PREFIX> is typically the uppercase segment name (or a project-wide namespace prefix like USH-AUTH) and <NNN> is a zero-padded number. Examples: AUTH-001, PAY-042, USH-AUTH-015.

For projects with a shared namespace, path-concatenated IDs are also valid: LID-CORE-001 where LID is the project namespace, CORE is the segment, and 001 is the sequence number.

Source citation format

Cite a spec from any language using a line comment:

// @spec AUTH-002
fn validate_session_expiry(session: &Session) -> bool { ... }

// @spec AUTH-001
export async function authenticate(credentials: Credentials) { ... }

# @spec AUTH-001
def authenticate(credentials: dict) -> User:

// @spec AUTH-002
func validateSessionExpiry(session *Session) bool {

The @spec keyword is case-sensitive and must be followed by the spec ID. Multiple citations on adjacent lines are allowed.

Schema versioning

`schema_version`	Layout	Status
1	`docs/specs/` + `docs/llds/` (flat)	❌ Not supported — migrate to v2
2	`docs/intent/` recursive tree	✅ Supported

Encountering an unsupported schema version produces a hard error with a migration hint — never a silent partial load.