cc-devflow 4.5.4 → 4.5.6

package/docs/examples/START-HERE.md

@@ -64,9 +64,9 @@ Use this when the only thing you know is the file in front of you.
 
 | If the main file you have is... | You are probably here | Read this first |
 | --- | --- | --- |
-| `ROADMAP.md` | `cc-roadmap` | [pdca-loop/ROADMAP.md](./pdca-loop/ROADMAP.md) |
-| `roadmap-tracking.json` | `cc-roadmap` machine truth source for roadmap + backlog | [pdca-loop/roadmap-tracking.json](./pdca-loop/roadmap-tracking.json) |
-| `BACKLOG.md` | `cc-roadmap` -> `cc-plan` handoff | [pdca-loop/BACKLOG.md](./pdca-loop/BACKLOG.md) |
+| `roadmap.json` | `cc-roadmap` editable machine truth source | [pdca-loop/roadmap.json](./pdca-loop/roadmap.json) |
+| `ROADMAP.md` | `cc-roadmap` generated human view | [pdca-loop/ROADMAP.md](./pdca-loop/ROADMAP.md) |
+| `BACKLOG.md` | deprecated `cc-roadmap` -> `cc-plan` projection | [pdca-loop/BACKLOG.md](./pdca-loop/BACKLOG.md) |
 | `design.md` | `cc-plan` | [pdca-loop/design.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md) or [full-design-blocked/design.md](./full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md) |
 | `tasks.md` | `cc-plan` or `cc-do` | [pdca-loop/tasks.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md) |
 | `task-manifest.json` | `cc-do` | [pdca-loop/task-manifest.json](./pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json) |

package/docs/examples/example-bindings.json

@@ -1,12 +1,12 @@
 {
-  "updatedAt": "2026-04-28",
+  "updatedAt": "2026-05-06",
   "skills": {
-    "cc-roadmap": "4.4.1",
-    "cc-plan": "3.7.1",
-    "cc-investigate": "1.2.1",
-    "cc-do": "1.6.1",
+    "cc-roadmap": "5.0.0",
+    "cc-plan": "3.7.7",
+    "cc-investigate": "1.2.2",
+    "cc-do": "1.6.2",
     "cc-check": "1.10.1",
-    "cc-act": "1.8.1",
+    "cc-act": "1.8.2",
     "cc-spec-init": "1.1.0"
   },
   "examples": [
@@ -15,7 +15,13 @@
       "readme": "docs/examples/pdca-loop/README.md",
       "root": "docs/examples/pdca-loop",
       "changeDir": "docs/examples/pdca-loop/changes/REQ-001-copy-invite-link",
-      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check", "cc-act"],
+      "covers": [
+        "cc-roadmap",
+        "cc-plan",
+        "cc-do",
+        "cc-check",
+        "cc-act"
+      ],
       "expectedShipMode": "create-pr"
     },
     {
@@ -23,7 +29,12 @@
       "readme": "docs/examples/full-design-blocked/README.md",
       "root": "docs/examples/full-design-blocked",
       "changeDir": "docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import",
-      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check"],
+      "covers": [
+        "cc-roadmap",
+        "cc-plan",
+        "cc-do",
+        "cc-check"
+      ],
       "expectedShipMode": "none"
     },
     {
@@ -31,7 +42,13 @@
       "readme": "docs/examples/local-handoff/README.md",
       "root": "docs/examples/local-handoff",
       "changeDir": "docs/examples/local-handoff/changes/REQ-003-audit-log-export",
-      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check", "cc-act"],
+      "covers": [
+        "cc-roadmap",
+        "cc-plan",
+        "cc-do",
+        "cc-check",
+        "cc-act"
+      ],
       "expectedShipMode": "local-handoff"
     }
   ]

package/docs/examples/full-design-blocked/BACKLOG.md

@@ -1,12 +1,14 @@
 # BACKLOG
 
+> Deprecated projection. Edit `roadmap.json` instead.
+
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 ## Queue
 

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`
+- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.7`, `cc-do@1.6.2`, `cc-check@1.10.1`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 
@@ -40,9 +40,9 @@ The sample shows what happens when implementation moved before the integration d
 
 ## Artifact Map
 
