cc-devflow 4.3.0 → 4.5.0

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

@@ -0,0 +1,154 @@
+# DESIGN
+
+## Document Meta
+
+- Requirement version: `REQ-002.v2`
+- Design version: `design.v2`
+- CC-Plan skill version: `3.5.4`
+- 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
+- Design status: `in-review`
+- Source roadmap item: `RM-010`
+- Source roadmap version: `roadmap.v2`
+- Source roadmap skill version: `4.1.0`
+- Date: `2026-04-16`
+- Owner: `product-owner`
+
+## Source Handoff
+
+- Source stage: `Stage 2`
+- Why now from roadmap: admin demand is real, but trust risks dominate the design
+- Inherited success signal: admins can predict every bulk invite outcome
+- Inherited kill signal: if semantics remain underspecified, stop execution and reopen planning
+- Inherited dependencies:
+  - existing seat limit enforcement
+  - current audit log contract
+- Inherited non-goals:
+  - no background job redesign
+  - no enterprise provisioning layer
+- Upstream evidence: support notes from larger teams
+- Assumptions to re-validate:
+  - duplicate emails can be skipped safely
+  - seat-limit failures can be partially accepted
+
+## Requirement Snapshot
+
+- Raw ask: admins want to upload a CSV of emails instead of inviting people one by one
+- User: workspace admins onboarding 20-200 collaborators
+- Pain: manual invites are too slow and error-prone
+- Smallest viable wedge: a CSV upload that clearly predicts accepted, skipped, and rejected rows
+- Out of scope:
+  - enterprise SCIM provisioning
+  - background retry orchestration
+
+## Success Criteria
+
+- Observable success signals:
+  - admin sees deterministic results for each CSV row
+  - duplicate, over-limit, and invalid rows are explained consistently
+- Business / operator success signals:
+  - support no longer manually explains bulk invite outcomes
+- Abort signals:
+  - billing-seat or audit outcomes differ from the documented plan
+
+## Options Considered
+
+### Option A
+
+- Shape: front-end-only CSV parsing with best-effort invite submission
+- Reuses: existing single-invite API
+- Pros: fast to prototype
+- Cons: semantics depend on hidden backend edge cases
+- Risks: partial success becomes impossible to explain
+
+### Option B
+
+- Shape: freeze a rule matrix first, then implement import around it
+- Reuses: existing invite engine, but with explicit row-state mapping
+- Pros: makes billing, duplicate, and audit behavior reviewable
+- Cons: more upfront planning
+- Risks: may expose a need for additional shared contracts
+
+## Approved Direction
+
+- Approved option: `Option B`
+- Why this is the best trade-off now: the import UX is not trustworthy until row outcomes and seat limits are explicitly modeled
+- Why not the other options now: best-effort submission would let implementation invent semantics during execution
+- What we explicitly rejected: a UI-only CSV uploader that guesses row behavior
+- Frozen decisions:
+  - bulk import must classify each row into accepted, skipped, or rejected
+  - seat-limit failures cannot silently pass
+  - audit log entries must match the visible row outcome
+- Deferred questions:
+  - whether partial success needs an explicit rollback option
+
+## Design
+
+- Modules touched:
+  - admin invite UI
+  - invite validation rules
+  - billing / seat limit decision points
+  - audit log mapping
+- Data flow:
+  - CSV parse -> row validation -> invite decision -> row result summary -> audit log write
+- Contracts:
+  - one rule matrix for duplicate, invalid, over-limit, and existing-member rows
+- Error handling:
+  - every rejected row must expose a user-readable reason
+- Rollout / migration:
+  - release only after rule matrix and verification plan are both approved
+
+## File Plan
+
+| File | Change | Reason |
+|------|--------|--------|
+| `src/admin/BulkInvitePanel.tsx` | update | upload and result display |
+| `src/admin/BulkInvitePanel.test.tsx` | update | row-state behavior tests |
+| `src/invite/bulk-import.ts` | add | import rule orchestration |
+| `src/invite/bulk-import.test.ts` | add | duplicate / seat / invalid cases |
+| `src/audit/invite-log.ts` | update | audit consistency |
+
+## Validation Strategy
+
+- Unit: rule matrix tests for each row outcome
+- Integration: admin upload flow covering duplicates and seat-limit failures
+- Manual: CSV import with mixed valid and invalid rows
+- Observability / evidence: row summary and audit log must agree
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| duplicate handling is underspecified | high | freeze explicit rule matrix before continuing |
+| audit and visible row summary diverge | high | verify audit mapping in integration review |
+
+## Review Gate
+
+- Placeholder scan: pass
+- Consistency scan: fail; current implementation evidence still assumes some row outcomes not frozen here
+- Scope scan: pass
+- Ambiguity scan: blocked; duplicate + seat-limit semantics still need sharper wording
+- Feasibility scan: pass
+- Source alignment: pass; roadmap still prioritizes trust over speed
+- 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:
+  - CSV upload stays inside admin settings
+- Taste decisions:
+  - show result rows directly after parse instead of a second confirmation wizard
+- User challenges:
+  - can admins predict partial failure without reading documentation?
+- Recommendation: do not declare this design complete until the row-outcome matrix is explicit
+
+## Approval
+
+- User approval status: `in-review`
+- Follow-up changes after review:
+  - add a rule matrix section before execution resumes
+
+## First-Read Test
+
+- 10 秒内能看出这次为什么不是 `tiny-design`
+- 10 秒内能看出批准方案和被拒方案的边界
+- `cc-do` 是否还能被迫二次设计；这里答案仍然是“会”，所以设计还不能诚实闭环

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

