specrails-core 3.1.0 → 3.3.0

package/docs/local-tickets.md

@@ -0,0 +1,218 @@
+# Local Ticket Management
+
+specrails-core ships with a built-in, file-based ticket management system. It is the **default backlog provider** — no GitHub account, CLI tool, or external service required.
+
+---
+
+## Overview
+
+Tickets live in `.claude/local-tickets.json` at your project root. Because it's a plain JSON file, tickets are:
+
+- **Version-controlled** — tracked by git, diffable in PRs
+- **Offline-first** — no network calls, no rate limits
+- **Tool-agnostic** — readable by any script or editor
+
+The file is shared between specrails-core (which reads and writes tickets during command execution) and specrails-hub (which provides a visual ticket panel with real-time sync).
+
+---
+
+## Storage format
+
+`.claude/local-tickets.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "revision": 7,
+  "last_updated": "2026-03-23T10:00:00.000Z",
+  "next_id": 8,
+  "tickets": {
+    "1": {
+      "id": 1,
+      "title": "Add dark mode",
+      "description": "Support system-level dark mode preference via CSS variables.",
+      "status": "todo",
+      "priority": "medium",
+      "labels": ["area:frontend", "effort:medium"],
+      "assignee": null,
+      "prerequisites": [],
+      "metadata": {
+        "vpc_scores": { "persona-a": 4, "persona-b": 3 },
+        "effort_level": "Medium",
+        "user_story": "As a user working at night, I want dark mode...",
+        "area": "frontend"
+      },
+      "comments": [],
+      "created_at": "2026-03-20T09:00:00.000Z",
+      "updated_at": "2026-03-20T09:00:00.000Z",
+      "created_by": "sr-product-manager",
+      "source": "product-backlog"
+    }
+  }
+}
+```
+
+### Field reference
+
+**Root fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema_version` | string | Always `"1.0"` for the current format |
+| `revision` | number | Incremented on every write — used for optimistic concurrency control |
+| `last_updated` | ISO-8601 | Timestamp of the most recent mutation |
+| `next_id` | number | Auto-increment counter for new ticket IDs |
+| `tickets` | object | Map of ticket ID (as string) → ticket object |
+
+**Ticket fields**
+
+| Field | Type | Values | Description |
+|-------|------|--------|-------------|
+| `id` | number | Auto-assigned | Numeric ID, referenced as `#<id>` |
+| `title` | string | — | Short title |
+| `description` | string | Markdown | Full description |
+| `status` | string | `todo`, `in_progress`, `done`, `cancelled` | Current state |
+| `priority` | string | `critical`, `high`, `medium`, `low` | Priority level |
+| `labels` | string[] | Freeform | Tag strings; convention: `area:*`, `effort:*` |
+| `assignee` | string\|null | — | Agent name or user, if assigned |
+| `prerequisites` | number[] | — | IDs of tickets that must be done first |
+| `metadata` | object | — | VPC scores, effort level, user story, area (set by agents) |
+| `comments` | array | — | Progress notes appended during implementation |
+| `created_at` | ISO-8601 | — | Creation timestamp |
+| `updated_at` | ISO-8601 | — | Last mutation timestamp |
+| `created_by` | string | — | Agent name or `"user"` |
+| `source` | string | `manual`, `product-backlog`, `propose-spec` | How the ticket was created |
+
+---
+
+## Setup
+
+Local tickets become the default during `/setup`. The wizard prompts:
+
+```
+## Backlog Provider
+
+Use local ticket management or connect an external provider?
+
+1. Local tickets (default, recommended) — lightweight JSON-based ticket management.
+   No external tools or accounts required.
+2. External provider — connect GitHub Issues, JIRA, or disable backlog commands
+```
+
+Pressing **Enter** or selecting **1** initializes `.claude/local-tickets.json` with an empty ticket store and writes `.claude/backlog-config.json`:
+
+```json
+{
+  "provider": "local",
+  "write_access": true,
+  "git_auto": true
+}
+```
+
+To switch providers later, re-run the setup wizard:
+
+```bash
+npx specrails-core@latest init --root-dir .
+> /setup
+```
+
+---
+
+## Concurrency model
+
+Both CLI agents and specrails-hub can modify `local-tickets.json` simultaneously. The system uses two complementary mechanisms:
+
+### Advisory file lock
+
+Before every write, the agent creates `.claude/local-tickets.json.lock`:
+
+```json
+{
+  "agent": "sr-product-manager",
+  "timestamp": "2026-03-23T10:00:00.000Z"
+}
+```
+
+If the lock file already exists:
+- **Fresh lock** (< 30 seconds old): wait 500 ms and retry, up to 5 attempts
+- **Stale lock** (≥ 30 seconds old): treat as orphaned, delete it, proceed
+
+The lock is deleted immediately after the write completes. The window is minimal: read → modify in memory → write → release.
+
+### Revision counter
+
+Every write increments `revision`. Readers that want to detect external changes compare the `revision` they last saw against the current value. This is how specrails-hub avoids echoing its own writes back through the file watcher.
+
+---
+
+## Command integration
+
+### `/sr:implement`
+
+Pass local ticket IDs the same way you would GitHub issue numbers:
+
+```bash
+/sr:implement #1, #4, #7
+```
+
+The command reads each ticket from `local-tickets.json`, extracts metadata (area, effort, description), and tracks the ticket through the pipeline — updating status to `in_progress` on start and `done` on successful completion.
+
+### `/sr:product-backlog`
+
+```bash
+/sr:product-backlog              # all areas
+/sr:product-backlog UI, Backend  # filter by area
+```
+
+Reads all `todo` and `in_progress` tickets, scores them by VPC match, respects the `prerequisites` dependency graph, and recommends the top 3 for your next sprint.
+
+### `/sr:update-product-driven-backlog`
+
+```bash
+/sr:update-product-driven-backlog            # explore all areas
+/sr:update-product-driven-backlog Analytics  # focus on one area
+```
+
+Runs product discovery using your VPC personas. Creates new local tickets for discovered feature ideas, tagged with `source: "product-backlog"` and `labels: ["product-driven-backlog", "area:<area>"]`. Existing tickets are checked for duplicates before creating new ones.
+
+### `/sr:propose-spec`
+
+When a proposal is finalized, a local ticket is created automatically:
+
+```
+Created local ticket #12: Add analytics export
+```
+
+The ticket captures the full proposal as its description and is tagged `source: "propose-spec"` with the label `spec-proposal`.
+
+---
+
+## integration-contract.json
+
+The `ticketProvider` section tells specrails-hub where to find and how to use the ticket store:
+
+```json
+{
+  "ticketProvider": {
+    "type": "local",
+    "storageFile": "local-tickets.json",
+    "lockFile": "local-tickets.json.lock",
+    "capabilities": ["crud", "labels", "status", "priorities", "dependencies", "comments"]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `type` | `"local"` — file-based storage (the only supported type currently) |
+| `storageFile` | Filename relative to the project's specrails dir (`.claude/` or `.codex/`) |
+| `lockFile` | Advisory lock filename, same directory |
+| `capabilities` | Features the hub enables based on what the provider supports |
+
+specrails-hub reads this file when it loads a project. If the file is missing or the `ticketProvider` key is absent, hub falls back to safe defaults (`type: "local"`, `storageFile: "local-tickets.json"`).
+
+---
+
+## Migrating from GitHub Issues or JIRA
+
+See the [Migration Guide](./migration-guide.md).

package/docs/migration-guide.md

@@ -0,0 +1,141 @@
+# Migration Guide: Switching to Local Tickets
+
+This guide is for teams currently using GitHub Issues or JIRA as their specrails backlog provider who want to switch to the built-in local ticket system.
+
+Switching is optional. GitHub Issues and JIRA remain fully supported. Local tickets are the recommended default for new projects.
+
+---
+
+## Should you switch?
+
+**Switch to local tickets if:**
+- Your team prefers a simple, zero-dependency setup
+- You want tickets version-controlled alongside your code
+- You use specrails-hub and want the visual ticket panel
+- You don't need GitHub/JIRA for other workflows (project boards, external stakeholders)
+
+**Stay on GitHub Issues / JIRA if:**
+- Other teams or stakeholders manage tickets in those tools
+- You rely on GitHub Projects, Milestones, or JIRA sprints
+- You want PR auto-close on issue merge (requires GitHub Issues)
+
+---
+
+## Step 1: Switch the provider
+
+Edit `.claude/backlog-config.json` in your project root:
+
+```json
+{
+  "provider": "local",
+  "write_access": true,
+  "git_auto": true
+}
+```
+
+Then initialize the ticket store if it doesn't exist yet:
+
+```bash
+# Inside Claude Code or Codex
+/sr:implement --setup-local-tickets
+```
+
+Or create the file manually:
+
+```bash
+cat > .claude/local-tickets.json << 'EOF'
+{
+  "schema_version": "1.0",
+  "revision": 0,
+  "last_updated": null,
+  "next_id": 1,
+  "tickets": {}
+}
+EOF
+```
+
+---
+
+## Step 2: Import existing issues (one-time migration)
+
+### From GitHub Issues
+
+Use the `sr:migrate-from-github` command (requires `gh` CLI):
+
+```bash
+# Inside Claude Code
+/sr:migrate-from-github
+```
+
+This command:
+1. Fetches all open issues labeled `product-driven-backlog` (the label specrails uses)
+2. Maps GitHub issue fields to local ticket schema:
+   - `number` → `id` (uses next available local ID)
+   - `title` → `title`
+   - `body` → `description`
+   - `labels` → `labels`
+   - `state: open` → `status: todo`
+3. Writes each ticket to `local-tickets.json`
+4. Prints a summary: `Imported 14 tickets from GitHub Issues`
+
+To import all open issues regardless of label:
+
+```bash
+/sr:migrate-from-github --all
+```
+
+To do a dry run (preview without writing):
+
+```bash
+/sr:migrate-from-github --dry-run
+```
+
+**After import:** Your GitHub Issues are unchanged. The migration is additive — it only creates local tickets. You can continue using GitHub Issues in parallel until you're ready to stop.
+
+### From JIRA
+
+Use the `sr:migrate-from-jira` command (requires `jira` CLI or REST API credentials in `.claude/backlog-config.json`):
+
+```bash
+# Inside Claude Code
+/sr:migrate-from-jira
+```
+
+This command:
+1. Fetches all open issues from the configured JIRA project
+2. Maps JIRA fields to local ticket schema:
+   - Issue key (`PROJECT-123`) → stored in `metadata.jira_key`
+   - `summary` → `title`
+   - `description` → `description`
+   - `priority` → `priority` (Critical/High/Medium/Low mapped directly)
+   - `status: To Do / Backlog` → `status: todo`
+   - `status: In Progress` → `status: in_progress`
+   - `labels` → `labels`
+3. Writes each ticket to `local-tickets.json`
+
+The original JIRA key is preserved in `metadata.jira_key` so you can cross-reference during the transition.
+
+---
+
+## Step 3: Regenerate commands (optional but recommended)
+
+Command templates are generated at `/setup` time with provider-specific instructions baked in. After switching providers, regenerate them so commands use the local file operations instead of GitHub/JIRA CLI calls:
+
+```bash
+npx specrails-core@latest init --root-dir .
+> /setup --update
+```
+
+The `--update` flag regenerates only the backlog commands (`product-backlog`, `update-product-driven-backlog`, `implement`) without re-running the full stack analysis.
+
+---
+
+## Rollback
+
+To revert to GitHub Issues:
+
+1. Edit `.claude/backlog-config.json` and set `"provider": "github"`
+2. Re-run `/setup --update` to regenerate commands
+3. Your `local-tickets.json` is preserved — switch back any time
+
+Local tickets and external provider data are independent. Switching providers does not delete tickets from either system.

package/docs/user-docs/faq.md

@@ -14,17 +14,20 @@ It creates a `.claude/` directory with agent templates, commands, and configurat
 
 Yes. Node 18+ is required to run `npx specrails-core@latest`. Once installed, SpecRails works with any language or framework — the agents adapt to whatever stack your project uses.
 
-**Can I run SpecRails on a project that doesn't have GitHub Issues?**
+**Do I need GitHub Issues?**
 
-Yes. During `/setup`, you can choose "none" as your backlog provider. Commands like `/sr:implement` will accept plain text descriptions instead of issue numbers:
+No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/sr:implement` accept ticket IDs or plain text:
 
 ```
+/sr:implement #1, #4
 /sr:implement "add rate limiting to the API"
 ```
 