-- `ROADMAP.md`
-- `roadmap-tracking.json` (shared roadmap/backlog truth)
-- `BACKLOG.md`
+- `roadmap.json` (editable roadmap truth)
+- `ROADMAP.md` (generated view)
+- `BACKLOG.md` (deprecated projection)
 - `changes/REQ-002-bulk-invite-import/planning/design.md`
 - `changes/REQ-002-bulk-invite-import/planning/tasks.md`
 - `changes/REQ-002-bulk-invite-import/planning/task-manifest.json`

package/docs/examples/full-design-blocked/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`
@@ -44,10 +44,24 @@
 - Kill signal / stop condition: if the team cannot specify bulk invite semantics before implementation starts
 
 ## Implementation Tracking
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 <!-- roadmap-tracking:start -->
 | RM-ID | Item | Stage | Priority | Primary Capability | Secondary Capabilities | Expected Spec Delta | Depends On | Status | REQ | Progress |
 |------|------|------|------|------|------|------|------|------|------|------|
 | RM-010 | Add CSV bulk invite import for admins | Stage 2 | P1 | cap-bulk-invite-import | cap-workspace-membership | define import semantics before widening current truth | - | Verification blocked | REQ-002 | 80% |
 <!-- roadmap-tracking:end -->
+
+
+## Technical Architecture
+
+```mermaid
+flowchart TD
+  roadmap_json["roadmap.json"]
+  roadmap_md["ROADMAP.md"]
+  backlog_md["BACKLOG.md (deprecated)"]
+  cc_plan["cc-plan"]
+  roadmap_json -->|renders| roadmap_md
+  roadmap_json -->|projects| backlog_md
+  roadmap_md -->|hands off| cc_plan
+```

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.7`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`
 - Why not `tiny-design`: the feature crosses import parsing, invite rules, billing limits, duplicate handling, and audit logging
@@ -42,6 +42,43 @@
   - enterprise SCIM provisioning
   - background retry orchestration
 
+## PRD-Grade Requirement Brief
+
+- Problem statement: admins onboarding larger teams spend too much time sending individual invites, and they cannot predict how duplicates, invalid rows, and seat limits will resolve in bulk.
+- Solution summary: admins upload a CSV and receive deterministic row outcomes before the invite flow can be trusted for execution.
+- Actors / personas:
+  - workspace admin onboarding 20-200 collaborators
+  - support operator explaining invite outcomes
+- Primary user stories:
+
+| ID | Actor | Wants | Benefit | Acceptance / evidence |
+|----|-------|-------|---------|-----------------------|
+| US-001 | Workspace admin | upload a CSV of invite emails | invite many collaborators without one-by-one entry | mixed valid rows produce visible accepted outcomes |
+| US-002 | Workspace admin | see duplicate, invalid, and over-limit row states | understand what happened without support help | every skipped or rejected row has a reason |
+| US-003 | Support operator | trust the audit trail for each row outcome | explain invite history consistently | audit entries match visible row outcomes |
+
+- Edge / recovery stories:
+
+| ID | Actor | Failure / boundary | Desired outcome | Acceptance / evidence |
+|----|-------|--------------------|-----------------|-----------------------|
+| US-EDGE-001 | Workspace admin | CSV contains duplicates and invalid emails | safe rows can proceed while bad rows are explained | rule matrix covers duplicate and invalid cases |
+| US-EDGE-002 | Workspace admin | upload exceeds seat limits | over-limit rows are rejected consistently | billing-seat tests match UI summary |
+
+- Implementation decisions:
+  - Freeze one row-outcome matrix before execution resumes.
+  - Reuse the existing invite engine, billing seat checks, and audit log contract.
+  - Keep enterprise provisioning and background retry orchestration outside this requirement.
+- Testing decisions:
+  - Test row semantics through bulk-import rules and the admin upload flow.
+  - Verify audit mapping against visible row outcomes.
+  - Use existing invite and admin panel tests as prior art.
+- Out of scope:
+  - enterprise SCIM provisioning
+  - background job redesign
+  - rollback wizard for partial success
+- Further notes:
+  - This design remains blocked until duplicate and seat-limit semantics are approved.
+
 ## Success Criteria
 
 - Observable success signals:
@@ -83,6 +120,13 @@
 - Deferred questions:
   - whether partial success needs an explicit rollback option
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | approach-approval | Best-effort upload would let duplicate, invalid, and seat-limit semantics drift during execution | Choose Option B and freeze a rule matrix first | Option B | Keep execution blocked until row outcomes are modeled | answered |
+| D2 | ambiguity-blocker | Duplicate and seat-limit outcomes are still not explicit enough for tests or audit mapping | Answer the row-outcome matrix before task generation | pending | `cc-do` must not start implementation until this is answered | asked |
+
 ## Design
 
 - Modules touched:
@@ -131,6 +175,8 @@
 - Ambiguity scan: blocked; duplicate + seat-limit semantics still need sharper wording
 - Feasibility scan: pass
 - Source alignment: pass; roadmap still prioritizes trust over speed
+- PRD brief scan: pass for actors and stories; blocked on duplicate and seat-limit semantics
+- Decision question scan: blocked; `D2` is still unanswered
 - UI / interaction review summary: result states are acceptable if semantics are frozen first
 - DX review summary: execution still needs a single row-outcome matrix
 - Auto-decided items:

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/task-manifest.json

@@ -5,6 +5,103 @@
   "updatedAt": "2026-04-16T12:00:00.000Z",
   "requirementId": "REQ-002",
   "requirementVersion": "REQ-002.v2",
+  "planningMeta": {
+    "reqPlanSkillVersion": "3.7.7",
+    "designVersion": "design.v2",
+    "approvedAt": null,
+    "approvedBy": null,
+    "basedOnOption": "Option B",
+    "requirementBrief": {
+      "problemStatement": "Admins onboarding larger teams need predictable bulk invite behavior for duplicates, invalid rows, and seat limits.",
+      "solutionSummary": "Freeze deterministic CSV row outcomes before executing the bulk invite flow.",
+      "actors": ["workspace admin", "support operator"],
+      "userStories": [
+        {
+          "id": "US-001",
+          "actor": "workspace admin",
+          "want": "upload a CSV of invite emails",
+          "benefit": "invite many collaborators without one-by-one entry",
+          "acceptance": ["Mixed valid rows produce visible accepted outcomes"]
+        },
+        {
+          "id": "US-002",
+          "actor": "workspace admin",
+          "want": "see duplicate, invalid, and over-limit row states",
+          "benefit": "understand what happened without support help",
+          "acceptance": ["Every skipped or rejected row has a reason"]
+        }
+      ],
+      "edgeOrRecoveryStories": [
+        {
+          "id": "US-EDGE-001",
+          "actor": "workspace admin",
+          "boundary": "CSV contains duplicates, invalid emails, or over-limit rows",
+          "desiredOutcome": "safe rows can proceed while bad rows are explained",
+          "acceptance": ["Rule matrix covers duplicate, invalid, and seat-limit cases"]
+        }
+      ],
+      "implementationDecisions": ["Freeze one row-outcome matrix before execution resumes"],
+      "testingDecisions": ["Test row semantics through bulk-import rules and the admin upload flow"],
+      "outOfScope": ["enterprise SCIM provisioning", "background job redesign", "rollback wizard for partial success"],
+      "furtherNotes": ["Design remains blocked until duplicate and seat-limit semantics are approved"]
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": ["Best-effort upload would hide duplicate, invalid, and seat-limit semantics", "Audit mapping depends on deterministic row outcomes"],
+        "recommendation": "Choose Option B and freeze a rule matrix first",
+        "options": [
+          {
+            "id": "A",
+            "label": "Front-end-only CSV upload",
+            "recommended": false,
+            "completeness": "5/10",
+            "good": "Fastest prototype and reuses the existing single-invite API",
+            "costRisk": "Lets hidden backend edge cases define user-visible semantics"
+          },
+          {
+            "id": "B",
+            "label": "Rule matrix first",
+            "recommended": true,
+            "completeness": "9/10",
+            "good": "Makes billing, duplicate, invalid, and audit behavior reviewable",
+            "costRisk": "Requires one more planning pass before execution can start"
+          }
+        ],
+        "userChoice": "B",
+        "impact": "cc-do stays blocked until row outcomes are modeled",
+        "status": "answered"
+      },
+      {
+        "questionId": "D2",
+        "gate": "ambiguity-blocker",
+        "knownEvidence": ["Duplicate and seat-limit outcomes are still not explicit enough for tests", "Audit entries must match visible row outcomes"],
+        "recommendation": "Answer the row-outcome matrix before task generation",
+        "options": [
+          {
+            "id": "A",
+            "label": "Block execution until matrix is explicit",
+            "recommended": true,
+            "completeness": "10/10",
+            "good": "Prevents cc-do from inventing semantics during implementation",
+            "costRisk": "Requires user/product input before coding can continue"
+          },
+          {
+            "id": "B",
+            "label": "Let implementation choose defaults",
+            "recommended": false,
+            "completeness": "4/10",
+            "good": "Starts coding sooner with fewer planning minutes",
+            "costRisk": "Creates invisible product decisions inside implementation tasks"
+          }
+        ],
+        "userChoice": null,
+        "impact": "No executable task manifest should be approved until this is answered",
+        "status": "asked"
+      }
+    ]
+  },
   "currentTaskId": null,
   "activePhase": null,
   "tasks": [

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.7`
 - Source roadmap item: `RM-010`
 - Source roadmap version: `roadmap.v2`
 