@@ -0,0 +1,146 @@
+{
+  "changeId": "REQ-002",
+  "goal": "Add a trustworthy CSV bulk invite flow for admins without inventing row-outcome semantics during execution.",
+  "createdAt": "2026-04-16T09:00:00.000Z",
+  "updatedAt": "2026-04-16T12:00:00.000Z",
+  "requirementId": "REQ-002",
+  "requirementVersion": "REQ-002.v2",
+  "currentTaskId": null,
+  "activePhase": null,
+  "tasks": [
+    {
+      "id": "T001",
+      "title": "[TEST] Add failing tests for duplicate and over-limit row outcomes",
+      "type": "TEST",
+      "phase": 1,
+      "parallel": false,
+      "dependsOn": [],
+      "touches": ["bulk-invite-rules"],
+      "files": ["src/invite/bulk-import.test.ts"],
+      "run": ["npm test -- src/invite/bulk-import.test.ts"],
+      "checks": ["tests fail before implementation"],
+      "acceptance": ["dangerous row outcomes are reproduced as explicit failing tests"],
+      "verification": ["npm test -- src/invite/bulk-import.test.ts"],
+      "evidence": ["failing test output"],
+      "context": {
+        "readFiles": ["design.md", "tasks.md", "src/invite/bulk-import.ts"],
+        "commands": ["npm test -- src/invite/bulk-import.test.ts"],
+        "notes": ["freeze row semantics before broader execution"]
+      },
+      "reviews": { "spec": "pass", "code": "pass" },
+      "status": "passed",
+      "attempts": 1,
+      "maxRetries": 1
+    },
+    {
+      "id": "T002",
+      "title": "[IMPL] Implement the initial bulk invite row classification",
+      "type": "IMPL",
+      "phase": 1,
+      "parallel": false,
+      "dependsOn": ["T001"],
+      "touches": ["bulk-invite-rules"],
+      "files": ["src/invite/bulk-import.ts"],
+      "run": ["npm test -- src/invite/bulk-import.test.ts"],
+      "checks": ["rule tests pass"],
+      "acceptance": ["bulk invite rows receive deterministic initial states"],
+      "verification": ["npm test -- src/invite/bulk-import.test.ts"],
+      "evidence": ["passing test output", "checkpoint summary"],
+      "context": {
+        "readFiles": ["design.md", "tasks.md", "src/invite/bulk-import.test.ts"],
+        "commands": ["npm test -- src/invite/bulk-import.test.ts"],
+        "notes": ["do not invent partial-failure semantics outside the approved design"]
+      },
+      "reviews": { "spec": "pass", "code": "pass" },
+      "status": "passed",
+      "attempts": 1,
+      "maxRetries": 1
+    },
+    {
+      "id": "T003",
+      "title": "[TEST] Add failing admin panel tests for mixed CSV results",
+      "type": "TEST",
+      "phase": 2,
+      "parallel": false,
+      "dependsOn": ["T002"],
+      "touches": ["admin-bulk-invite-ui"],
+      "files": ["src/admin/BulkInvitePanel.test.tsx"],
+      "run": ["npm test -- src/admin/BulkInvitePanel.test.tsx"],
+      "checks": ["admin panel tests fail before UI integration"],
+      "acceptance": ["mixed row outcomes are visible as UI failures before implementation"],
+      "verification": ["npm test -- src/admin/BulkInvitePanel.test.tsx"],
+      "evidence": ["failing test output"],
+      "context": {
+        "readFiles": ["design.md", "tasks.md", "src/admin/BulkInvitePanel.tsx"],
+        "commands": ["npm test -- src/admin/BulkInvitePanel.test.tsx"],
+        "notes": ["UI must not hide ambiguous row states"]
+      },
+      "reviews": { "spec": "pass", "code": "pass" },
+      "status": "passed",
+      "attempts": 1,
+      "maxRetries": 1
+    },
+    {
+      "id": "T004",
+      "title": "[IMPL] Render bulk invite results in the admin panel",
+      "type": "IMPL",
+      "phase": 2,
+      "parallel": false,
+      "dependsOn": ["T003"],
+      "touches": ["admin-bulk-invite-ui"],
+      "files": ["src/admin/BulkInvitePanel.tsx"],
+      "run": ["npm test -- src/admin/BulkInvitePanel.test.tsx"],
+      "checks": ["admin panel tests pass"],
+      "acceptance": ["admins can see accepted, skipped, and rejected rows in the panel"],
+      "verification": ["npm test -- src/admin/BulkInvitePanel.test.tsx"],
+      "evidence": ["passing test output", "review notes"],
+      "context": {
+        "readFiles": ["design.md", "tasks.md", "src/admin/BulkInvitePanel.test.tsx"],
+        "commands": ["npm test -- src/admin/BulkInvitePanel.test.tsx"],
+        "notes": ["surface row states without redefining backend truth"]
+      },
+      "reviews": { "spec": "pass", "code": "pass" },
+      "status": "passed",
+      "attempts": 1,
+      "maxRetries": 1
+    },
+    {
+      "id": "T005",
+      "title": "Run mixed-surface checks and gather review evidence",
+      "type": "OTHER",
+      "phase": 3,
+      "parallel": false,
+      "dependsOn": ["T004"],
+      "touches": ["quality-gates"],
+      "files": ["src/admin/BulkInvitePanel.tsx", "src/invite/bulk-import.ts"],
+      "run": [
+        "npm test -- src/invite/bulk-import.test.ts",
+        "npm test -- src/admin/BulkInvitePanel.test.tsx"
+      ],
+      "checks": ["targeted tests pass", "review evidence collected"],
+      "acceptance": ["fresh verification evidence exists for cc-check"],
+      "verification": [
+        "npm test -- src/invite/bulk-import.test.ts",
+        "npm test -- src/admin/BulkInvitePanel.test.tsx"
+      ],
+      "evidence": ["passing targeted test output", "review notes"],
+      "context": {
+        "readFiles": ["tasks.md", "task-manifest.json"],
+        "commands": [
+          "npm test -- src/invite/bulk-import.test.ts",
+          "npm test -- src/admin/BulkInvitePanel.test.tsx"
+        ],
+        "notes": ["fresh evidence can still block if the design contract is incomplete"]
+      },
+      "reviews": { "spec": "pass", "code": "pass" },
+      "status": "passed",
+      "attempts": 1,
+      "maxRetries": 1
+    }
+  ],
+  "metadata": {
+    "source": "tasks.md",
+    "generatedBy": "docs-example",
+    "planVersion": 1
+  }
+}

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

