The Project Model

Requirement A project MUST keep every record in the home its type names.

Rationale One home per type tells a reader and the builder where a record lives.

Example A decision lives at docs/product/decisions/0047-extend-loan-period.md.

Requirement Every written record MUST carry its type, identifier, title, owner, and status.

Rationale Shared fields let the builder join records across pages.

Requirement A link MUST live as fields on the record it starts from.

Rationale One writing site keeps a link and its source in one edit.

Requirement A conflict MUST resolve toward the higher authority.

Rationale Constraint outranks product, product outranks requirement, requirement outranks rule, and rule outranks use case. Decisions explain a choice and carry no rank; research and prose carry none.

Requirement A tie MUST resolve toward the later approved decision.

Rationale The shared owner decides when no later decision separates the records.

Requirement A record MUST NOT stand approved behind a draft decision.

Rationale Approval means the reasoning behind the record already holds. The builder also writes each record's effectiveStatus: draft when the record, a decision deciding it, or a requirement it fulfills is a draft. A result or a case takes its use case's effective status.

Requirement An accepted gap MUST live as a known gap with owner and end date.

Rationale A dated owner turns missing work into a visible promise.

Example The running library example accepts that retiring a copy has no handler yet, so the gap lives as a known gap with an owner and an end date in docs/known-gaps/retire-copy-unimplemented.md.

{
  "type": "known-gap",
  "id": "known-gap/retire-copy-unimplemented",
  "title": "Retire copy unimplemented",
  "owner": "lending-team",
  "status": "approved",
  "check": "use-case-unimplemented",
  "subject": ["use-case/lending.retire-copy"],
  "endsBy": "2027-06-01",
  "reason": "Retirement waits for the weeding policy."
}

The use-case-unimplemented check reports without failing until 2027-06-01, and the lending team answers for closing the gap, which satisfies this provision.

Requirement A conflict MUST resolve toward the project exception, the extension, the deeper page, or the shallower page, in that order.

Rationale A project requirement never overrides a shared standard; the conflict becomes an exception.

Example The running library example needs its morning import to skip the quiet shelf check, so it records a project exception that outranks the shared standard in docs/exceptions/shelf-check-bypass.md.

{
  "type": "exception",
  "id": "exception/shelf-check-bypass",
  "title": "Shelf check bypass",
  "owner": "lending-team",
  "status": "approved",
  "standard": "standard/lending.quiet-shelf-check",
  "reason": "The import runs before opening.",
  "reviewBy": "2027-01-01",
  "removeWhen": "The import moves after opening."
}

The record names the standard it departs from, the reason, and the review date, so the departure stays visible and dated, which satisfies this provision.

Requirement A use case MUST name the permissions it needs.

Rationale Actors hold roles at a scope, roles allow permissions, and entry points may restrict them.

Example An anonymous use case sets anonymous and names no permission.

Requirement Module order MUST live as dependsOn links between modules.

Rationale A link states the dependency without ranking one module above another.

Requirement Every page MUST name one owner and one status.

Rationale Entries inherit both from their page unless they set their own.

Example A draft names its decider and decideBy date.

The three statuses and what each allows: a draft awaits its decider, approved holds, and retired means a replacement holds.

Requirement A replacing decision MUST name the decision it replaces, and no other record type carries replaces.

Rationale Decisions alone keep the past: the old one stands retired beside the new one. Every other record changes in place, and a rename rewrites every citation in the same change.

Requirement Every decision that is not retired MUST name at least one record it settles in decides.

Rationale The draft gate and the computed effective status follow decides. A decision that names nothing holds back nothing, so its approval state means nothing.

Requirement Every Markdown link outside code on a page under the record roots MUST point at an existing file, by its relative path.

Rationale A link shaped like an identifier, or to a moved file, reads as navigation and leads nowhere. An identifier is cited in backticks, and a link names a file.

Requirement A project MUST declare its size, stacks, and optional types.

Rationale Size decides the required record types and test projects; stacks decide the technology pages.

Example A library loan system declares small with a single backend stack.

Requirement A use case MUST end in a success result and name its refusals.

Rationale Callers branch on named endings, and cases prove one ending each.

Example A loan use case names loaned and book-not-available.

The running library example carries this in use-case/lending.borrow-copy, which names result/borrow-copy.borrowed and result/borrow-copy.copy-unavailable in results and case/borrow-copy.borrowing-an-available-copy-succeeds in cases:

"records": [
  {
    "type": "result",
    "id": "result/borrow-copy.borrowed",
    "title": "Borrowed",
    "owner": "lending-team",
    "outcome": "success",
    "httpStatus": 201,
    "meaning": "The copy is lent."
  },
  {
    "type": "result",
    "id": "result/borrow-copy.copy-unavailable",
    "title": "Copy unavailable",
    "owner": "lending-team",
    "outcome": "refusal",
    "code": "failure/lending.copy_not_available",
    "httpStatus": 409,
    "meaning": "The copy is unavailable."
  },
  {
    "type": "case",
    "id": "case/borrow-copy.borrowing-an-available-copy-succeeds",
    "title": "Borrowing an available copy succeeds",
    "owner": "lending-team",
    "status": "approved",
    "situation": "A copy sits available on its shelf.",
    "action": "The reader borrows the copy.",
    "result": "result/borrow-copy.borrowed",
    "expect": "The loan is active."
  }
]

Success ends with 201, the refusal carries the failure code failure/lending.copy_not_available with 409, and the case pairs one situation with the success result, which satisfies this provision.

Requirement A public use case MUST sit in a journey or name its background caller.

Rationale Reachability shows readers how each operation is found.

Requirement Implemented and verified MUST come from the builder, never from handwriting.

Rationale The builder joins handlers, routes, scenarios, and test runs to the written records.

Example A use case reads implemented when its handler exists.