diff --git a/.changeset/72-project-business-context.md b/.changeset/72-project-business-context.md new file mode 100644 index 000000000..cfa52862d --- /dev/null +++ b/.changeset/72-project-business-context.md @@ -0,0 +1,5 @@ +--- +type: Added +pr: 756 +--- +**Optional `## Business Context` section in the PROJECT.md template** — a four-field block (Customer, Revenue model, Success metric, Strategy notes) for monetized or customer-facing projects, positioned between Core Value and Requirements. Optional by default (an HTML comment tells non-business projects to delete it), capped at four one-line fields to stay a constraint reference rather than a business plan, and reviewed at each milestone by `/gsd-complete-milestone` when present. (#72) diff --git a/docs/reference/planning-artifacts.md b/docs/reference/planning-artifacts.md index 41ef84113..45e73360b 100644 --- a/docs/reference/planning-artifacts.md +++ b/docs/reference/planning-artifacts.md @@ -51,6 +51,8 @@ The `.planning/` directory is GSD Core's shared memory for a project. Every work | **Produced by** | `/gsd-new-project` (initial creation); updated by `/gsd-complete-milestone` as decisions are validated. | | **Consumed by** | All planning workflows; `gsd-phase-researcher`, `gsd-planner` (context); `discuss-phase` (prior decisions); `gsd-plan-checker` (project constraints). | +Includes an optional `## Business Context` section (Customer, Revenue model, Success metric, Strategy notes) for monetized or customer-facing projects — four one-line fields that connect business outcomes to requirement prioritization. It is deleted for internal tools, experiments, or meta workspaces, and reviewed at each milestone by `/gsd-complete-milestone` when present. + ### `ROADMAP.md` | | | diff --git a/gsd-core/templates/project.md b/gsd-core/templates/project.md index 37a986c70..a78c5c220 100644 --- a/gsd-core/templates/project.md +++ b/gsd-core/templates/project.md @@ -17,6 +17,15 @@ Use the user's language and framing. Update whenever reality drifts from this de [The ONE thing that matters most. If everything else fails, this must work. One sentence that drives prioritization when tradeoffs arise.] +## Business Context + + + +- **Customer**: [Who pays / who uses — one line] +- **Revenue model**: [How it makes money — one line] +- **Success metric**: [The number that matters — one line] +- **Strategy notes**: [Link to external strategy doc, if any] + ## Requirements ### Validated @@ -83,6 +92,13 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform - Drives prioritization when tradeoffs arise - Rarely changes; if it does, it's a significant pivot +**Business Context:** +- Optional — only for monetized or customer-facing projects +- Delete the entire section for internal tools, experiments, or meta workspaces +- 4 fields max, one line each — a constraint reference, not a business plan +- Use **Strategy notes** to link out to a dedicated strategy doc rather than duplicating it here +- Informs requirement prioritization: features serving the customer/revenue model come first + **Requirements — Validated:** - Requirements that shipped and proved valuable - Format: `- ✓ [Requirement] — [version/phase]` @@ -140,8 +156,9 @@ and implemented by workflows/transition.md and workflows/complete-milestone.md. **After each milestone:** 1. Full review of all sections 2. Core Value check — still the right priority? -3. Audit Out of Scope — reasons still valid? -4. Update Context with current state (users, feedback, metrics) +3. Business Context check (if present) — customer, revenue model, success metric still accurate? +4. Audit Out of Scope — reasons still valid? +5. Update Context with current state (users, feedback, metrics) diff --git a/gsd-core/workflows/complete-milestone.md b/gsd-core/workflows/complete-milestone.md index 029e6e298..a7755945c 100644 --- a/gsd-core/workflows/complete-milestone.md +++ b/gsd-core/workflows/complete-milestone.md @@ -245,7 +245,12 @@ cat .planning/phases/*-*/*-SUMMARY.md - Still the right priority? Did shipping reveal a different core value? - Update if the ONE thing has shifted -3. **Requirements audit:** +3. **Business Context check (only if the section is present):** + - Skip entirely if PROJECT.md has no `## Business Context` section + - Customer, revenue model, and success metric still accurate after shipping? + - Update any field that drifted; refresh the linked strategy doc reference if it moved + +4. **Requirements audit:** **Validated section:** - All Active requirements shipped this milestone → Move to Validated @@ -261,17 +266,17 @@ cat .planning/phases/*-*/*-SUMMARY.md - Remove irrelevant items - Add requirements invalidated during milestone -4. **Context update:** +5. **Context update:** - Current codebase state (LOC, tech stack) - User feedback themes (if any) - Known issues or technical debt -5. **Key Decisions audit:** +6. **Key Decisions audit:** - Extract all decisions from milestone phase summaries - Add to Key Decisions table with outcomes - Mark ✓ Good, ⚠️ Revisit, or — Pending -6. **Constraints check:** +7. **Constraints check:** - Any constraints changed during development? Update as needed Update PROJECT.md inline. Update "Last updated" footer: @@ -355,6 +360,7 @@ Initial user testing showed demand for shape tools. - [ ] "What This Is" reviewed and updated if needed - [ ] Core Value verified as still correct +- [ ] Business Context checked (or confirmed absent) - [ ] All shipped requirements moved to Validated - [ ] New requirements added to Active for next milestone - [ ] Out of Scope reasoning audited diff --git a/tests/enh-72-business-context.test.cjs b/tests/enh-72-business-context.test.cjs new file mode 100644 index 000000000..b58b7007e --- /dev/null +++ b/tests/enh-72-business-context.test.cjs @@ -0,0 +1,96 @@ +// allow-test-rule: source-text-is-the-product +// The PROJECT.md template + complete-milestone workflow .md ARE the product surface +// the runtime loads; asserting on their text tests the deployed contract directly. +/** + * Enhancement #72 — optional Business Context section in the PROJECT.md template. + * + * Contract tests over the product-text surfaces (template + milestone workflow .md): + * the template offers a Business Context section that is explicitly OPTIONAL, capped + * at the four approved one-line fields, and the milestone evolution review treats it + * as conditional so non-business projects that deleted it are never forced to review it. + */ +const { test, describe } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const path = require('path'); + +const TEMPLATE = path.join(__dirname, '..', 'gsd-core', 'templates', 'project.md'); +const COMPLETE_MILESTONE = path.join(__dirname, '..', 'gsd-core', 'workflows', 'complete-milestone.md'); + +function parseTemplateContract(content) { + const lines = content.split(/\r?\n/); + const lower = content.toLowerCase(); + // The Business Context block lives between its heading and the next "## " heading. + const startIdx = lines.findIndex(l => l.trim() === '## Business Context'); + let sectionBody = ''; + if (startIdx !== -1) { + const rest = lines.slice(startIdx + 1); + const endOffset = rest.findIndex(l => l.startsWith('## ')); + sectionBody = (endOffset === -1 ? rest : rest.slice(0, endOffset)).join('\n'); + } + const fieldOf = (label) => new RegExp(`^- \\*\\*${label}\\*\\*:`, 'm').test(sectionBody); + return { + hasSection: startIdx !== -1, + // Optional-by-default: an HTML comment tells non-business projects to delete it. + hasOptionalMarker: /