@@ -0,0 +1,78 @@
+# TASKS
+
+## Plan Meta
+
+- Requirement version: `REQ-002.v2`
+- Design version: `design.v2`
+- CC-Plan skill version: `3.5.4`
+- Source roadmap item: `RM-010`
+- Source roadmap version: `roadmap.v2`
+
+## Execution Handoff
+
+- Canonical design: `design.md`
+- Execution mode: `single-path`
+- Frozen decisions:
+  - bulk invite results must classify each row
+  - audit behavior must match visible results
+- Read first:
+  - `design.md`
+  - `src/admin/BulkInvitePanel.tsx`
+  - `src/invite/bulk-import.ts`
+  - `src/audit/invite-log.ts`
+- Commands to trust:
+  - `npm test -- src/invite/bulk-import.test.ts`
+  - `npm test -- src/admin/BulkInvitePanel.test.tsx`
+- Do not re-decide:
+  - duplicate handling semantics
+  - seat-limit fallback behavior
+  - audit row-result contract
+- Parallel boundaries: no parallel execution until row-outcome semantics are frozen
+
+## Phase 1: Rule Matrix
+
+- [x] T001 [TEST] Add failing tests for duplicate and over-limit row outcomes (dependsOn:none) `src/invite/bulk-import.test.ts`
+  Goal: 先把最危险的 bulk invite 行为变成红灯。
+  Files: `src/invite/bulk-import.test.ts`
+  Read first: `design.md`, `src/invite/bulk-import.ts`
+  Verification: `npm test -- src/invite/bulk-import.test.ts`
+  Evidence: failing output
+  Ready when: 当前规则文件已经可定位
+
+- [x] T002 [IMPL] Implement the initial bulk invite row classification (dependsOn:T001) `src/invite/bulk-import.ts`
+  Goal: 给 duplicate / over-limit 行为一个最小实现。
+  Files: `src/invite/bulk-import.ts`
+  Read first: `design.md`, `src/invite/bulk-import.test.ts`
+  Verification: `npm test -- src/invite/bulk-import.test.ts`
+  Evidence: passing output + checkpoint
+  Ready when: T001 已见红
+
+## Phase 2: Surface Integration
+
+- [x] T003 [TEST] Add failing admin panel tests for mixed CSV results (dependsOn:T002) `src/admin/BulkInvitePanel.test.tsx`
+  Goal: 在 UI 层看到 mixed row outcomes 的真实表现。
+  Files: `src/admin/BulkInvitePanel.test.tsx`
+  Read first: `design.md`, `src/admin/BulkInvitePanel.tsx`
+  Verification: `npm test -- src/admin/BulkInvitePanel.test.tsx`
+  Evidence: failing output
+  Ready when: T002 已完成
+
+- [x] T004 [IMPL] Render bulk invite results in the admin panel (dependsOn:T003) `src/admin/BulkInvitePanel.tsx`
+  Goal: 把 row outcomes 接进管理界面。
+  Files: `src/admin/BulkInvitePanel.tsx`
+  Read first: `design.md`, `src/admin/BulkInvitePanel.test.tsx`
+  Verification: `npm test -- src/admin/BulkInvitePanel.test.tsx`
+  Evidence: passing output + review notes
+  Ready when: T003 已见红
+
+## Phase 3: Verification
+
+- [x] T005 Run mixed-surface checks and gather review evidence (dependsOn:T004) `bulk invite quality gates`
+  Goal: 为 `cc-check` 准备 bulk invite 的新鲜证据。
+  Files: `src/admin/BulkInvitePanel.tsx`, `src/invite/bulk-import.ts`
+  Read first: `tasks.md`, `task-manifest.json`
+  Verification:
+  - `npm test -- src/invite/bulk-import.test.ts`
+  - `npm test -- src/admin/BulkInvitePanel.test.tsx`
+  Evidence: passing output + review notes
+  Ready when: T004 已完成

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/review/report-card.json