+You can switch to GitHub Issues or JIRA during `/setup` (Phase 3) if you prefer.
+
 **How long does /setup take?**
 
-About 5 minutes. Most of the time is spent on Phase 2 (persona generation), which does web research on your domain.
+The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/setup --lite`: three questions, under a minute, no web research.
 
 ---
 

package/docs/user-docs/installation.md

@@ -95,7 +95,7 @@ codex     # Codex
 /setup
 ```
 
-The wizard runs 5 phases:
+By default, `/setup` runs the full 5-phase wizard:
 
 | Phase | What happens |
 |-------|-------------|
@@ -105,6 +105,8 @@ The wizard runs 5 phases:
 | **4. Generate** | Fills all templates with your project-specific context |
 | **5. Cleanup** | Removes setup files, leaving only your tailored workflow |
 
+**In a hurry?** Run `/setup --lite` instead — three questions, sensible defaults, done in under a minute.
+
 After setup, `.claude/` contains fully configured agents and commands ready to use. The `/setup` command removes itself — it only runs once.
 
 ## Verify

package/docs/user-docs/quick-start.md

@@ -46,7 +46,7 @@ Then run:
 /setup
 ```
 
-The wizard runs automatically and takes about 5 minutes. It analyzes your codebase and configures SpecRails for your specific project:
+The wizard runs the full 5-phase setup (about 5 minutes). It analyzes your codebase and configures SpecRails for your specific project:
 
 ```
 Phase 1/5  Analyzing codebase...