@@ -15,6 +15,13 @@
 - Frozen decisions:
   - bulk invite results must classify each row
   - audit behavior must match visible results
+- PRD brief:
+  - Problem statement: admins need predictable CSV invite outcomes for duplicates, invalid rows, and seat limits
+  - Solution summary: freeze deterministic row outcomes before executing the bulk invite flow
+  - User stories covered: `US-001`, `US-002`, `US-003`, `US-EDGE-001`, `US-EDGE-002`
+  - Implementation decisions: reuse invite engine, billing checks, and audit contract after the row-outcome matrix is approved
+  - Testing decisions: test bulk-import rules, admin upload flow, and audit mapping
+  - Out of scope: SCIM provisioning, background jobs, rollback wizard
 - Read first:
   - `design.md`
   - `src/admin/BulkInvitePanel.tsx`

package/docs/examples/full-design-blocked/roadmap.json

@@ -0,0 +1,123 @@
+{
+  "version": 3,
+  "outputPolicy": {
+    "documentLanguage": "en"
+  },
+  "meta": {
+    "roadmapVersion": "roadmap.v2",
+    "skillVersion": "5.0.0",
+    "status": "active",
+    "lastUpdated": "2026-04-19",
+    "currentFocusStage": "Stage 2"
+  },
+  "context": {
+    "planningPosture": "",
+    "evidenceMaturity": "",
+    "canonicalTerms": [],
+    "durableDecisionSources": []
+  },
+  "evidence": [],
+  "route": {
+    "recommended": "",
+    "whyThisWinsNow": "",
+    "rejectedRoutes": [],
+    "firstSignal": "",
+    "killSignal": ""
+  },
+  "stages": [],
+  "items": [
+    {
+      "rmId": "RM-010",
+      "item": "Add CSV bulk invite import for admins",
+      "stage": "Stage 2",
+      "priority": "P1",
+      "primaryCapability": "cap-bulk-invite-import",
+      "secondaryCapabilities": [
+        "cap-workspace-membership"
+      ],
+      "expectedSpecDelta": "define import semantics before widening current truth",
+      "dependsOn": [],
+      "status": "Verification blocked",
+      "req": "REQ-002",
+      "progress": "80%",
+      "backlog": {
+        "capabilityGap": "admins can invite one user at a time but cannot safely import invite batches",
+        "evidence": "sales onboarding asks for spreadsheet-scale invites",
+        "parallelWith": [],
+        "unknowns": "duplicate-email policy, seat enforcement, audit fan-out",
+        "nextDecision": "reroute to full design before more execution work",
+        "ready": true,
+        "whyNow": "demand is real, but the contract is too wide to keep improvising in code",
+        "successSignal": "the capability has a trusted import contract before implementation resumes",
+        "entryConstraints": "must freeze limits, duplicates, warnings, and audit behavior first",
+        "openRisks": "another partial implementation pass would deepen the semantic drift",
+        "firstPlanningQuestion": "which subflows share one import contract and which need explicit splits?",
+        "requiredContextToLoad": "invite limits, billing rules, duplicate handling, audit logging",
+        "whyReadyNow": "the blocker is design truth, not implementation effort",
+        "parked": false,
+        "parkedReason": "",
+        "triggerToReopen": "",
+        "missingEvidence": ""
+      }
+    }
+  ],
+  "handoff": {
+    "readyForCcPlan": [
+      "RM-010"
+    ],
+    "parked": [],
+    "serialSpine": [
+      "RM-010"
+    ],
+    "parallelWaves": []
+  },
+  "architecture": {
+    "diagramType": "flowchart",
+    "nodes": [
+      {
+        "id": "roadmap_json",
+        "label": "roadmap.json"
+      },
+      {
+        "id": "roadmap_md",
+        "label": "ROADMAP.md"
+      },
+      {
+        "id": "backlog_md",
+        "label": "BACKLOG.md (deprecated)"
+      },
+      {
+        "id": "cc_plan",
+        "label": "cc-plan"
+      }
+    ],
+    "edges": [
+      {
+        "from": "roadmap_json",
+        "to": "roadmap_md",
+        "label": "renders"
+      },
+      {
+        "from": "roadmap_json",
+        "to": "backlog_md",
+        "label": "projects"
+      },
+      {
+        "from": "roadmap_md",
+        "to": "cc_plan",
+        "label": "hands off"
+      }
+    ]
+  },
+  "backlogMeta": {
+    "roadmapVersion": "roadmap.v2",
+    "skillVersion": "4.4.1",
+    "currentFocusStage": "Stage 2"
+  },
+  "dependencyHandoff": {
+    "serialSpine": "RM-010",
+    "parallelReadyNextWave": "-",
+    "notesOnBlockers": "verification is blocked until the import contract covers limits, duplicates, billing, and audit consistency"
+  },
+  "lastSyncedAt": "2026-04-19"
+}