@@ -0,0 +1,52 @@
+{
+  "changeId": "REQ-002",
+  "verdict": "blocked",
+  "overall": "fail",
+  "summary": "verdict=blocked quick=2/2 strict=0/0 review=blocked",
+  "quickGates": [
+    {
+      "name": "bulk-rule-tests",
+      "status": "pass",
+      "command": "npm test -- src/invite/bulk-import.test.ts",
+      "summary": "targeted bulk invite rule tests passed"
+    },
+    {
+      "name": "admin-panel-tests",
+      "status": "pass",
+      "command": "npm test -- src/admin/BulkInvitePanel.test.tsx",
+      "summary": "admin panel tests passed for the current diff"
+    }
+  ],
+  "strictGates": [],
+  "review": {
+    "status": "blocked",
+    "summary": "The implementation evidence is real, but the requirement-level design contract is still incomplete",
+    "details": "Diff review found that duplicate-email and seat-limit semantics are still not frozen tightly enough to trust the current implementation as the requirement truth.",
+    "taskReviews": {
+      "status": "pass",
+      "required": true,
+      "summary": "All completed tasks carry spec/code proof",
+      "reviewers": [],
+      "findings": []
+    },
+    "diffReview": {
+      "status": "blocked",
+      "required": false,
+      "summary": "Requirement-level review says the row-outcome matrix must be reopened in planning",
+      "reviewers": [],
+      "findings": [
+        "duplicate-email behavior is still underspecified",
+        "seat-limit partial-failure semantics are not frozen in design.md"
+      ]
+    },
+    "findings": [
+      "The current code may be locally green while still violating the intended admin trust model"
+    ]
+  },
+  "blockingFindings": [
+    "design: duplicate-email row handling is not frozen tightly enough",
+    "design: seat-limit partial-failure semantics must be reopened in cc-plan"
+  ],
+  "reroute": "cc-plan",
+  "timestamp": "2026-04-16T12:15:00.000Z"
+}

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