@@ -59,14 +59,14 @@ Phase 2/5  Generating user personas...
            → Created 3 VPC profiles
 
 Phase 3/5  Configuration...
-           → Backlog provider: GitHub Issues
+           → Backlog provider: local
            → Git workflow: trunk-based
 
 Phase 4/5  Generating files...
            → sr-architect.md (adapted to your stack)
            → sr-developer.md (knows your CI commands)
            → sr-reviewer.md (runs your specific checks)
-           → 9 more agents
+           → 11 more agents
 
 Phase 5/5  Cleanup complete. /setup removed.
 
@@ -75,6 +75,8 @@ Phase 5/5  Cleanup complete. /setup removed.
 
 After setup, the `/setup` command is gone — it's a one-time wizard.
 
+**In a hurry?** Use `/setup --lite` for a 3-question quick setup (under a minute). You can always run the full wizard later.
+
 ## Step 3: Implement your first feature
 
 Pick something small. Either reference a GitHub Issue or describe it in plain text:
@@ -129,7 +131,7 @@ One command. The PR is ready for human review.
 /sr:product-backlog
 ```
 
-See your GitHub Issues ranked by persona fit and effort. The top 3 are safe to implement next.
+See your tickets ranked by persona fit and effort. The top 3 are safe to implement next. Uses local tickets by default.
 
 **Generate new feature ideas:**
 
@@ -137,7 +139,7 @@ See your GitHub Issues ranked by persona fit and effort. The top 3 are safe to i
 /sr:update-product-driven-backlog
 ```
 
