diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 3e06d3d..24fcbba 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -3,69 +3,118 @@ **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] **Input**: Feature specification from `/specs/[###-feature-name]/spec.md` -**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow. +**Note**: This template is filled in by the `/speckit.plan` command. For this project, planning is document-first and multi-repo aware. ## Summary [Extract from feature spec: primary requirement + target documents + intended update approach] +## Repository Scope + +- **Formal workflow home**: `water-docs` +- **Target repos in scope**: + - `water-docs`: [Yes / No] + - `water-backend`: [Yes / No] + - `water-frontend`: [Yes / No] +- **Primary delivery mode**: [Document closure / Code evidence alignment / Backend implementation / Frontend implementation / Mixed] + +## Code Baseline + +- **Backend baseline**: [commit SHA / branch / N/A] +- **Frontend baseline**: [commit SHA / branch / N/A] +- **Baseline capture plan**: [How code evidence will be tied to a stable commit] + ## Technical Context - - -**Primary Work Product**: [e.g., Markdown design docs, management docs, link/index governance or NEEDS CLARIFICATION] +**Primary Work Product**: [Markdown design docs, management docs, evidence files, backend code, frontend code] **Source of Truth Documents**: [List the authoritative docs that this change must align with] **Reference Sources**: [Archive/guides/other references allowed for verification] -**Validation Commands**: [e.g., make validate-file FILE=..., make check-links, make validate-mermaid] -**Target Scope**: [e.g., specific chapters, specific main docs, cross-doc governance] -**Project Type**: 文档治理仓库 -**Constraints**: [e.g., no new parallel formal docs, no invented business rules, relative links only] -**Scale/Scope**: [e.g., single document / cross-document / structural governance] +**Validation Commands**: [e.g., make validate-file FILE=..., make check-links, make validate-mermaid, compile/build/test commands] +**Target Scope**: [specific chapters, main docs, code modules, or verification slices] +**Project Type**: 文档治理仓库 + 多仓实现协作 +**Constraints**: [no new parallel formal docs, no invented business rules, relative links only, branch rules, baseline rules] +**Scale/Scope**: [single document / cross-document / multi-repo / verification-heavy] ## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* -- [ ] **主文档归属已确认**：本次改动将优先落在既有主文档或治理文档，而不是新增平行正式稿。 -- [ ] **范围基线已确认**：若涉及新增功能、模块、接口或外部协同，已按 `03_Summary_Design.md` 与 Archive 范围基线交集完成判定。 +- [ ] **主文档归属已确认**：正式结论优先落在 `water-docs` 既有主文档或治理文档，不新增平行正式稿。 +- [ ] **多仓范围已确认**：已明确本轮是否涉及 `water-backend`、`water-frontend`，以及各自只是取证还是需要改代码。 +- [ ] **代码基线已确认**：backend/frontend 的 commit 或 branch 基线已记录，避免文档结论失去实现版本锚点。 - [ ] **Archive 使用方式合规**：Archive 仅作为来源/核对输入，不直接替代正式口径。 -- [ ] **一致性影响已列出**：已识别系统名称、数据库口径、编号、图表、链接、术语等受影响项。 -- [ ] **校验与台账动作已规划**：已明确需要执行的校验命令，以及是否需要更新 `01_Project_Progress.md` / `03_Task_Checklist.md`。 +- [ ] **一致性影响已列出**：已识别系统名称、数据库口径、编号、图表、链接、术语、接口契约等受影响项。 +- [ ] **校验与台账动作已规划**：已明确需要执行的文档校验、代码验证、evidence 更新，以及是否需要更新 `01_Project_Progress.md` / `03_Task_Checklist.md`。 ## Project Structure -### Documentation (this feature) +### Feature Artifacts ```text specs/[###-feature]/ -├── plan.md # This file (/speckit.plan command output) -├── research.md # Phase 0 output (/speckit.plan command) -├── data-model.md # Optional: document entities/traceability objects -├── quickstart.md # Optional: validation or review quickstart -├── contracts/ # Optional: interface or section-level artifacts -└── tasks.md # Phase 2 output (/speckit.tasks command) +├── spec.md +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +├── tasks.md +└── verification.md / final-verdict.md ``` ### Repository Touchpoints ```text -docs/design/ -├── 00_Management/ -├── 01_Overview/ -├── 02_Detailed_Design/ -├── 03_Technical_Design/ -└── 04_Appendix/Archive/ +water-docs/ +├── docs/design/ +├── specs/ +└── .specify/ -README.md -AGENTS.md -.specify/templates/ +water-backend/ +└── [backend modules in scope] + +water-frontend/ +└── [frontend modules in scope] ``` -**Structure Decision**: [Document the exact files to be updated and the reason each file is in scope] +**Structure Decision**: [Document the exact files or modules to be updated and the reason each is in scope] + +## Phase 0: Research & Alignment + +### Research Inputs + +- [List unresolved questions about docs, backend, frontend, baseline, or validation] + +### Deliverables + +- `research.md` +- [Optional evidence note if brownfield code audit is required] + +## Phase 1: Design & Contracts + +### Planned Artifacts + +- `data-model.md` +- `contracts/*` +- `quickstart.md` +- `verification.md` or `final-verdict.md` if the feature is verification-heavy + +### Design Decisions + +- [List the intended docs-first and multi-repo decisions] + +## Validation Plan + +- **Document validation**: [make validate-file / check-links / mermaid checks] +- **Backend validation**: [compile / unit test / smoke / N/A] +- **Frontend validation**: [build / lint / typecheck / smoke / N/A] +- **Evidence output**: [baseline.md / docs-validation.md / backend-validation.md / frontend-validation.md / final-verdict.md] + +## Ledger Sync Plan + +- **Project progress update required**: [Yes / No] +- **Task checklist update required**: [Yes / No] +- **Evidence or verification summary update required**: [Yes / No] ## Complexity Tracking diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index d72e6f5..24f514f 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -12,20 +12,42 @@ - **Reference sources**: [List allowed Archive/guides/supporting docs] - **Scope decision**: [State whether this request is in scope, needs confirmation, or is out of scope] +## Repository Scope *(mandatory)* + +- **Target repos**: + - `water-docs`: [Required / Not Required] + - `water-backend`: [Required / Not Required] + - `water-frontend`: [Required / Not Required] +- **Expected delivery type**: [Document closure / Code evidence alignment / Backend implementation / Frontend implementation / Mixed] +- **Out of scope for this round**: [List anything explicitly excluded] + +## Code Baseline *(mandatory for brownfield work)* + +- **Backend baseline**: [commit SHA / branch / N/A] +- **Frontend baseline**: [commit SHA / branch / N/A] +- **Baseline capture rule**: [How the implementation evidence will be tied back to a specific code version] + +## Evidence Scope *(mandatory)* + +- **Document evidence required**: [Which formal docs or specs must be updated] +- **Backend evidence required**: [Controllers / services / tests / compile / N/A] +- **Frontend evidence required**: [Pages / routes / build / smoke / N/A] +- **Verification artifacts required**: [baseline.md / docs-validation.md / backend-validation.md / frontend-validation.md / final-verdict.md] + ## User Scenarios & Testing *(mandatory)* ### User Story 1 - [Brief Title] (Priority: P1) -[Describe the document-maintenance user journey in plain language] +[Describe the primary independently reviewable outcome in plain language] **Why this priority**: [Explain the value and why it has this priority level] -**Independent Test**: [Describe how this can be reviewed independently, e.g. by validating one target document and checking impacted links] +**Independent Test**: [Describe how this can be reviewed independently] **Acceptance Scenarios**: @@ -64,9 +86,10 @@ ### Edge Cases +- What happens when the formal document conclusion and the current code evidence do not align? - What happens when a requested change is only supported by Archive history but not by current main docs? - How does the workflow handle broken relative links, unstable anchors, or Mermaid syntax regressions introduced by edits? -- What happens when one document changes numbering or terminology that affects other linked documents? +- What happens when the backend and frontend are on different commits and the feature must still produce a single verdict? ## Requirements *(mandatory)* @@ -74,25 +97,29 @@ - **FR-001**: Specification MUST identify the exact target documents that will be changed. - **FR-002**: Specification MUST identify the main source-of-truth documents that govern the change. -- **FR-003**: Specification MUST record whether the request is in scope, requires confirmation, or is out of scope under the project range baseline. -- **FR-004**: System MUST preserve the single-source-of-truth model and MUST NOT assume creation of new parallel formal documents unless explicitly approved. -- **FR-005**: System MUST list the validation actions needed after the change, including file validation and any required link or Mermaid checks. -- **FR-006**: System MUST state whether management ledgers need updates in `01_Project_Progress.md` and `03_Task_Checklist.md`. -- **FR-007**: System MUST capture cross-document consistency impacts when terminology, numbering, diagrams, or references may change. +- **FR-003**: Specification MUST identify which repositories are in scope and which are explicitly out of scope for the round. +- **FR-004**: Specification MUST record backend/frontend code baselines or explicitly mark them N/A. +- **FR-005**: System MUST preserve the single-source-of-truth model and MUST NOT assume creation of new parallel formal documents unless explicitly approved. +- **FR-006**: Specification MUST list the validation actions needed after the change, including file validation and any required link or Mermaid checks. +- **FR-007**: Specification MUST state whether management ledgers need updates in `01_Project_Progress.md` and `03_Task_Checklist.md`. +- **FR-008**: Specification MUST capture cross-document consistency impacts when terminology, numbering, diagrams, references, or interface contracts may change. +- **FR-009**: Specification MUST define what evidence artifacts are required before the feature can be marked complete. ### Key Entities *(include if feature involves data)* - **Target Document**: A Markdown file that will be modified as part of the request. - **Source of Truth Document**: A main document or governance document that constrains allowed conclusions. - **Reference Source**: Archive or guide material used only for verification, traceability, or scope judgment. -- **Validation Action**: A command or review step that proves the document set remains consistent after change. +- **Code Baseline**: A backend or frontend commit reference used to anchor brownfield implementation evidence. +- **Evidence Artifact**: A document under `specs/` or `evidence/` that records validation, code proof, or the final verdict. - **Ledger Update**: A required change to project progress or task checklist records after important modifications. ## Success Criteria *(mandatory)* ### Measurable Outcomes -- **SC-001**: Every target document is explicitly named before implementation begins. +- **SC-001**: Every target document and in-scope repository is explicitly named before implementation begins. - **SC-002**: Every completed change can be traced to at least one source-of-truth or approved reference source. -- **SC-003**: Required validation actions are explicitly listed and can be executed without ambiguity. -- **SC-004**: Reviewers can determine from the spec alone whether ledger updates and cross-document sync are required. +- **SC-003**: Required validation and evidence actions are explicitly listed and can be executed without ambiguity. +- **SC-004**: Reviewers can determine from the spec alone whether ledger updates, code-baseline capture, and cross-document sync are required. +- **SC-005**: The feature can produce a final verdict without relying on unstated assumptions about backend or frontend implementation status. diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index c208baa..e59807d 100644 --- a/.specify/templates/tasks-template.md +++ b/.specify/templates/tasks-template.md @@ -5,11 +5,11 @@ description: "Task list template for feature implementation" # Tasks: [FEATURE NAME] **Input**: Design documents from `/specs/[###-feature-name]/` -**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/ +**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md -**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks. +**Validation**: Validation and evidence tasks are NOT optional. Every feature task set MUST include the applicable document validation, code validation, ledger-sync, and final-verdict tasks. -**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently. +**Organization**: Tasks are grouped by user story so each slice can be completed, reviewed, and validated independently. ## Format: `[ID] [P?] [Story] Description` @@ -19,84 +19,98 @@ description: "Task list template for feature implementation" ## Path Conventions +- Formal workflow: `water-docs/` - Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/` - Governance documents: `docs/design/00_Management/` -- Archive references: `docs/design/04_Appendix/Archive/` -- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/` +- Feature artifacts: `specs/[###-feature]/` +- Backend modules: `water-backend/...` +- Frontend modules: `water-frontend/...` -## Phase 1: Scope & Source Confirmation (Shared Foundation) +## Phase 1: Scope, Baseline & Source Confirmation -**Purpose**: Confirm the source-of-truth set and impact boundary before editing. +**Purpose**: Confirm the source-of-truth set, repo boundary, and code baselines before editing anything. -- [ ] T001 Confirm target documents and exact chapters from spec.md -- [ ] T002 Confirm governing source-of-truth documents and allowed references -- [ ] T003 [P] Record scope judgment (in scope / needs confirmation / out of scope) -- [ ] T004 [P] Identify cross-document impacts: terminology, numbering, diagrams, links, ledger updates +- [ ] T001 Confirm target documents, target repos, and exact chapters from `specs/[###-feature]/spec.md` +- [ ] T002 Confirm governing source-of-truth documents and allowed references from `specs/[###-feature]/plan.md` +- [ ] T003 [P] Record backend/frontend code baseline references in `specs/[###-feature]/plan.md` or `specs/[###-feature]/verification.md` +- [ ] T004 [P] Identify cross-document and cross-repo impacts: terminology, numbering, diagrams, links, contracts, ledger updates --- -## Phase 2: User Story 1 - [Title] (Priority: P1) 🎯 MVP +## Phase 2: Shared Foundation -**Goal**: [Brief description of the first independently reviewable document update] +**Purpose**: Establish the shared alignment baseline for docs, code evidence, and verification outputs. + +- [ ] T005 Normalize key terms, interface IDs, module IDs, and state vocabulary in `specs/[###-feature]/plan.md` +- [ ] T006 Confirm the final validation command set in `specs/[###-feature]/quickstart.md` +- [ ] T007 Prepare verification output targets in `specs/[###-feature]/verification.md` or `specs/[###-feature]/final-verdict.md` + +--- + +## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP + +**Goal**: [Brief description of the first independently reviewable outcome] **Independent Test**: [How to verify this story on its own] ### Implementation for User Story 1 -- [ ] T005 [US1] Update target document in docs/design/... with the approved scope -- [ ] T006 [US1] Sync affected anchors, references, numbering, or glossary terms in impacted docs -- [ ] T007 [US1] Run `make validate-file FILE=` and capture result -- [ ] T008 [US1] Run any required cross-document validation (`make check-links`, `make validate-mermaid`) and capture result -- [ ] T009 [US1] Update `docs/design/00_Management/01_Project_Progress.md` if the change is important -- [ ] T010 [US1] Update `docs/design/00_Management/03_Task_Checklist.md` if a tracked task is completed or materially changed +- [ ] T008 [US1] Update target formal document in `water-docs/docs/design/...` +- [ ] T009 [US1] Sync impacted references, anchors, numbering, glossary terms, or contracts in `water-docs/...` +- [ ] T010 [US1] If required, inspect or update matching backend scope in `water-backend/...` +- [ ] T011 [US1] If required, inspect or update matching frontend scope in `water-frontend/...` +- [ ] T012 [US1] Run story-specific document validation and capture result in `specs/[###-feature]/quickstart.md` +- [ ] T013 [US1] Run story-specific code validation or evidence capture and record result in `specs/[###-feature]/verification.md` -**Checkpoint**: User Story 1 is reviewable, validated, and ledger-synced independently +**Checkpoint**: User Story 1 is independently reviewable with both document and implementation evidence aligned. --- -## Phase 3: User Story 2 - [Title] (Priority: P2) +## Phase 4: User Story 2 - [Title] (Priority: P2) -**Goal**: [Brief description of the second independently reviewable update] +**Goal**: [Brief description of the second independently reviewable outcome] **Independent Test**: [How to verify this story on its own] ### Implementation for User Story 2 -- [ ] T011 [US2] Update target document in docs/design/... with approved changes -- [ ] T012 [US2] Sync affected references, diagrams, or traceability entries -- [ ] T013 [US2] Run `make validate-file FILE=` and capture result -- [ ] T014 [US2] Run any additional required validation and capture result -- [ ] T015 [US2] Update relevant management ledgers if applicable +- [ ] T014 [US2] Update target formal document in `water-docs/docs/design/...` +- [ ] T015 [US2] Sync affected references, diagrams, or traceability entries in `water-docs/...` +- [ ] T016 [US2] If required, inspect or update matching backend scope in `water-backend/...` +- [ ] T017 [US2] If required, inspect or update matching frontend scope in `water-frontend/...` +- [ ] T018 [US2] Run story-specific validation and capture result in `specs/[###-feature]/quickstart.md` +- [ ] T019 [US2] Record backend/frontend evidence or outcome in `specs/[###-feature]/verification.md` -**Checkpoint**: User Story 2 is reviewable and validated independently +**Checkpoint**: User Story 2 is independently reviewable and validated. --- -## Phase 4: User Story 3 - [Title] (Priority: P3) +## Phase 5: User Story 3 - [Title] (Priority: P3) -**Goal**: [Brief description of the third independently reviewable update] +**Goal**: [Brief description of the third independently reviewable outcome] **Independent Test**: [How to verify this story on its own] ### Implementation for User Story 3 -- [ ] T016 [US3] Update target document in docs/design/... with approved changes -- [ ] T017 [US3] Sync affected supporting documents or guidance files -- [ ] T018 [US3] Run `make validate-file FILE=` and capture result -- [ ] T019 [US3] Run any additional required validation and capture result -- [ ] T020 [US3] Update relevant management ledgers if applicable +- [ ] T020 [US3] Update target formal document or governance file in `water-docs/docs/design/...` +- [ ] T021 [US3] Sync affected supporting docs, contracts, or guidance files in `water-docs/...` +- [ ] T022 [US3] If required, inspect or update matching backend/frontend scope in `water-backend/...` or `water-frontend/...` +- [ ] T023 [US3] Run story-specific validation and capture result in `specs/[###-feature]/quickstart.md` +- [ ] T024 [US3] Update `docs/design/00_Management/01_Project_Progress.md` and `docs/design/00_Management/03_Task_Checklist.md` if applicable -**Checkpoint**: All planned document updates are independently reviewable and validated +**Checkpoint**: All planned updates are independently reviewable and validated. --- -## Final Phase: Cross-Cutting Closure +## Final Phase: Verification & Closure -**Purpose**: Ensure repository-wide consistency after all story slices are complete. +**Purpose**: Ensure repository-wide consistency, baseline traceability, and final verdict output. -- [ ] T021 [P] Re-check source-of-truth alignment across all modified files -- [ ] T022 [P] Re-check relative links, stable anchors, and Mermaid consistency across all modified files -- [ ] T023 Prepare final summary with modified files, validation results, remaining risks, and next-step suggestions +- [ ] T025 [P] Re-check source-of-truth alignment across all modified files and touched repos +- [ ] T026 [P] Re-check relative links, stable anchors, and Mermaid consistency across all modified formal docs +- [ ] T027 [P] Re-check backend/frontend baseline SHAs and validation outputs in `specs/[###-feature]/verification.md` +- [ ] T028 Prepare final summary and verdict in `specs/[###-feature]/final-verdict.md` or `specs/[###-feature]/verification.md` --- @@ -104,28 +118,28 @@ description: "Task list template for feature implementation" ### Phase Dependencies -- **Scope & Source Confirmation**: No dependencies; MUST finish before content edits -- **User Stories**: Depend on confirmed scope and sources +- **Scope, Baseline & Source Confirmation**: No dependencies; MUST finish before edits +- **Shared Foundation**: Depends on Phase 1 and MUST finish before story execution +- **User Stories**: Depend on confirmed scope, baseline, and validation plan - **Final Phase**: Depends on all selected user stories being complete ### Within Each User Story -- Update target document before syncing impacted documents +- Update formal docs before syncing impacted support files - Complete content edits before validation - Complete validation before ledger updates are marked done -- Complete ledger sync before final summary +- Record backend/frontend evidence before final verdict ### Parallel Opportunities - Scope analysis tasks marked [P] can run in parallel -- Different impacted supporting files can be updated in parallel if they do not touch the same file -- Validation tasks for different files can run in parallel when commands are independent - ---- +- Backend and frontend inspection tasks can run in parallel when they touch different repos +- Validation tasks for different files or repos can run in parallel when commands are independent ## Notes -- Every task set MUST preserve the single-source-of-truth model +- Every task set MUST preserve the single-source-of-truth model in `water-docs` - Archive is for verification and traceability, not direct formal output replacement -- Do not omit validation or ledger tasks when they apply -- Avoid vague tasks; every task should name the file path and expected outcome +- backend/frontend do not own the official spec; they consume and evidence it +- Do not omit validation, evidence, or ledger tasks when they apply +- Avoid vague tasks; every task should name the file path, repo, and expected outcome diff --git a/.specify/templates/verify-template.md b/.specify/templates/verify-template.md new file mode 100644 index 0000000..9b2ab25 --- /dev/null +++ b/.specify/templates/verify-template.md @@ -0,0 +1,62 @@ +# Verification: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` +**Date**: [DATE] +**Spec**: [link] +**Plan**: [link] +**Tasks**: [link] + +## Code Baseline + +- **Backend repo**: `water-backend` +- **Backend commit**: [commit SHA / N/A] +- **Frontend repo**: `water-frontend` +- **Frontend commit**: [commit SHA / N/A] +- **Baseline captured at**: [DATE TIME] + +## Document Validation + +| Check | Scope | Result | Notes | +|-------|-------|--------|-------| +| `make validate-file` | [file] | [PASS/FAIL] | [details] | +| `make check-links` | [scope] | [PASS/FAIL] | [details] | +| `make validate-mermaid` / fallback | [scope] | [PASS/FAIL/BLOCKED] | [details] | + +## Backend Validation + +| Check | Scope | Result | Notes | +|-------|-------|--------|-------| +| Compile | [module] | [PASS/FAIL/N/A] | [details] | +| Unit Test | [module] | [PASS/FAIL/N/A] | [details] | +| Smoke / Evidence | [controller/service] | [PASS/FAIL/N/A] | [details] | + +## Frontend Validation + +| Check | Scope | Result | Notes | +|-------|-------|--------|-------| +| Build | [module] | [PASS/FAIL/N/A] | [details] | +| Lint / Typecheck | [module] | [PASS/FAIL/N/A] | [details] | +| Smoke / Evidence | [page/route/component] | [PASS/FAIL/N/A] | [details] | + +## Ledger Sync + +- `01_Project_Progress.md`: [Updated / Not Required] +- `03_Task_Checklist.md`: [Updated / Not Required] +- Other governance docs: [List if applicable] + +## Final Verdict + +- **Document status**: [Closed / Partial / Blocked] +- **Backend status**: [Implemented / Partially Implemented / Not Implemented / N/A] +- **Frontend status**: [Implemented / Partially Implemented / Not Implemented / N/A] +- **Overall result**: [PASS / PARTIAL / BLOCKED] + +## Remaining Risks + +- [Risk 1] +- [Risk 2] + +## Next Actions + +- [Next step 1] +- [Next step 2]