Implement: Workflow: replan — handle requirement changes mid-build

_sam/_config/workflow-manifest.csv

@@ -5,3 +5,4 @@ name,description,module,path
 "build-tdd","SAM Build-TDD Workflow - Implements a single user story using RED-GREEN-REFACTOR with conditional UI/CSS/A11y/Security review.","core","_sam/core/workflows/build-tdd/workflow.md"
 "plan-n-build","SAM end-to-end composer - runs plan, then tdd for every story, then comprehensive docs.","core","_sam/core/workflows/plan-n-build/workflow.md"
 "extend","SAM Extend Workflow - Plan additive changes on top of an existing app. Reads existing sdocs/, never wipes; emits new contracts, stories, and regression integration without modifying done work.","core","_sam/core/workflows/extend/workflow.md"
+"replan","SAM Replan Workflow - Handle requirement changes mid-build by diffing a revised PRD against the current state and surgically updating affected artifacts.","core","_sam/core/workflows/replan/workflow.md"

_sam/core/resources/contract-schema.md

@@ -47,6 +47,13 @@ created: 2026-05-14                     # YYYY-MM-DD
   - `draft` — Atlas designed it, no story has implemented it yet
   - `stable` — implemented and exercised by at least one story
   - `deprecated` — superseded; consumers must migrate
+- **Replan lifecycle for `status`** — when `sam-replan` processes a revised PRD:
+  - *Feature removed* → the contract is set to `deprecated`. The contract file is **not** deleted; code that implements it remains in place until the user explicitly removes it.
+  - *Feature modified, story already done* → the contract `version` is bumped and the owning story is marked `needs-rebuild`. The contract stays `stable` (the new version is the current truth).
+  - *Feature modified, story not yet built* → the contract is updated in place; `status` remains `draft` or `stable` as-is.
+  - *Feature added* → new contracts are created at `draft`, same as the `extend` workflow.
+  - A `deprecated` contract must not be referenced by any new story's `consumes:` list. Existing stories that consume it are flagged in the impact summary for the user to address.
+  - Deprecation is permanent within a plan cycle — there is no "un-deprecate". If the feature returns, a new contract with a new id is created.
 - `owner_story` — the story whose `produces:` list contains this contract. Exactly one. `null` only for contracts that pre-exist the planning run (legacy code).
 - `version` — pinned in story `consumes:` entries via `id@version` when a breaking change is needed; otherwise consumers always read latest.
 

_sam/core/resources/story-schema.md

@@ -31,7 +31,7 @@ id: STORY-003                         # stable identifier; never renumber
 epic: EPIC-001                        # parent epic id (or null for ad-hoc stories)
 kind: feature                         # feature | integration | scaffolding
 title: User can reset password       # one-line summary, no trailing period
-status: ready                         # draft | ready | in-progress | done | blocked
+status: ready                         # draft | ready | in-progress | done | blocked | needs-rebuild | obsolete
 priority: P1                          # P0 (critical) | P1 (normal) | P2 (nice-to-have)
 prd: ../../prd.md                     # relative path from this file to the source PRD (or null)
 depends_on: [STORY-001]               # list of story ids that must be `done` first; [] if none
@@ -52,6 +52,11 @@ created: 2026-05-13                   # YYYY-MM-DD; never changes after creation
   - `ready` → `in-progress` (when `build-tdd` picks it up)
   - `in-progress` → `done` (when `build-tdd` completes all phases)
   - any → `blocked` (when retry limit hit; include reason in body)
+  - `done` → `needs-rebuild` (when a contract this story produces has changed; code is kept but story must be re-built when user confirms)
+  - `needs-rebuild` → `in-progress` (when user confirms rebuild; `build-tdd` picks it up again)
+  - `done` → `obsolete` (when the feature is removed from the PRD; code is not deleted but story is retired)
+  - `ready` → `obsolete` (when the feature is removed before build starts)
+  - `in-progress` → `obsolete` (when the feature is removed during build)
 - `priority` — drives execution order in `plan-n-build`.
 - `prd` — relative link so agents can pull PRD context without re-deriving it.
 - `depends_on` — `plan-n-build` honors this when ordering execution.

_sam/core/workflows/replan/steps/step-01-diff-prd.md