-The Product Manager researches your competitive landscape and creates well-formed GitHub Issues for new features.
+The Product Manager researches your competitive landscape and creates new tickets (local by default, or GitHub Issues if configured).
 
 **Run multiple features in parallel:**
 

package/docs/workflows.md

@@ -126,7 +126,7 @@ View your prioritized product backlog, ranked by VPC fit and effort.
 
 ### What it shows
 
-The Product Analyst reads your GitHub Issues (labeled `product-driven-backlog`) and produces:
+The Product Analyst reads your backlog (local tickets in `.claude/local-tickets.json` by default, or GitHub Issues labeled `product-driven-backlog` if configured) and produces:
 
 - **Backlog table** per area — sorted by Total Persona Score
 - **Top 3 recommendations** — ranked by VPC score / effort ratio, filtered to Wave 1 of the safe implementation order
@@ -166,7 +166,7 @@ Generate new feature ideas through product discovery. The Product Manager (Opus)
 2. Researches competitors via web search
 3. Generates 2–4 feature ideas per area
 4. Scores each against every persona (0–5)
-5. Creates GitHub Issues (if write access) or displays for manual creation
+5. Creates tickets in your active backlog provider (local tickets by default; GitHub Issues or JIRA if configured) or displays for manual creation
 
 ---
 