package/docs/examples/local-handoff/BACKLOG.md

@@ -1,12 +1,14 @@
 # BACKLOG
 
+> Deprecated projection. Edit `roadmap.json` instead.
+
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 ## Queue
 

package/docs/examples/local-handoff/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`, `cc-act@1.8.1`
+- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.7`, `cc-do@1.6.2`, `cc-check@1.10.1`, `cc-act@1.8.2`
 
 This example shows verified work that is **ready to move forward**, but `cc-act` still chooses `local-handoff`.
 
@@ -36,9 +36,9 @@ But the current environment is local-only:
 
 ## Artifact Map
 
-- `ROADMAP.md`
-- `roadmap-tracking.json` (shared roadmap/backlog truth)
-- `BACKLOG.md`
+- `roadmap.json` (editable roadmap truth)
+- `ROADMAP.md` (generated view)
+- `BACKLOG.md` (deprecated projection)
 - `changes/REQ-003-audit-log-export/planning/design.md`
 - `changes/REQ-003-audit-log-export/planning/tasks.md`
 - `changes/REQ-003-audit-log-export/planning/task-manifest.json`

package/docs/examples/local-handoff/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v3`
-- Skill version: `4.4.1`
+- Skill version: `5.0.0`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`
@@ -36,10 +36,24 @@
 - Kill signal / stop condition: if export requires a shared reporting pipeline redesign
 
 ## Implementation Tracking
