Skip to content

Clarify scope vs process in Hierarchy of Truth #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cursor merged 1 commit into from
Jul 17, 2026
Merged

Clarify scope vs process in Hierarchy of Truth #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion .specify/memory/constitution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,16 @@ When documents conflict, higher layers win:
5. `specs/<feature>/plan.md` and `tasks.md`
6. Source code

**Scope vs process.** Product scope and acceptance criteria are authoritative only in `HomesFlow.prd.md`. This constitution governs *how* we build (process, architecture, traceability). If the PRD is silent on a product behavior, do not invent scope here — amend the PRD. If documents conflict on *engineering law*, this constitution wins; on *what the product must do*, the PRD wins.

External planning aids (e.g. StoriesOnBoard story maps) may inform humans when drafting or revising the PRD. They are not part of this hierarchy and are not Gate-2-enforced.

## Governance

Amendments require a version bump and brief rationale. Traceability mechanics live in `traceability.md`; engineering and toolchain notes in `specs/001-mvp/dev-notes.md`. Neither overrides this file or the PRD.

**Version**: 1.2.0 | **Ratified**: 2026-06-28 | **Last Amended**: 2026-07-03
**Version**: 1.2.1 | **Ratified**: 2026-06-28 | **Last Amended**: 2026-07-17

**1.2.1 rationale**: Clarified Hierarchy of Truth so agents do not blur process law (constitution) with product scope (PRD). Story maps and similar tools stay outside the machine-checked chain.

**1.2.0 rationale**: Principle III previously hardcoded blanket timestamp-wins. Amended to defer to the PRD's data-type-aware conflict model (story-map decision 2026-07-03): automatic resolution with loser notification, terminal-status protection, connectivity-gated structural actions. Keeps the constitution stable as per-data-type rules evolve in the PRD.
2 changes: 2 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,6 @@

**Hard rule — requirements:** Scope and behavior source from `HomesFlow.prd.md` only. Do not invent, extrapolate, or assume product scope. Implementation must follow accepted spec/plan/tasks and traceability; if the PRD is silent, ask or propose a PRD change — do not ship guessed requirements.

**Scope vs process:** Product scope = PRD only. Process/architecture laws = constitution. Do not invent product behavior from the constitution, glossary, story maps, or craft docs.

Run `/speckit.specify` using the PRD as input.
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ No orphan code, no silent scope, no untracked debt: an acceptance criterion is e

| Document | Role |
|----------|------|
| **[Story map](https://homesflow.storiesonboard.com/m/homesflow1)** (StoriesOnBoard) | Product planning view: releases, story slices, and what's next; feeds the PRD |
| **`HomesFlow.prd.md`** | Product requirements, user stories, acceptance criteria |
| **`.specify/memory/constitution.md`** | Non-negotiable architectural and process laws |
| **`HomesFlow.prd.md`** | Product requirements, user stories, acceptance criteria (authoritative scope) |
| **`.specify/memory/constitution.md`** | Non-negotiable process and architecture laws (not product scope) |
| **[Story map](https://homesflow.storiesonboard.com/m/homesflow1)** (StoriesOnBoard) | Human planning aid — releases and story slices; not Gate-2-enforced; promote changes into the PRD when they become product truth |
| **`traceability.md`** | How IDs flow from PRD → spec → tasks → code → tests |
| **`specs/001-mvp/craft-conventions.md`** | Swift, shell, lint, and Sonar policy (craft gates) |
| **`specs/001-mvp/dev-notes.md`** | Environments, deployment, feature breadcrumbs, platform backlog |
Expand Down
4 changes: 3 additions & 1 deletion traceability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

Purpose: guarantee an unbroken chain from PRD requirement → spec → task → code → test, so that coverage and scope are *machine-checkable* rather than maintained by hand.

This file is the single source of mechanics. The short, non-negotiable **principle** belongs in the Spec Kit constitution (`.specify/memory/constitution.md`); everything else lives here and is referenced from there.
Gate 2 proves the PRD is *true of the system*: shipped behavior is authorized by a registry ID, and every acceptance criterion is either verified by a named test or explicitly tracked as debt. It does not prove the PRD is the right product — that is discovery/validation work outside this chain.

This file is the single source of mechanics. The short, non-negotiable **principle** belongs in the Spec Kit constitution (`.specify/memory/constitution.md`); everything else lives here and is referenced from there. Product scope remains in `HomesFlow.prd.md` (see constitution Hierarchy of Truth — scope vs process).

---

Expand Down
Loading