@@ -0,0 +1,196 @@
+---
+step: 1
+name: diff-prd
+description: Compare revised PRD against current sdocs/prd.md and categorize each requirement as added, modified, removed, or unchanged
+agents: [architect]
+---
+
+# Step 1: Diff Revised PRD Against Current PRD
+
+**Agent:** Atlas (System Architect)
+
+**Purpose:** Perform a semantic, section-by-section comparison of a revised PRD against the current `sdocs/prd.md`. Every requirement is categorized as `added | modified | removed | unchanged`. The structured diff report drives all downstream phases — an incorrect classification here will cascade through impact analysis and artifact updates.
+
+---
+
+## ENTRY CONDITIONS
+
+- Revised PRD file exists and is readable
+- `sdocs/prd.md` (or root `prd.md`) exists and is readable
+- `sdocs/architecture-ref.md` exists (needed for context on architectural constraints)
+- `sdocs/stories/` exists with at least one story file (otherwise use `plan`, not `replan`)
+
+If any precondition fails, halt and tell the user which file is missing.
+
+---
+
+## REQUIRED READING
+
+Before any analysis:
+- The revised PRD — read in full
+- `sdocs/prd.md` — read in full (this is the baseline for the diff)
+- `sdocs/architecture-ref.md` — especially `## Key Architectural Decisions` and `## System Shape` (to understand whether changes cross architectural boundaries)
+
+---
+
+## PROCESS
+
+### 1.1 Inventory Current PRD Sections
+
+Parse the current `sdocs/prd.md` and build an inventory of every requirement-bearing section:
+
+```yaml
+sections:
+  - id: <section-slug>          # derived from heading text
+    heading: <full heading>
+    level: <h2 | h3 | h4>
+    type: feature | constraint | scope | meta
+    acceptance_criteria: [<list of ACs if present>]
+    content_hash: <for quick unchanged detection>
+```
+
+Focus on `## Features`, `## Acceptance Criteria`, `## Constraints`, and `## Out of Scope`. Meta sections (title, overview, changelog) are tracked but classified separately.
+
+### 1.2 Inventory Revised PRD Sections
+
+Repeat the same parse on the revised PRD. Use identical slugging rules so sections can be matched by id.
+
+### 1.3 Match and Classify
+
+For each section in the union of both inventories:
+
+| Current PRD | Revised PRD | Classification |
+|-------------|-------------|----------------|
+| present     | present, same content | `unchanged` |
+| present     | present, different content | `modified` |
+| present     | absent | `removed` |
+| absent      | present | `added` |
+
+For `modified` sections, drill into the specific changes:
+
+```yaml
+modification_detail:
+  section: <id>
+  changes:
+    - field: acceptance_criteria
+      type: ac-added | ac-removed | ac-changed
+      before: <text or null>
+      after: <text or null>
+    - field: scope
+      type: narrowed | broadened | reframed
+      before: <text>
+      after: <text>
+    - field: constraints
+      type: added | removed | changed
+      before: <text or null>
+      after: <text or null>
+```
+
+### 1.4 Detect Renames and Moves
+
+Before finalizing a `removed` + `added` pair, check for potential renames:
+- If a removed section and an added section share >70% content similarity, flag them as a **rename candidate**
+- Present rename candidates in the diff report for human verification
+- Do NOT auto-classify renames as `unchanged` — classify as `modified` with a rename note
+
+### 1.5 Generate Diff Summary
+
+Produce a count summary:
+
+```yaml
+summary:
+  total_sections: <N>
+  added: <N>
+  modified: <N>
+  removed: <N>
+  unchanged: <N>
+  rename_candidates: <N>
+```
+
+If removed + modified sections exceed 80% of total, append a warning:
+
+> ⚠ More than 80% of requirements are affected. Consider using `plan --force` for a full rewrite instead.
+
+### 1.6 Write Diff Report
+
+Write the structured diff to `sdocs/replans/<YYYY-MM-DD>-<slug>-diff.md`:
+
+```markdown
+---
+replan_slug: <slug derived from the primary change>
+phase: replan-step-1
+date: <today>
+revised_prd: <path to revised PRD>
+current_prd: sdocs/prd.md
+---
+
+# PRD Diff — <slug>
+
+## Summary
+- Total sections: N
+- Added: N
+- Modified: N
+- Removed: N
+- Unchanged: N
+
+## Added Sections
+| Section | Heading | Type |
+|---------|---------|------|
+| <id>    | <heading> | feature |
+
+## Modified Sections
+| Section | Heading | What Changed |
+|---------|---------|--------------|
+| <id>    | <heading> | AC added, scope broadened |
+
+### Modification Details
+#### <section-id>
+- **Before:** <relevant text>
+- **After:** <relevant text>
+- **Change type:** <ac-added, scope-broadened, etc.>
+
+## Removed Sections
+| Section | Heading | Type |
+|---------|---------|------|
+| <id>    | <heading> | feature |
+
+## Unchanged Sections
+| Section | Heading |
+|---------|---------|
+| <id>    | <heading> |
+
+## Rename Candidates
+| Removed | Added | Similarity |
+|---------|-------|------------|
+| <old-id> | <new-id> | ~75% |
+```
+
+The slug is derived from the most significant change in the revised PRD (e.g. `title-length-update`, `drop-tags-feature`). If there is no clear dominant change, use a generic slug like `multi-change`.
+
+---
+
+## GATE — DIFF PASSES WHEN
+
+- [ ] Every section in the current PRD is accounted for (classified as `modified`, `removed`, or `unchanged`)
+- [ ] Every section in the revised PRD is accounted for (classified as `modified`, `added`, or `unchanged`)
+- [ ] No section is left unclassified
+- [ ] Every `modified` section has a `modification_detail` entry explaining what changed
+- [ ] Rename candidates (if any) are flagged, not silently absorbed
+- [ ] Diff report written to `sdocs/replans/<YYYY-MM-DD>-<slug>-diff.md`
+- [ ] Summary counts are internally consistent (`added + modified + removed + unchanged = total unique sections across both PRDs`)
+
+---
+
+## FAILURE MODES
+
+- **Unreadable PRD:** Halt with error message identifying which file could not be parsed.
+- **Completely different structure:** If no sections match between current and revised PRD (0 unchanged, 0 modified), warn that the PRDs share no common structure and recommend `plan --force` instead.
+- **Ambiguous classification:** If a section cannot be confidently classified (e.g. heading matches but content is entirely rewritten), classify as `modified` with a note — never leave it unclassified.
+
+---
+
+## NEXT
+
+→ Step 2: Impact Analysis (`step-02-impact-analysis.md`)
+
+Atlas passes the structured diff report to the next phase, which walks the contract dependency graph to determine which artifacts are affected by each modified or removed requirement.