-- Tracking source: `roadmap-tracking.json`
+- Roadmap state source: `roadmap.json`
 
 <!-- roadmap-tracking:start -->
 | RM-ID | Item | Stage | Priority | Primary Capability | Secondary Capabilities | Expected Spec Delta | Depends On | Status | REQ | Progress |
 |------|------|------|------|------|------|------|------|------|------|------|
 | RM-020 | Add an audit-log export summary download | Stage 2 | P1 | cap-audit-log-export | - | codify local export summary truth | - | Local handoff | REQ-003 | 100% |
 <!-- roadmap-tracking:end -->
+
+
+## Technical Architecture
+
+```mermaid
+flowchart TD
+  roadmap_json["roadmap.json"]
+  roadmap_md["ROADMAP.md"]
+  backlog_md["BACKLOG.md (deprecated)"]
+  cc_plan["cc-plan"]
+  roadmap_json -->|renders| roadmap_md
+  roadmap_json -->|projects| backlog_md
+  roadmap_md -->|hands off| cc_plan
+```

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.1`
+- CC-Plan skill version: `3.7.7`
 - Requirement ID: `REQ-003`
 - Design mode: `tiny-design`
 - Why this stays `tiny-design`: the patch adds one export action inside the existing admin audit UI without changing data contracts
@@ -34,6 +34,23 @@
   - keep the action inside the current admin panel
 - Upgrade trigger to `full-design`: if export needs background generation or new reporting contracts
 
+## PRD-Grade Brief
+
+- Problem statement: admins can review audit summary rows in the UI, but taking them into weekly reports requires manual copying.
+- Solution summary: admins can download the currently visible audit summary rows as a CSV from the existing admin panel.
+- Actors / personas:
+  - workspace admin reviewing weekly activity
+- User stories:
+  - US-001: As a workspace admin, I want to download visible audit summary rows as CSV, so that I can include them in weekly reporting without manual copying.
+- Implementation decisions:
+  - Export only the rows already visible in the panel.
+  - Keep CSV as the only output format.
+- Testing decisions:
+  - Test through the admin panel action and visible row data.
+  - Existing audit summary panel tests are the prior art.
+- Out of scope: JSON export, scheduled reporting, and shared reporting backend work.
+- Further notes: richer machine-readable exports should become a separate requirement.
+
 ## Validation
 
 - Primary check: targeted panel test proves the export action is available and uses current summary rows
@@ -56,8 +73,16 @@
 - Scope scan: pass
 - Ambiguity scan: pass
 - Feasibility scan: pass
+- PRD brief scan: pass; the export story and scope boundaries are explicit
+- Decision question scan: pass; `D1` approved the tiny-design CSV-export boundary
 - Final recommendation: approved as `tiny-design`
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | approach-approval | Existing admin panel already owns visible summary rows and the change does not need a reporting backend | Approve the tiny-design CSV export | Tiny design CSV export | Export only visible rows from the current panel; do not create reporting contracts | answered |
+
 ## Approval
 
 - User approval status: approved

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/planning/task-manifest.json

@@ -5,6 +5,61 @@
   "updatedAt": "2026-04-16T14:20:00.000Z",
   "requirementId": "REQ-003",
   "requirementVersion": "REQ-003.v1",
+  "planningMeta": {
+    "reqPlanSkillVersion": "3.7.7",
+    "designVersion": "design.v1",
+    "approvedAt": "2026-04-16T13:10:00.000Z",
+    "approvedBy": "user",
+    "basedOnOption": "Tiny design card",
+    "requirementBrief": {
+      "problemStatement": "Admins can review audit summary rows in the UI, but weekly reporting requires manual copying.",
+      "solutionSummary": "Add a CSV download action for the currently visible audit summary rows.",
+      "actors": ["workspace admin reviewing weekly activity"],
+      "userStories": [
+        {
+          "id": "US-001",
+          "actor": "workspace admin",
+          "want": "download visible audit summary rows as CSV",
+          "benefit": "include them in weekly reporting without manual copying",
+          "acceptance": ["Panel behavior test proves the export action uses current summary rows"]
+        }
+      ],
+      "edgeOrRecoveryStories": [],
+      "implementationDecisions": ["Export only rows already visible in the panel", "Keep CSV as the only output format"],
+      "testingDecisions": ["Test through the admin panel action and visible row data"],
+      "outOfScope": ["JSON export", "scheduled reporting", "shared reporting backend"],
+      "furtherNotes": ["Richer machine-readable exports should become a separate requirement"]
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": ["Existing admin panel already owns the visible summary rows", "No reporting backend is needed for the first useful export"],
+        "recommendation": "Approve the tiny-design CSV export",
+        "options": [
+          {
+            "id": "A",
+            "label": "Tiny design CSV export",
+            "recommended": true,
+            "completeness": "8/10",
+            "good": "Solves weekly reporting friction with the current panel data",
+            "costRisk": "Does not handle JSON, scheduling, or shared reporting contracts"
+          },
+          {
+            "id": "B",
+            "label": "Shared reporting pipeline",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "Could support more formats and future scheduled reports",
+            "costRisk": "Creates a larger platform surface before the local export is proven"
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do exports only visible rows from the current panel and avoids new reporting contracts",
+        "status": "answered"
+      }
+    ]
+  },
   "currentTaskId": null,
   "activePhase": null,
   "tasks": [