diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 993c0cf..897ae2b 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -48,10 +48,16 @@ When documents conflict, higher layers win: 5. `specs//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. diff --git a/CLAUDE.md b/CLAUDE.md index ada3604..eccf0c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/README.md b/README.md index 87b3ada..2ce6d7e 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/traceability.md b/traceability.md index 4bcac20..385e42f 100644 --- a/traceability.md +++ b/traceability.md @@ -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). ---