package/integration-contract.json

@@ -35,5 +35,11 @@
     "refactor-recommender",
     "health-check",
     "compat-check"
-  ]
+  ],
+  "ticketProvider": {
+    "type": "local",
+    "storageFile": "local-tickets.json",
+    "lockFile": "local-tickets.json.lock",
+    "capabilities": ["crud", "labels", "status", "priorities", "dependencies", "comments"]
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"

package/templates/commands/sr/implement.md

@@ -24,12 +24,22 @@ Check the environment variable `CLAUDE_CODE_ENTRYPOINT`. If it contains `remote_
 
 ### Checks to run (sequential, fail-fast)
 
-#### 1. GitHub CLI authentication
+#### 1. Backlog provider availability
 
+Read `.claude/backlog-config.json` and extract `BACKLOG_PROVIDER`.
+
+**If `BACKLOG_PROVIDER=local`:**
 ```bash
-gh auth status 2>&1
+[[ -f "$SPECRAILS_DIR/local-tickets.json" ]] && echo "Local tickets storage: OK" || echo "WARNING: local-tickets.json not found"
 ```
+- Set `LOCAL_TICKETS_AVAILABLE=true/false` based on file existence.
+- Set `GH_AVAILABLE=false` (GitHub CLI not needed for local provider).
+- Set `BACKLOG_AVAILABLE=true` if local-tickets.json exists.
 
+**Otherwise:**
+```bash
+gh auth status 2>&1
+```
 - Set `GH_AVAILABLE=true/false` for later phases.
 
 #### 2. OpenSpec CLI
@@ -107,7 +117,7 @@ Initialize conflict-tracking variables:
 - Set `SINGLE_MODE = true`. No worktrees, no parallelism.
 - **Skip Phase 1 and Phase 2** — go directly to Phase 3a.
 
-**If the user passed issue/ticket references** (e.g. `#85, #71` for GitHub or `PROJ-85, PROJ-71` for JIRA):
+**If the user passed issue/ticket references** (e.g. `#85, #71` for GitHub, `#1, #2` for local tickets, or `PROJ-85, PROJ-71` for JIRA):
 - Fetch each issue/ticket:
   ```bash
   {{BACKLOG_VIEW_CMD}}
@@ -120,7 +130,44 @@ Initialize conflict-tracking variables:
 
 After fetching issue refs, capture a baseline snapshot for conflict detection.
 
-**If `GH_AVAILABLE=true` and the input mode was issue numbers:**
+##### If `BACKLOG_PROVIDER=local` and input mode was issue numbers:
+
+For each resolved ticket ID, read `$SPECRAILS_DIR/local-tickets.json` and extract the ticket object at `tickets["{id}"]`.
+
+Build a snapshot object for each ticket:
+- `number`: ticket `id` (integer)
+- `title`: ticket `title` string
+- `state`: map ticket `status` — `"done"` or `"cancelled"` → `"closed"`, otherwise → `"open"`
+- `assignees`: `[ticket.assignee]` if non-null, else `[]`
+- `labels`: ticket `labels` array, sorted alphabetically
+- `body_sha`: SHA-256 of the ticket `description` string — compute with:
+  ```bash
+  echo -n "{description}" | sha256sum | cut -d' ' -f1
+  ```
+  If `sha256sum` is not available, fall back to `openssl dgst -sha256 -r` or `shasum -a 256`.
+- `updated_at`: ticket `updated_at` value
+- `captured_at`: current local time in ISO 8601 format
+
+Write the following JSON to `.claude/backlog-cache.json` (overwrite fully — this establishes a fresh baseline for this run):
+
+```json
+{
+  "schema_version": "1",
+  "provider": "local",
+  "last_updated": "<ISO 8601 timestamp>",
+  "written_by": "implement",
+  "issues": {
+    "<id>": { <snapshot object> },
+    ...
+  }
+}
+```
+
+If the write succeeds: set `SNAPSHOTS_CAPTURED=true`.
+
+If the write fails: print `[backlog-cache] Warning: could not write cache. Conflict detection disabled for this run.` and set `SNAPSHOTS_CAPTURED=false`. Do NOT abort the pipeline.
+
+##### If `GH_AVAILABLE=true` and input mode was issue numbers (GitHub/JIRA):
 
 For each resolved issue number, run:
 
@@ -161,9 +208,9 @@ If the write succeeds: set `SNAPSHOTS_CAPTURED=true`.
 
 If the write fails (e.g., `.claude/` directory does not exist): print `[backlog-cache] Warning: could not write cache. Conflict detection disabled for this run.` and set `SNAPSHOTS_CAPTURED=false`. Do NOT abort the pipeline.
 
-**If `GH_AVAILABLE=false` or input was not issue numbers:**
+##### Otherwise (no backlog available or non-issue input):
 
-Set `SNAPSHOTS_CAPTURED=false`. Print: `[conflict-check] Snapshot skipped — GH unavailable or non-issue input.`
+Set `SNAPSHOTS_CAPTURED=false`. Print: `[conflict-check] Snapshot skipped — backlog unavailable or non-issue input.`
 
 #### Gitignore advisory
 
@@ -267,7 +314,9 @@ Pick the single idea with the best impact/effort ratio from each exploration. Pr
 
 Otherwise, re-fetch each issue in scope and diff against the Phase 0 snapshot:
 
-For each issue number in `ISSUE_REFS`:
+**If `BACKLOG_PROVIDER=local`:** For each ticket ID in `ISSUE_REFS`, read `$SPECRAILS_DIR/local-tickets.json` and extract the ticket at `tickets["{id}"]`. If the ticket does not exist (deleted): treat as a CRITICAL conflict — field `"state"`, was `<cached state>`, now `"deleted"`. Otherwise, reconstruct a current snapshot using the same mapping as the Phase 0 local snapshot.
+
+**If `BACKLOG_PROVIDER=github`:** For each issue number in `ISSUE_REFS`:
 
 ```bash
 gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt
@@ -275,7 +324,7 @@ gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt
 
 If the `gh` command returns non-zero (issue deleted or inaccessible): treat as a CRITICAL conflict — field `"state"`, was `<cached state>`, now `"deleted"`.
 
-Otherwise, reconstruct a current snapshot (same shape as Phase 0: sort `assignees` and `labels`, compute `body_sha`).
+In both cases, reconstruct a current snapshot (same shape as Phase 0: sort `assignees` and `labels`, compute `body_sha`).
 
 **Short-circuit:** If `current.updatedAt == cached.updated_at`, mark the issue as clean and skip field comparison.
 
@@ -848,6 +897,9 @@ This check is independent of Phase 3a.0. Even if the user chose to continue thro
 
 Re-fetch each issue in `ISSUE_REFS` and diff against `.claude/backlog-cache.json` using the same algorithm as Phase 3a.0:
 
+**If `BACKLOG_PROVIDER=local`:** Read `$SPECRAILS_DIR/local-tickets.json` and extract each ticket by ID.
+
+**If `BACKLOG_PROVIDER=github`:**
 ```bash
 gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt
 ```
@@ -881,8 +933,12 @@ Record skipped operations to `.cache-manifest.json` under `skipped_operations`:
 - `"git: commit"`
 - `"git: push"`
 - `"github: pr creation"` (if `GH_AVAILABLE=true`)
-- `"github: issue comment #N"` for each issue in scope (if `BACKLOG_WRITE=true`)
-- `"github: issue close #N (via PR merge)"` for each fully resolved issue (if `BACKLOG_WRITE=true`)
+- If `BACKLOG_PROVIDER=local` and `BACKLOG_WRITE=true`:
+  - `"local: ticket comment #{id}"` for each ticket in scope
+  - `"local: ticket status update #{id}"` for each fully resolved ticket
+- If `BACKLOG_PROVIDER=github` and `BACKLOG_WRITE=true`:
+  - `"github: issue comment #N"` for each issue in scope
+  - `"github: issue close #N (via PR merge)"` for each fully resolved issue
 
 Then skip the rest of Phase 4c and proceed directly to Phase 4e.
 
@@ -934,17 +990,19 @@ All implementation is complete and CI checks pass.
 #### Backlog updates (both modes)
 
 **If `BACKLOG_WRITE=true`:**
-- For fully resolved issues/tickets: add a comment noting completion and reference the PR. Do NOT close the issue explicitly — use `Closes #N` in the PR body so GitHub/JIRA closes it automatically when the PR is merged:
+- For fully resolved issues/tickets: add a comment noting completion and reference the PR:
   ```bash
   {{BACKLOG_COMMENT_CMD}}
   ```
-  - GitHub: `gh issue comment {number} --body "Implemented in PR #XX. All acceptance criteria met."`
-  - JIRA: `jira issue comment {key} --message "Implemented in PR #XX. All acceptance criteria met."`
-  - Ensure the PR body includes `Closes #N` for each fully resolved issue (GitHub auto-closes on merge)
+  - **Local:** Update the ticket status to `"done"` using `{{BACKLOG_UPDATE_CMD}}` and add a comment: `"Implemented in PR #XX. All acceptance criteria met."` via `{{BACKLOG_COMMENT_CMD}}`. Local tickets are closed directly — there is no auto-close-on-merge mechanism.
+  - **GitHub:** `gh issue comment {number} --body "Implemented in PR #XX. All acceptance criteria met."` — do NOT close the issue explicitly. Use `Closes #N` in the PR body so GitHub auto-closes on merge.
+  - **JIRA:** `jira issue comment {key} --message "Implemented in PR #XX. All acceptance criteria met."`
+  - For GitHub/JIRA: ensure the PR body includes `Closes #N` for each fully resolved issue (auto-closes on merge)
 - For partially resolved issues/tickets: add a comment noting progress:
   ```bash
   {{BACKLOG_PARTIAL_COMMENT_CMD}}
   ```
+  - **Local:** Additionally update the ticket status to `"in_progress"` via `{{BACKLOG_UPDATE_CMD}}` if it is still `"todo"`.
 
 **If `BACKLOG_WRITE=false`:**
 - Do NOT create, modify, or comment on any issues/tickets.