@@ -0,0 +1,50 @@
+{
+  "version": 2,
+  "lastSyncedAt": "2026-04-19",
+  "backlogMeta": {
+    "roadmapVersion": "roadmap.v2",
+    "skillVersion": "4.3.2",
+    "currentFocusStage": "Stage 2"
+  },
+  "dependencyHandoff": {
+    "serialSpine": "RM-010",
+    "parallelReadyNextWave": "-",
+    "notesOnBlockers": "verification is blocked until the import contract covers limits, duplicates, billing, and audit consistency"
+  },
+  "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": ""
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,45 @@
+# BACKLOG
+
+## Backlog Meta
+
+- Roadmap version: `roadmap.v2`
+- Skill version: `4.3.2`
+- Last synced: `2026-04-19`
+- Current focus stage: `Stage 2`
+- Tracking source: `roadmap-tracking.json`
+
+## Queue
+
+| RM-ID | Title | Source Stage | Priority | Primary Capability | Secondary Capabilities | Capability Gap | Expected Spec Delta | Evidence | Depends On | Parallel With | Unknowns | Next Decision | Ready |
+|------|------|------|------|------|------|------|------|------|------|------|------|------|------|
+| RM-020 | Add an audit-log export summary download | Stage 2 | P1 | cap-audit-log-export | - | admins can export raw audit data but not a compact summary for review | codify local export summary truth | support escalations keep asking for a lightweight summary bundle | - | - | csv-only or csv-plus-markdown summary | resume from local handoff once remote access returns | Yes |
+
+## Dependency Handoff
+
+- Serial spine: RM-020
+- Parallel-ready next wave: -
+- Notes on blockers: export work stays local-only until the next maintainer has remote access
+
+## Ready For Req-Plan
+
+- RM-020:
+  - Primary Capability: `cap-audit-log-export`
+  - Secondary Capabilities: `-`
+  - Why now: the implementation and proof already exist, only the landing path is deferred
+  - Success signal: admins can download a concise audit summary without manual spreadsheet cleanup
+  - Entry constraints: stay local-only and avoid remote automation
+  - Capability gap: admins can export raw audit data but not a compact summary for review
+  - Expected spec delta: codify local export summary truth
+  - Open risks: handoff may age if schema changes before the next maintainer resumes
+  - First planning question: does the summary format need another review before remote landing?
+  - Required context to load: admin export screen, generated summary fixture, local handoff notes
+  - Depends On: `-`
+  - Parallel With: `-`
+  - Why this is ready now: the requirement is already proven and only needs a clean resume point
+
+## Parked
+
+- RM-XXX:
+  - Reason parked:
+  - Trigger to reopen:
+  - Missing evidence:

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

@@ -0,0 +1,56 @@
+# Local-Handoff Example
+
+## Example Meta
+
+- Example version: `1.0.0`
+- Last reviewed: `2026-04-17`
+- Bound skills: `cc-roadmap@4.3.2`, `cc-plan@3.5.4`, `cc-do@1.5.2`, `cc-check@1.8.2`, `cc-act@1.6.2`
+
+This example shows verified work that is **ready to move forward**, but `cc-act` still chooses `local-handoff`.
+
+That is not a failure.
+
+It simply means:
+
+- the requirement passed verification
+- a PR or remote push is intentionally not the next action
+- the workflow still must leave a clean handoff for the next maintainer
+
+## Scenario
+
+The fictional product now adds a downloadable audit-log export summary inside the admin console.
+
+The implementation is done and verified.
+
+But the current environment is local-only:
+
+- remote access is unavailable
+- the branch should not be pushed yet
+- another maintainer will pick it up later
+
+## What To Look For
+
+1. Why `cc-check` is `pass`
+2. Why `cc-act` still does not choose `create-pr`
+3. How `resume-index.md` becomes the only final handoff file
+
+## Artifact Map
+
+- `ROADMAP.md`
+- `roadmap-tracking.json` (shared roadmap/backlog truth)
+- `BACKLOG.md`
+- `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`
+- `changes/REQ-003-audit-log-export/review/report-card.json`
+- `changes/REQ-003-audit-log-export/handoff/resume-index.md`
+
+## Why There Is No `pr-brief.md`
+
+This sample intentionally chooses `local-handoff`.
+
+That mode needs:
+
+- `resume-index.md`
+
+It does **not** require a PR brief yet.

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

@@ -0,0 +1,45 @@
+# ROADMAP
+
+## Roadmap Meta
+
+- Roadmap version: `roadmap.v3`
+- Skill version: `4.3.2`
+- Status: `active`
+- Last updated: `2026-04-16`
+- Owner / decider: `product-owner`
+- Current focus stage: `Stage 2`
+- Confidence: `medium`
+- Supersedes roadmap version: `roadmap.v2`
+
+## Context Snapshot
+
+- Product / repo: `workspace-lite`
+- Project stage: collaboration and admin reporting are now both in use
+- Users: workspace admins reviewing activity and sharing reports internally
+- Pain: admins can inspect audit events, but cannot export a concise summary
+- Existing workaround: manually copy rows into an internal note
+- Strongest demand evidence: admins ask for a downloadable summary during weekly reviews
+- Why now: admin trust now depends on visibility and operational clarity
+- Distribution path: internal admin beta
+- Deadline / forcing function: internal ops review on `2026-04-25`
+- Team / capacity: one engineer
+- Hard constraints: keep export local to the current admin console
+- Adoption / trust bottleneck: admins want proof they can take activity history out of the UI cleanly
+- Known unknowns: whether CSV alone is enough or if JSON export will be needed later
+
+## Recommended Route
+
+- Recommendation: `wedge-first`
+- Why this route wins now: a simple downloadable summary removes the current reporting pain without broader analytics work
+- Why the rejected routes lose now: platform and rescue variants add scope before the current operator need is solved
+- First signal to watch: admins can finish weekly review without copying rows manually
+- Kill signal / stop condition: if export requires a shared reporting pipeline redesign
+
+## Implementation Tracking
+- Tracking source: `roadmap-tracking.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 -->

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/handoff/resume-index.md

@@ -0,0 +1,39 @@
+# Resume Index
+
+## Current Reality
+
+- Requirement: `REQ-003`
+- Roadmap item: `RM-020`
+- Verification state: `pass`
+- Ship mode: `local-handoff`
+- Current branch: `feature/audit-summary-export`
+- Blocking environment fact: remote push / PR creation is unavailable right now
+
+## What Is Already Done
+
+- design approved as `tiny-design`
+- implementation tasks `T001-T003` completed
+- targeted test and lint evidence collected
+- `report-card.json` confirms `pass`
+
+## Next Entry
+
+- when remote access is restored, rerun `detect-ship-target`
+- if the branch still has no PR, switch from `local-handoff` to `create-pr`
+- use `resume-index.md` and `report-card.json` as the truth sources for the next ship step
+
+## Read First
+
+- `design.md`
+- `tasks.md`
+- `task-manifest.json`
+- `report-card.json`
+
+## How To Re-Verify
+
+- `npm test -- src/admin/AuditSummaryPanel.test.tsx`
+- `npm run lint -- src/admin/AuditSummaryPanel.tsx`
+
+## Open Follow-Up
+
+- if operators ask for JSON or scheduled exports, lift that into a new roadmap item instead of reopening `REQ-003`