openspecpm 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-05-18
+
+### Security hardening — pass through audit findings
+
+Eleven commits addressing every HIGH / MEDIUM / LOW-with-security-impact finding from the v1.0.0 quality audit. 113/113 tests; +14 new regression tests across the touched surfaces.
+
+**HIGH severity:**
+
+- **`cli/src/http.js`** — every adapter HTTP request now bounded by `AbortSignal.timeout(timeoutMs)` (default 30s). A hung Jira / ADO / Linear / GitLab endpoint no longer wedges `sync --all` indefinitely. New test confirms the request rejects within budget, not at wall-clock max.
+- **`cli/src/adapters/azure.js`** + **`cli/src/adapters/gitlab.js`** — user-controlled `item.id` / `child.id` / `parent.id` (from `tasks.md` frontmatter, user-editable) now wrapped in `encodeURIComponent` before URL-path interpolation. Closes a path-injection vector — a typo'd `external_id: "1/../99"` no longer reaches unintended endpoints. Jira was already correct.
+- **`cli/src/tracking.js`** — `loadChange` now validates that `tasks.md` frontmatter `items:` is an array of well-shaped objects (each with a string `title`). Malformed entries are silently dropped; non-array `items:` raises a clear error with a remediation pointing at the file to repair. Malformed YAML itself raises with file context instead of crashing deep with `TypeError: items is not iterable`.
+- **`cli/src/openspec-bridge.js`** — new `assertSafeFeatureName()` rejects empty / non-string input, anything containing `..` / `/` / `\` / Windows drive letters, and anything outside `/^[a-z0-9][a-z0-9._-]*$/i`. Called at the top of `changeDir()`, `changeExists()`, and `propose()` so every entry point into the OpenSpec layout validates first. Closes path-traversal via feature name.
+- **`cli/src/commands/sync.js`** + **`cli/src/commands/bulk.js`** — `sync`, `sync --all`, and `ship --all-ready` now throw at the end if any task or change failed, instead of swallowing per-task errors and returning 0. `openspecpm sync feature && deploy` in CI no longer proceeds on silent partial sync. Per-task `last_error` still persisted to `tasks.md` frontmatter for inspection.
+- **`cli/src/notify.js`** — `fetch` response status is now checked instead of being discarded. A 401 / 403 / 500 from Slack / Teams / generic counts as an error, not a successful send. `standup --broadcast` no longer claims success when the webhook silently rejected.
+
+**MEDIUM severity:**
+
+- **`cli/tests/github-adapter.test.js`** — locked the leading-dash title behavior under array argv (M3). No code change needed; execa array-args + cobra's flag parser already handle `--title "--evil-flag"` correctly, but the regression test prevents a future refactor from breaking it.
+- **`cli/src/audit.js`** — `SECRET_SEGMENTS` extended to include `bearer`, `cookie`, `session`, `webhook`, `signature`, `assertion`. New `scrubValue()` redacts webhook URLs from any string value (Slack hooks, MS Teams connectors, M365 webhooks). `record()`'s `result` and `error` fields now also go through `scrubValue`. **`cli/src/notify.js`** sanitizes its `target.url` from every error message at the source. Two-layer defense: the URL can't leak from notify's error path, and even if some other code path puts a webhook URL in an audit entry, the sink redacts it. (M6 + M11 + LOW-4)
+- **`cli/bin/openspecpm.js`** — installed `uncaughtException` and `unhandledRejection` handlers that print sanitized message + remediation + a pointer to `audit.log`. A future programming bug (TypeError, etc.) no longer dumps Node's default stack trace with absolute install / tmp paths to stderr. (M8)
+- **`cli/src/commands/sync.js`** — `extractSummary` now strips C0/C1 control chars (except TAB/LF/CR), DEL, zero-width / joiner chars, bidi overrides (LRE/RLE/PDF/LRO/RLO), and isolates (LRI/RLI/FSI/PDI) before sending the proposal body to the remote tracker as the epic description. Closes homograph / hidden-content vector in issue titles and bodies. (M9)
+
+**LOW severity (defense-in-depth):**
+
+- **`cli/src/adapters/azure.js`** — `listWorkItems` now allowlist-validates the WIQL `tag` against `/^[a-zA-Z0-9._:-]+$/`. Single-quote doubling escape already handled the only known WIQL string-literal breakout, but allowlist validation is more robust than escape-based protection. (LOW-1)
+
+### Post-1.0 doc sweep
+
+- **README.md:** lede tagline + flow Mermaid + "differences from CCPM" section now reference all five PM backends (GitHub, Azure DevOps, Jira, **Linear, GitLab**) instead of the original three. The "three differences" framing bumped to five — added bullets for audit-log-by-default and cross-feature task graphs, with the LLM judge folded into the BDD-authoring bullet.
+- **README cross-cutting line:** added optional Slack / Teams / generic-webhook broadcasts on `standup --broadcast`.
+- **README Roadmap:** marked `bdd-llm-reviewer` as shipped (no longer in the active 6); count adjusted to 5 remaining.
+- **README Project structure:** rewritten to reflect actual `cli/src/` contents (20 commands, 5 adapters under `cli/src/adapters/`, `audit.js` / `notify.js` / `telemetry.js` / `install-hints.js` / `bdd/judge.js`), workflow set (`test.yml` + `auto-approve.yml` + `release.yml` + `publish.yml`), `docs/screenshots/`, and `openspec/changes/` v2 roadmap directory.
+- **SKILL.md:** "three differences" → "five differences"; "(Sprint 3+)" / "(Sprint 3)" markers stripped from the workflow header and the phase table.
+- **SECURITY.md:** out-of-scope vendor list extended with Linear + GitLab (the in-scope secrets list already had them).
+- **`skill/openspecpm/references/{conventions,sync,execute,plan}.md`:** "(Sprint N)" / "(Sprint N+)" annotations stripped throughout — those markers were pre-1.0 development history noise, no longer meaningful.
+- **`openspec/changes/README.md`:** added a "Shipped" section calling out `bdd-llm-reviewer` (v1.0.0); active roadmap table reduced from 6 to 5 changes; totals recomputed (47 tasks, ~178 hrs).
+- **`openspec/changes/bdd-llm-reviewer/proposal.md`:** frontmatter `status: draft` → `status: shipped` with `shipped_in: 1.0.0` and `shipped_at: 2026-05-18`.
+- **`cli/bin/openspecpm.js`:** `program.version()` now reads from `package.json` at runtime instead of the hardcoded `'0.1.0-alpha.0'`. Future `npm version` bumps keep `openspecpm --version` in sync automatically.
+
 ## [1.0.0] - 2026-05-18
 
 ### Fix — release.yml must use a user-owned PAT, not GITHUB_TOKEN

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Faks-builds%2F03ce34dc5c6486c004dd8cf4c27ea87c%2Fraw%2Ftests.json)](cli/tests)
 
-> Spec-driven, BDD-shaped project management for AI agents — author once in [OpenSpec](https://github.com/Fission-AI/OpenSpec), sync to GitHub Issues, Azure DevOps Boards, or Jira.
+> Spec-driven, BDD-shaped project management for AI agents — author once in [OpenSpec](https://github.com/Fission-AI/OpenSpec), sync to GitHub Issues, Azure DevOps Boards, Jira, Linear, or GitLab.
 
 OpenSpecPM turns natural-language intent ("plan X", "sync the X epic", "what's blocked", "ship X") into a disciplined flow:
 
@@ -14,7 +14,7 @@ flowchart LR
     Proposal["📝 **proposal.md**<br/>(OpenSpec)"]
     BDD["📋 **BDD specs**<br/>Given / When / Then"]
     Tasks["✅ **tasks**"]
-    Tracked["🎯 **Tracked work items**<br/>GitHub · ADO · Jira"]
+    Tracked["🎯 **Tracked work items**<br/>GitHub · ADO · Jira · Linear · GitLab"]
     Shipped["🚀 **Shipped code**"]
 
     Idea --> Proposal --> BDD --> Tasks --> Tracked --> Shipped
@@ -30,127 +30,13 @@ flowchart LR
     class Shipped doneC
 ```
 
-It is a sibling of [CCPM](https://github.com/automazeio/ccpm), with three differences:
+It is a sibling of [CCPM](https://github.com/automazeio/ccpm), with five differences:
 
-1. **OpenSpec drives spec authoring** — every feature gets `proposal.md`, `design.md`, `tasks.md`, and a `specs/` folder of BDD scenarios.
-2. **The PM tool is pluggable** — an interactive wizard at `init` time picks GitHub Issues/Projects, Azure DevOps Boards, or Jira.
-3. **Built for non-engineers too** — PMs/BAs/PgMs can drive the flow. A `doctor` command owns auth-setup pain. Worktrees are hidden by default.
-
-## Install
-
-```bash
-# Standalone CLI (any harness)
-npx openspecpm@latest init
-
-# Claude Code Agent Skill
-# Copy skill/openspecpm/ into your Claude Code skills directory.
-# SKILL.md handles routing — just talk to Claude.
-```
-
-OpenSpecPM shells out to [OpenSpec](https://github.com/Fission-AI/OpenSpec); install it first:
-
-```bash
-npm install -g @fission-ai/openspec
-```
-
-## In action
-
-> A walkthrough of OpenSpecPM running against two sample features (`dark-mode`, `auth-rate-limit`). Source images live in [`docs/screenshots/`](docs/screenshots/); regenerate with `pwsh docs/screenshots/render.ps1` after CLI output changes — the renderer sets up its own sample data and cleans up after itself.
-
-**1 · Phase-grouped command reference** — `help-table` shows every command grouped by workflow phase (Setup → Plan → Sync → Track → Execute/Ship):
-
-![openspecpm help-table](docs/screenshots/help-table.png)
-
-**2 · Health check across every adapter** — `doctor` diagnoses auth + tooling for all five backends (GitHub, Azure DevOps, Jira, Linear, GitLab) with an English remediation hint on every failure. The `[judge]` section reports `ANTHROPIC_API_KEY` for the optional LLM BDD judge:
-
-![openspecpm doctor](docs/screenshots/doctor.png)
-
-**3 · Author a proposal** — `propose --offline` scaffolds `proposal.md`, `tasks.md`, and `specs/main.md` from templates without calling the OpenSpec CLI. Soft BDD lint runs immediately so placeholder Then-clauses are flagged before you keep editing:
-
-![openspecpm propose](docs/screenshots/propose.png)
-
-**4 · Optional LLM BDD judge** — pass `--llm` (or set `judge.enabled: true` in `.openspecpm/config.json`) to augment the heuristic linter with Claude Haiku 4.5. The judge catches what regex can't: cross-spec contradictions (`bdd/llm-contradiction`), success criteria with no scenario (`bdd/llm-missing-coverage`), and Then-clauses that pass the verb check but state no observable outcome (`bdd/llm-vague-then`). Findings merge into the same lint stream and respect `--force` the same way. Prompt-cached on the proposal so re-runs across multiple specs stay cheap. *Sample output below — real findings vary per scenario set; the judge can't be regenerated by `render.ps1` because it requires a live `ANTHROPIC_API_KEY`:*
-
-![openspecpm propose --llm](docs/screenshots/judge.png)
-
-**5 · Decompose into tasks** — `decompose` walks proposal headings, GitHub-style checklists, a `Tasks` section, and BDD scenarios under `specs/` and writes a structured `tasks.md` with `sync_state` frontmatter:
-
-![openspecpm decompose](docs/screenshots/decompose.png)
-
-**6 · Multi-feature status** — `status` shows the configured adapter and per-change task counts (`synced / pending / failed / done`) at a glance:
-
-![openspecpm status](docs/screenshots/status.png)
-
-**7 · "What can I work on right now?"** — `next` lists tasks with no unmet dependencies, marking parallel-safe ones so multiple agents can pick them up:
-
-![openspecpm next](docs/screenshots/next.png)
-
-**8 · "What's waiting on what?"** — `blocked` lists every task held up by a dependency and names the blocker, so the path to unblocking is one read away:
-
-![openspecpm blocked](docs/screenshots/blocked.png)
-
-**9 · Parallel-agent dispatch** — `fan-out` emits ready-to-paste prompts for `parallel: true` tasks with no unmet deps. Each prompt embeds the proposal summary, design notes, and BDD spec as acceptance criteria so subagents can work in isolation:
-
-![openspecpm fan-out](docs/screenshots/fan-out.png)
-
-**10 · Cross-file search** — `search` is a case-insensitive grep across every proposal, spec, tasks file, and progress note. Useful for tracing back from a keyword to the change that owns it:
-
-![openspecpm search](docs/screenshots/search.png)
-
-**11 · Project-wide validation** — `validate` runs the schema check and BDD linter across every change and reports per-feature error + warning counts:
-
-![openspecpm validate](docs/screenshots/validate.png)
-
-## Quick start
-
-```bash
-# 1. One-time setup. The wizard asks which PM tool your team uses.
-npx openspecpm init
-
-# 2. Verify auth before doing anything remote.
-npx openspecpm doctor
-
-# 3. Author a proposal. OpenSpec generates proposal.md, design.md, tasks.md,
-#    and BDD scenarios in specs/. Soft BDD-lint runs after authoring.
-npx openspecpm propose dark-mode --prompt "Per-user dark theme with persistence."
-
-# 4. Review the generated files. Refine BDD scenarios until lint is clean.
-
-# 5. Sync to the PM tool. Hard BDD lint runs first; pass --force to override.
-npx openspecpm sync dark-mode
-
-# 6. Pick up where you left off.
-npx openspecpm next        # tasks ready to start
-npx openspecpm blocked     # tasks waiting on dependencies
-npx openspecpm standup     # progress updates in the last 24h
-
-# 7. When the feature is verified, close + archive.
-npx openspecpm ship dark-mode
-```
-
-## Command reference
-
-| Command | What it does |
-|---|---|
-| `init` | Interactive wizard. Picks the PM tool. Writes `.openspecpm/config.json`. |
-| `doctor [adapter]` | Auth/tooling health check. English remediation hints on every failure. |
-| `propose <feature> [--llm]` | Shell out to OpenSpec; create `openspec/changes/<feature>/`. Soft-lint BDD scenarios; `--llm` adds the LLM judge. |
-| `decompose <feature>` | Extract tasks from proposal headings/checklists + BDD scenarios into `tasks.md`. |
-| `sync <feature> [--llm]` | Hard-lint BDD, then create/update work items in the PM tool. Idempotent; `--llm` adds the LLM judge as a hard gate. |
-| `comment <feature> <task>` | Broadcast local `progress.md` (or `-m`) to the PM tool with `<!-- SYNCED -->` marker. |
-| `reconcile <feature>` | Pull remote work-item state into local frontmatter. Detects out-of-band closes. |
-| `bug-report <feature> <task> --title "…"` | File a linked regression against a shipped task. |
-| `status` | Per-change task counts: pending / created / failed / done. |
-| `standup [--since 24h]` | Recent `progress.md` updates, newest first. |
-| `next [-l 5]` | Tasks with no unmet dependencies. |
-| `blocked` | Tasks waiting on unmet dependencies (with reasons). |
-| `validate [--llm]` | Schema + dependency + BDD-lint sweep across every change; `--llm` adds the LLM judge per change. |
-| `search <query>` | Grep across proposals, specs, tasks, progress notes. |
-| `fan-out <feature>` | Emit ready-to-paste agent prompts for `parallel: true` tasks. |
-| `ship <feature> [-y]` | Close all task work items + close the epic + archive the OpenSpec change. |
-| `help-table [topic]` | Context-aware command reference grouped by workflow phase. |
-
-Every command appends a JSONL entry (secrets scrubbed) to `.openspecpm/audit.log`.
+1. **OpenSpec drives spec authoring + BDD scenarios become enforceable.** Every feature gets `proposal.md`, `design.md`, `tasks.md`, and a `specs/` folder of Given/When/Then scenarios. A heuristic linter blocks vague Thens at `sync` time. An optional [LLM judge](#architecture-highlights) (Claude Haiku 4.5, opt-in via `--llm`) catches cross-spec contradictions and missing-coverage gaps the regex linter can't see.
+2. **Five pluggable PM backends** — an interactive wizard at `init` time picks GitHub Issues/Projects, Azure DevOps Boards, Jira, Linear, or GitLab. New backends register without forking via `registerAdapter()`.
+3. **Built for non-engineers too** — PMs/BAs/PgMs can drive the flow. A `doctor` command owns auth-setup pain (with `--install` and `--setup-auth` flags for OS-specific install hints and PAT-creation URLs). Worktrees are hidden by default.
+4. **Audit-logged by default.** Every command appends a JSONL entry (secrets scrubbed) to `.openspecpm/audit.log`. Useful for regulated industries that need a paper trail; useful for the rest of us when something looks weird.
+5. **Cross-feature task graphs.** `depends_on:` can reach across changes (`<feature>/<task-title>` or `<feature>/<external-id>`), so `next` and `blocked` reflect the whole project rather than one feature in isolation.
 
 ## Architecture
 
@@ -314,7 +200,123 @@ flowchart LR
     class Shipped doneC
 ```
 
-> Cross-cutting on every command: audit log (`.openspecpm/audit.log`, secrets scrubbed) · token-bucket rate-limiting per adapter · OpenSpec version probe · optional opt-in telemetry.
+> Cross-cutting on every command: audit log (`.openspecpm/audit.log`, secrets scrubbed) · token-bucket rate-limiting per adapter · OpenSpec version probe · optional opt-in telemetry · optional Slack / Teams / generic-webhook broadcasts on `standup --broadcast`.
+
+## Install
+
+```bash
+# Standalone CLI (any harness)
+npx openspecpm@latest init
+
+# Claude Code Agent Skill
+# Copy skill/openspecpm/ into your Claude Code skills directory.
+# SKILL.md handles routing — just talk to Claude.
+```
+
+OpenSpecPM shells out to [OpenSpec](https://github.com/Fission-AI/OpenSpec); install it first:
+
+```bash
+npm install -g @fission-ai/openspec
+```
+
+## In action
+
+> A walkthrough of OpenSpecPM running against two sample features (`dark-mode`, `auth-rate-limit`). Source images live in [`docs/screenshots/`](docs/screenshots/); regenerate with `pwsh docs/screenshots/render.ps1` after CLI output changes — the renderer sets up its own sample data and cleans up after itself.
+
+**1 · Phase-grouped command reference** — `help-table` shows every command grouped by workflow phase (Setup → Plan → Sync → Track → Execute/Ship):
+
+![openspecpm help-table](docs/screenshots/help-table.png)
+
+**2 · Health check across every adapter** — `doctor` diagnoses auth + tooling for all five backends (GitHub, Azure DevOps, Jira, Linear, GitLab) with an English remediation hint on every failure. The `[judge]` section reports `ANTHROPIC_API_KEY` for the optional LLM BDD judge:
+
+![openspecpm doctor](docs/screenshots/doctor.png)
+
+**3 · Author a proposal** — `propose --offline` scaffolds `proposal.md`, `tasks.md`, and `specs/main.md` from templates without calling the OpenSpec CLI. Soft BDD lint runs immediately so placeholder Then-clauses are flagged before you keep editing:
+
+![openspecpm propose](docs/screenshots/propose.png)
+
+**4 · Optional LLM BDD judge** — pass `--llm` (or set `judge.enabled: true` in `.openspecpm/config.json`) to augment the heuristic linter with Claude Haiku 4.5. The judge catches what regex can't: cross-spec contradictions (`bdd/llm-contradiction`), success criteria with no scenario (`bdd/llm-missing-coverage`), and Then-clauses that pass the verb check but state no observable outcome (`bdd/llm-vague-then`). Findings merge into the same lint stream and respect `--force` the same way. Prompt-cached on the proposal so re-runs across multiple specs stay cheap. *Sample output below — real findings vary per scenario set; the judge can't be regenerated by `render.ps1` because it requires a live `ANTHROPIC_API_KEY`:*
+
+![openspecpm propose --llm](docs/screenshots/judge.png)
+
+**5 · Decompose into tasks** — `decompose` walks proposal headings, GitHub-style checklists, a `Tasks` section, and BDD scenarios under `specs/` and writes a structured `tasks.md` with `sync_state` frontmatter:
+
+![openspecpm decompose](docs/screenshots/decompose.png)
+
+**6 · Multi-feature status** — `status` shows the configured adapter and per-change task counts (`synced / pending / failed / done`) at a glance:
+
+![openspecpm status](docs/screenshots/status.png)
+
+**7 · "What can I work on right now?"** — `next` lists tasks with no unmet dependencies, marking parallel-safe ones so multiple agents can pick them up:
+
+![openspecpm next](docs/screenshots/next.png)
+
+**8 · "What's waiting on what?"** — `blocked` lists every task held up by a dependency and names the blocker, so the path to unblocking is one read away:
+
+![openspecpm blocked](docs/screenshots/blocked.png)
+
+**9 · Parallel-agent dispatch** — `fan-out` emits ready-to-paste prompts for `parallel: true` tasks with no unmet deps. Each prompt embeds the proposal summary, design notes, and BDD spec as acceptance criteria so subagents can work in isolation:
+
+![openspecpm fan-out](docs/screenshots/fan-out.png)
+
+**10 · Cross-file search** — `search` is a case-insensitive grep across every proposal, spec, tasks file, and progress note. Useful for tracing back from a keyword to the change that owns it:
+
+![openspecpm search](docs/screenshots/search.png)
+
+**11 · Project-wide validation** — `validate` runs the schema check and BDD linter across every change and reports per-feature error + warning counts:
+
+![openspecpm validate](docs/screenshots/validate.png)
+
+## Quick start
+
+```bash
+# 1. One-time setup. The wizard asks which PM tool your team uses.
+npx openspecpm init
+
+# 2. Verify auth before doing anything remote.
+npx openspecpm doctor
+
+# 3. Author a proposal. OpenSpec generates proposal.md, design.md, tasks.md,
+#    and BDD scenarios in specs/. Soft BDD-lint runs after authoring.
+npx openspecpm propose dark-mode --prompt "Per-user dark theme with persistence."
+
+# 4. Review the generated files. Refine BDD scenarios until lint is clean.
+
+# 5. Sync to the PM tool. Hard BDD lint runs first; pass --force to override.
+npx openspecpm sync dark-mode
+
+# 6. Pick up where you left off.
+npx openspecpm next        # tasks ready to start
+npx openspecpm blocked     # tasks waiting on dependencies
+npx openspecpm standup     # progress updates in the last 24h
+
+# 7. When the feature is verified, close + archive.
+npx openspecpm ship dark-mode
+```
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `init` | Interactive wizard. Picks the PM tool. Writes `.openspecpm/config.json`. |
+| `doctor [adapter]` | Auth/tooling health check. English remediation hints on every failure. |
+| `propose <feature> [--llm]` | Shell out to OpenSpec; create `openspec/changes/<feature>/`. Soft-lint BDD scenarios; `--llm` adds the LLM judge. |
+| `decompose <feature>` | Extract tasks from proposal headings/checklists + BDD scenarios into `tasks.md`. |
+| `sync <feature> [--llm]` | Hard-lint BDD, then create/update work items in the PM tool. Idempotent; `--llm` adds the LLM judge as a hard gate. |
+| `comment <feature> <task>` | Broadcast local `progress.md` (or `-m`) to the PM tool with `<!-- SYNCED -->` marker. |
+| `reconcile <feature>` | Pull remote work-item state into local frontmatter. Detects out-of-band closes. |
+| `bug-report <feature> <task> --title "…"` | File a linked regression against a shipped task. |
+| `status` | Per-change task counts: pending / created / failed / done. |
+| `standup [--since 24h]` | Recent `progress.md` updates, newest first. |
+| `next [-l 5]` | Tasks with no unmet dependencies. |
+| `blocked` | Tasks waiting on unmet dependencies (with reasons). |
+| `validate [--llm]` | Schema + dependency + BDD-lint sweep across every change; `--llm` adds the LLM judge per change. |
+| `search <query>` | Grep across proposals, specs, tasks, progress notes. |
+| `fan-out <feature>` | Emit ready-to-paste agent prompts for `parallel: true` tasks. |
+| `ship <feature> [-y]` | Close all task work items + close the epic + archive the OpenSpec change. |
+| `help-table [topic]` | Context-aware command reference grouped by workflow phase. |
+
+Every command appends a JSONL entry (secrets scrubbed) to `.openspecpm/audit.log`.
 
 ## Workflow phases
 
@@ -337,9 +339,9 @@ OpenSpecPM is organized into five phases, each with a reference doc under [`skil
 
 ## Roadmap
 
-Active v2 work is tracked as OpenSpec changes under [`openspec/changes/`](openspec/changes/README.md). Six features are scaffolded with full proposals, dependency-aware task lists, and BDD scenarios: dependency-graph visualization, LLM-backed BDD reviewer, spec → test scaffolding, compliance traceability export, three new adapters (Notion / ClickUp / Asana), and a real agent orchestrator that graduates `fan-out` from prompt-emitter to dispatcher.
+Active v2 work is tracked as OpenSpec changes under [`openspec/changes/`](openspec/changes/README.md). The first scaffolded feature — **`bdd-llm-reviewer`** — shipped in v1.0.0. Five remain: dependency-graph visualization, spec → test scaffolding, compliance traceability export, three new adapters (Notion / ClickUp / Asana), and a real agent orchestrator that graduates `fan-out` from prompt-emitter to dispatcher.
 
-OpenSpecPM dogfoods itself: anyone can `openspecpm next` to see what's ready to start, or `openspecpm sync <change>` to push any of the six into a tracked PM tool.
+OpenSpecPM dogfoods itself: anyone can `openspecpm next` to see what's ready to start, or `openspecpm sync <change>` to push any of the five into a tracked PM tool.
 
 ## Project structure
 
@@ -348,19 +350,32 @@ openspecpm/
 ├── README.md              this file
 ├── LICENSE                MIT
 ├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── SECURITY.md
 ├── package.json
-├── .github/workflows/test.yml
+├── .github/
+│   ├── workflows/         test.yml · auto-approve.yml · release.yml · publish.yml
+│   ├── ISSUE_TEMPLATE/
+│   └── PULL_REQUEST_TEMPLATE.md
+├── docs/screenshots/      README captures + render.ps1 renderer
+├── openspec/changes/      v2 roadmap (each subdir is a tracked change)
 ├── skill/openspecpm/      Claude Code Agent Skill
 │   ├── SKILL.md
-│   └── references/        conventions, plan, structure, sync, execute, track
+│   └── references/        conventions · plan · structure · sync · execute · track
 └── cli/
     ├── bin/openspecpm.js  Commander entrypoint
     ├── src/
-    │   ├── commands/      init, doctor, propose, sync, status, standup, next, blocked, ship
-    │   ├── adapters/      base, github, azure, jira, index
-    │   ├── bdd/           linter, templates
-    │   ├── http.js        REST helper for ADO + Jira
-    │   ├── tracking.js    listChanges, findNext, findBlocked, findRecent
+    │   ├── commands/      init · doctor · propose · decompose · sync · comment · reconcile ·
+    │   │                  status · standup · next · blocked · validate · search · fan-out ·
+    │   │                  bug-report · ship · assign · watch · help · bulk
+    │   ├── adapters/      base · github · azure · jira · linear · gitlab · index
+    │   ├── bdd/           linter · judge · templates
+    │   ├── audit.js       JSONL audit log + secret scrubber
+    │   ├── http.js        REST helper for ADO / Jira / Linear / GitLab
+    │   ├── tracking.js    listChanges · findNext · findBlocked · findRecent
+    │   ├── notify.js      Slack / Teams / generic-webhook envelopes
+    │   ├── telemetry.js   opt-in, audit-log-only at alpha
+    │   ├── install-hints.js
     │   ├── openspec-bridge.js
     │   ├── config.js
     │   ├── frontmatter.js

package/cli/bin/openspecpm.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { audited } from '../src/audit.js';
+
+// Read version from package.json so `npm version` bumps and the CLI's
+// `--version` output stay in sync. package.json always ships in the
+// npm tarball, so this resolves correctly under `npx openspecpm`.
+const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 import { runInit } from '../src/commands/init.js';
 import { runDoctor } from '../src/commands/doctor.js';
 import { runPropose } from '../src/commands/propose.js';
@@ -27,7 +33,7 @@ const program = new Command();
 program
   .name('openspecpm')
   .description('Spec-driven, BDD-shaped project management for AI agents.')
-  .version('0.1.0-alpha.0');
+  .version(pkg.version);
 
 program
   .command('init')
@@ -192,10 +198,21 @@ program
   .description('Context-aware help grouped by workflow phase')
   .action((topic) => { runHelp({ topic }); });
 
+// Sanitize uncaught errors so a future programming bug (TypeError, etc.)
+// doesn't dump a stack trace with absolute install / tmp paths to stderr.
+// fatal() is the normal path; these handlers are insurance for code paths
+// that don't reach Commander's .catch(fatal).
+process.on('uncaughtException', fatal);
+process.on('unhandledRejection', (reason) => {
+  fatal(reason instanceof Error ? reason : new Error(String(reason ?? 'unknown')));
+});
+
 program.parseAsync(process.argv);
 
 function fatal(err) {
-  process.stderr.write(`\n✖ ${err.message}\n`);
-  if (err.remediation) process.stderr.write(`  → ${err.remediation}\n`);
+  const msg = err?.message ?? String(err ?? 'unknown error');
+  process.stderr.write(`\n✖ ${msg}\n`);
+  if (err?.remediation) process.stderr.write(`  → ${err.remediation}\n`);
+  process.stderr.write(`  See .openspecpm/audit.log for details.\n`);
   process.exit(1);
 }

package/cli/src/adapters/azure.js

@@ -2,6 +2,11 @@ import { Adapter, AdapterError } from './base.js';
 import { HttpClient, basicAuth } from '../http.js';
 import { TokenBucket, PRESETS } from '../ratelimit.js';
 
+// User-controlled ids (from tasks.md frontmatter) MUST be encoded before
+// interpolation into URL paths or body URL values, or a value like
+// "1/../99" can reach unintended endpoints.
+const enc = (v) => encodeURIComponent(String(v));
+
 const API_VERSION = '7.1';
 const COMMENTS_API_VERSION = '7.1-preview.3';
 
@@ -151,11 +156,11 @@ export class AzureAdapter extends Adapter {
         path: '/relations/-',
         value: {
           rel: 'System.LinkTypes.Hierarchy-Reverse',
-          url: `${this.config.baseUrl ?? `https://dev.azure.com/${this.config.organization}`}/_apis/wit/workItems/${parent.id}`,
+          url: `${this.config.baseUrl ?? `https://dev.azure.com/${this.config.organization}`}/_apis/wit/workItems/${enc(parent.id)}`,
         },
       },
     ];
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${child.id}`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${enc(child.id)}`;
     await this.#req('PATCH', path, {
       query: { 'api-version': API_VERSION },
       body: ops,
@@ -164,7 +169,7 @@ export class AzureAdapter extends Adapter {
   }
 
   async addProgressComment(item, body) {
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workItems/${item.id}/comments`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workItems/${enc(item.id)}/comments`;
     await this.#req('POST', path, {
       query: { 'api-version': COMMENTS_API_VERSION },
       body: { text: body },
@@ -179,7 +184,7 @@ export class AzureAdapter extends Adapter {
     if (patch.iterationPath) ops.push({ op: 'add', path: '/fields/System.IterationPath', value: patch.iterationPath });
     if (patch.areaPath) ops.push({ op: 'add', path: '/fields/System.AreaPath', value: patch.areaPath });
     if (!ops.length) return;
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${item.id}`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${enc(item.id)}`;
     await this.#req('PATCH', path, {
       query: { 'api-version': API_VERSION },
       body: ops,
@@ -193,7 +198,7 @@ export class AzureAdapter extends Adapter {
   }
 
   async getWorkItem(item) {
-    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${item.id}`;
+    const path = `/${encodeURIComponent(this.#project())}/_apis/wit/workitems/${enc(item.id)}`;
     const data = await this.#req('GET', path, { query: { 'api-version': API_VERSION } });
     return {
       ref: { adapter: 'azure', id: String(data.id), url: data._links?.html?.href },
@@ -206,6 +211,17 @@ export class AzureAdapter extends Adapter {
 
   async listWorkItems(query = {}) {
     const tag = query.tag ?? `openspec`;
+    // Defense in depth: WIQL string-literal syntax means `'` is the only
+    // breakout char and we already double it. But there's no known WIQL
+    // feature that escapes a literal via other chars, so reject anything
+    // outside a known-safe set rather than trust escaping alone. Tags in
+    // this codebase are always `openspec` or `openspec:<feature>`; the
+    // feature side is validated by openspec-bridge.assertSafeFeatureName.
+    if (!/^[a-zA-Z0-9._:-]+$/.test(String(tag))) {
+      throw new AdapterError(`Unsafe tag for WIQL: "${tag}".`, {
+        remediation: 'Tag must match /^[a-zA-Z0-9._:-]+$/. Use a plain slug.',
+      });
+    }
     const wiql = `SELECT [System.Id], [System.Title], [System.State], [System.Tags], [System.AssignedTo] FROM workitems WHERE [System.TeamProject] = @project AND [System.Tags] CONTAINS '${tag.replace(/'/g, "''")}' ORDER BY [System.Id] DESC`;
     const path = `/${encodeURIComponent(this.#project())}/_apis/wit/wiql`;
     const res = await this.#req('POST', path, {

package/cli/src/adapters/gitlab.js

@@ -2,6 +2,11 @@ import { Adapter, AdapterError } from './base.js';
 import { HttpClient } from '../http.js';
 import { TokenBucket } from '../ratelimit.js';
 
+// User-controlled ids (from tasks.md frontmatter) MUST be encoded before
+// interpolation into URL paths, or a value like "1/../99" can reach
+// unintended project endpoints.
+const enc = (v) => encodeURIComponent(String(v));
+
 const STATE_TO_NORMALIZED = (s) => {
   const v = (s ?? '').toLowerCase();
   if (v === 'closed') return 'closed';
@@ -109,7 +114,7 @@ export class GitLabAdapter extends Adapter {
   }
 
   async linkWorkItems(parent, child, type = 'relates_to') {
-    await this.#req('POST', `/projects/${this.#project()}/issues/${child.id}/links`, {
+    await this.#req('POST', `/projects/${this.#project()}/issues/${enc(child.id)}/links`, {
       body: {
         target_project_id: this.config.projectId,
         target_issue_iid: parent.id,
@@ -119,7 +124,7 @@ export class GitLabAdapter extends Adapter {
   }
 
   async addProgressComment(item, body) {
-    await this.#req('POST', `/projects/${this.#project()}/issues/${item.id}/notes`, {
+    await this.#req('POST', `/projects/${this.#project()}/issues/${enc(item.id)}/notes`, {
       body: { body },
     });
   }
@@ -134,18 +139,18 @@ export class GitLabAdapter extends Adapter {
     if (patch.milestoneId) body.milestone_id = patch.milestoneId;  // sprint
     if (patch.weight !== undefined) body.weight = patch.weight;     // story points
     if (!Object.keys(body).length) return;
-    await this.#req('PUT', `/projects/${this.#project()}/issues/${item.id}`, { body });
+    await this.#req('PUT', `/projects/${this.#project()}/issues/${enc(item.id)}`, { body });
   }
 
   async closeWorkItem(item, resolution) {
-    await this.#req('PUT', `/projects/${this.#project()}/issues/${item.id}`, {
+    await this.#req('PUT', `/projects/${this.#project()}/issues/${enc(item.id)}`, {
       body: { state_event: 'close' },
     });
     if (resolution) await this.addProgressComment(item, resolution);
   }
 
   async getWorkItem(item) {
-    const data = await this.#req('GET', `/projects/${this.#project()}/issues/${item.id}`);
+    const data = await this.#req('GET', `/projects/${this.#project()}/issues/${enc(item.id)}`);
     return {
       ref: { adapter: 'gitlab', id: String(data.iid), url: data.web_url },
       title: data.title,

package/cli/src/audit.js

@@ -13,12 +13,15 @@ export async function record({ command, args = {}, result = null, error = null,
   if (!command) return;
   const path = auditPath(cwd);
   await mkdir(dirname(path), { recursive: true });
+  const errorText = error ? (typeof error === 'string' ? error : error.message ?? String(error)) : null;
   const entry = {
     ts: new Date().toISOString(),
     command,
     args: scrub(args),
-    result: result ? truncate(result, 500) : null,
-    error: error ? truncate(typeof error === 'string' ? error : error.message ?? String(error), 500) : null,
+    // result + error can carry user-supplied strings (e.g. a failing-fetch
+    // message containing a webhook URL). Run them through scrubValue too.
+    result: result ? truncate(scrubValue(String(result)), 500) : null,
+    error: errorText ? truncate(scrubValue(errorText), 500) : null,
   };
   if (meta && typeof meta === 'object') entry.meta = scrub(meta);
   await appendFile(path, JSON.stringify(entry) + '\n', 'utf8');
@@ -34,7 +37,21 @@ export async function tail(n = 50, cwd = process.cwd()) {
   });
 }
 
-const SECRET_SEGMENTS = new Set(['token', 'secret', 'password', 'pat', 'auth', 'credential']);
+const SECRET_SEGMENTS = new Set([
+  // Original set.
+  'token', 'secret', 'password', 'pat', 'auth', 'credential',
+  // Added: real-world key naming a CLI accumulates over time.
+  // bearer/cookie/session — bearer credentials by name.
+  // webhook — Slack/Teams URLs ARE the credential.
+  // signature — webhook HMAC sigs, request-signing headers.
+  // assertion — SAML / OIDC.
+  'bearer', 'cookie', 'session', 'webhook', 'signature', 'assertion',
+]);
+
+// Webhook URLs that act as bearer credentials. Anyone holding the URL can
+// post to the channel. Redact in any string value so accidental logging
+// (e.g. a failing-fetch error message embedding the URL) never leaks.
+const WEBHOOK_URL_RE = /https:\/\/(?:hooks\.slack\.com\/services|[^\/\s"'`]*\.webhook\.office(?:365)?\.com|outlook\.office(?:365)?\.com\/webhook)[^\s"'`]+/gi;
 
 function isSecretKey(k) {
   if (/api[_-]?key/i.test(k)) return true;
@@ -44,7 +61,13 @@ function isSecretKey(k) {
   return false;
 }
 
+function scrubValue(s) {
+  if (typeof s !== 'string') return s;
+  return s.replace(WEBHOOK_URL_RE, '<redacted-webhook>');
+}
+
 function scrub(obj) {
+  if (typeof obj === 'string') return scrubValue(obj);
   if (!obj || typeof obj !== 'object') return obj;
   if (Array.isArray(obj)) return obj.map(scrub);
   const out = {};
@@ -54,9 +77,9 @@ function scrub(obj) {
     } else if (v && typeof v === 'object') {
       out[k] = scrub(v);
     } else if (typeof v === 'string' && v.length > 200) {
-      out[k] = v.slice(0, 200) + '…';
+      out[k] = scrubValue(v).slice(0, 200) + '…';
     } else {
-      out[k] = v;
+      out[k] = scrubValue(v);
     }
   }
   return out;

package/cli/src/commands/bulk.js

@@ -31,6 +31,11 @@ export async function runSyncAll({ dryRun = false, force = false, yes = false }
     }
   }
   process.stdout.write(`\nSummary: ${synced} synced, ${failed} failed.\n`);
+  if (failed > 0) {
+    const err = new Error(`${failed} change(s) failed to sync.`);
+    err.remediation = 'See per-change errors above; re-run for affected features after fixing.';
+    throw err;
+  }
 }
 
 export async function runShipAllReady({ yes = false, skipArchive = false } = {}) {
@@ -64,4 +69,9 @@ export async function runShipAllReady({ yes = false, skipArchive = false } = {})
     }
   }
   process.stdout.write(`\nSummary: ${shipped} shipped, ${failed} failed.\n`);
+  if (failed > 0) {
+    const err = new Error(`${failed} change(s) failed to ship.`);
+    err.remediation = 'See per-change errors above; re-run for affected features after fixing.';
+    throw err;
+  }
 }

package/cli/src/commands/reconcile.js

@@ -4,6 +4,7 @@ import { readConfig } from '../config.js';
 import { loadAdapter } from '../adapters/index.js';
 import { changeDir, changeExists } from '../openspec-bridge.js';
 import * as fm from '../frontmatter.js';
+import { coerceItems, safeParseFrontmatter } from '../tracking.js';
 
 export async function runReconcile({ feature, dryRun = false } = {}) {
   if (!feature) throw new Error('feature name is required');
@@ -17,10 +18,22 @@ export async function runReconcile({ feature, dryRun = false } = {}) {
 
   const dir = changeDir(feature);
   const tasksPath = join(dir, 'tasks.md');
-  let tasksRaw = '';
-  try { tasksRaw = await readFile(tasksPath, 'utf8'); } catch { /* missing */ }
-  const { data: tdata, body: tbody } = fm.parse(tasksRaw);
-  const items = tdata.items ?? [];
+  // Read + validate through the same helpers loadChange uses, so a non-array
+  // items: (or malformed YAML) raises a clear error instead of iterating
+  // character-by-character.
+  let tdata = {};
+  let tbody = '';
+  try {
+    ({ data: tdata, body: tbody } = await safeParseFrontmatter(tasksPath, feature, 'tasks.md'));
+  } catch (err) {
+    if (err.code === 'ENOENT' || /no such file/i.test(err.message)) {
+      // tasks.md missing — nothing to reconcile.
+      process.stdout.write('No items in tasks.md to reconcile.\n');
+      return;
+    }
+    throw err;
+  }
+  const items = coerceItems(tdata.items, tbody, feature);
   if (!items.length) {
     process.stdout.write('No items in tasks.md to reconcile.\n');
     return;

package/cli/src/commands/sync.js

@@ -7,6 +7,7 @@ import { changeDir, changeExists } from '../openspec-bridge.js';
 import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
 import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
 import * as fm from '../frontmatter.js';
+import { coerceItems, safeParseFrontmatter } from '../tracking.js';
 import { record } from '../audit.js';
 
 export async function runSync({ feature, dryRun = false, force = false, diff = false, llm = false } = {}) {
@@ -102,9 +103,11 @@ export async function runSync({ feature, dryRun = false, force = false, diff = f
     out('No tasks.md found — only the epic was synced.');
     return;
   }
-  const tasksRaw = await readFile(tasksPath, 'utf8');
-  const { data: tdata, body: tbody } = fm.parse(tasksRaw);
-  const items = tdata.items ?? parseChecklist(tbody);
+  // Route through the same parse+coerce helpers loadChange uses, so a
+  // non-array items: (or malformed YAML) is rejected here too — sync is the
+  // primary command and bypassing the validator was the H3 regression.
+  const { data: tdata, body: tbody } = await safeParseFrontmatter(tasksPath, feature, 'tasks.md');
+  const items = coerceItems(tdata.items, tbody, feature);
   const updatedItems = [];
 
   for (const task of items) {
@@ -132,16 +135,52 @@ export async function runSync({ feature, dryRun = false, force = false, diff = f
     const patched = fm.serialize({ ...tdata, items: updatedItems }, tbody);
     await writeFile(tasksPath, patched, 'utf8');
   }
+
+  // Exit with a non-zero status if any task failed, so CI invocations like
+  // `openspecpm sync feature && deploy` don't proceed on silent partial sync.
+  // The tasks.md patch above already persisted last_error per failed task.
+  const failed = updatedItems.filter((t) => t.sync_state === 'failed');
+  if (failed.length) {
+    const err = new Error(`${failed.length} task(s) failed to sync in "${feature}".`);
+    err.remediation = 'Inspect last_error in tasks.md frontmatter and re-run sync to retry only failed items.';
+    throw err;
+  }
 }
 
 function out(s) {
   process.stdout.write(s + '\n');
 }
 
+// Strip C0/C1 control chars (except common whitespace), bidi overrides, and
+// zero-width chars from text we forward to a remote tracker as an issue body.
+// A proposal author could intentionally or accidentally include these and
+// they show up confusingly (or as homograph-attack vectors) in GitHub/Jira
+// issue UIs. Implemented as a codepoint predicate rather than a regex literal
+// so the source file stays pure ASCII (a regex with literal control chars
+// makes git treat the file as binary).
+function isPrintableChar(cp) {
+  if (cp === 0x09 || cp === 0x0A || cp === 0x0D) return true; // keep TAB / LF / CR
+  if (cp <= 0x1F) return false;                                // C0 controls
+  if (cp === 0x7F) return false;                               // DEL
+  if (cp >= 0x80 && cp <= 0x9F) return false;                  // C1 controls
+  if (cp >= 0x200B && cp <= 0x200F) return false;              // zero-width + joiners + LRM/RLM
+  if (cp >= 0x202A && cp <= 0x202E) return false;              // LRE/RLE/PDF/LRO/RLO bidi overrides
+  if (cp >= 0x2066 && cp <= 0x2069) return false;              // LRI/RLI/FSI/PDI isolates
+  return true;
+}
+
+function sanitizeText(s) {
+  const out = [];
+  for (const ch of String(s)) {
+    if (isPrintableChar(ch.codePointAt(0))) out.push(ch);
+  }
+  return out.join('');
+}
+
 function extractSummary(md) {
   const { body } = fm.parse(md);
   const firstPara = body.split(/\r?\n\r?\n/).find((p) => p.trim() && !p.startsWith('#'));
-  return (firstPara ?? '').trim().slice(0, 1000);
+  return sanitizeText((firstPara ?? '').trim()).slice(0, 1000);
 }
 
 function parseChecklist(body) {

package/cli/src/http.js

@@ -1,13 +1,16 @@
 import { AdapterError } from './adapters/base.js';
 
+const DEFAULT_TIMEOUT_MS = 30_000;
+
 export class HttpClient {
   #baseUrl;
   #authHeader;
   #fetchImpl;
   #defaultHeaders;
   #remediationHint;
+  #timeoutMs;
 
-  constructor({ baseUrl, auth, fetch: fetchImpl = globalThis.fetch, defaultHeaders = {}, remediationHint } = {}) {
+  constructor({ baseUrl, auth, fetch: fetchImpl = globalThis.fetch, defaultHeaders = {}, remediationHint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
     if (!baseUrl) throw new Error('HttpClient requires baseUrl');
     if (typeof fetchImpl !== 'function') throw new Error('global fetch not available; pass {fetch} explicitly');
     this.#baseUrl = baseUrl.replace(/\/+$/, '');
@@ -15,6 +18,7 @@ export class HttpClient {
     this.#fetchImpl = fetchImpl;
     this.#defaultHeaders = defaultHeaders;
     this.#remediationHint = remediationHint;
+    this.#timeoutMs = timeoutMs;
   }
 
   async request(method, path, { query, body, headers, contentType = 'application/json', accept = 'application/json' } = {}) {
@@ -35,10 +39,18 @@ export class HttpClient {
       finalHeaders['Content-Type'] = contentType;
     }
 
+    // Bound the request with an abort signal so a hung backend can't wedge sync --all.
+    const signal = AbortSignal.timeout(this.#timeoutMs);
     let res;
     try {
-      res = await this.#fetchImpl(url, { method, headers: finalHeaders, body: payload });
+      res = await this.#fetchImpl(url, { method, headers: finalHeaders, body: payload, signal });
     } catch (err) {
+      if (err?.name === 'TimeoutError' || err?.name === 'AbortError') {
+        throw new AdapterError(`${method} ${url} timed out after ${this.#timeoutMs}ms`, {
+          remediation: 'Backend did not respond in time. Retry, or raise HttpClient timeoutMs if the endpoint is known-slow.',
+          cause: err,
+        });
+      }
       throw new AdapterError(`Network error calling ${method} ${url}: ${err.message}`, {
         remediation: this.#remediationHint ?? 'Check connectivity and base URL.',
         cause: err,

package/cli/src/notify.js

@@ -24,19 +24,42 @@ export async function notify({ config, title, body, level = 'info', fetchImpl =
   const errors = [];
   for (const t of targets) {
     try {
-      await fetchImpl(t.url, {
+      const res = await fetchImpl(t.url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(formatPayload(t.kind, { title, body, level })),
       });
+      // A 401/403/500 from Slack/Teams reaches the network but the message
+      // never lands. Without this check, those would be counted as `sent`,
+      // and a user running `standup --broadcast` would think their channel
+      // got the update when the webhook silently rejected it.
+      if (!res?.ok) {
+        const status = res?.status ?? '?';
+        const statusText = res?.statusText ?? '';
+        let snippet = '';
+        try {
+          snippet = (await res.text()).slice(0, 200);
+        } catch { /* res.text() failed; ignore */ }
+        errors.push({ target: t.kind, error: redactUrl(t.url, `HTTP ${status} ${statusText}${snippet ? ` — ${snippet}` : ''}`) });
+        continue;
+      }
       sent++;
     } catch (err) {
-      errors.push({ target: t.kind, error: err.message });
+      // Strip the webhook URL from fetch's error message before returning it.
+      // The URL is itself a bearer credential for Slack/Teams — anyone holding
+      // it can post to the channel. We don't want it surfacing in audit.log
+      // or stdout via a caller that surfaces this errors[] array.
+      errors.push({ target: t.kind, error: redactUrl(t.url, err.message ?? String(err)) });
     }
   }
   return { sent, errors };
 }
 
+function redactUrl(url, msg) {
+  if (!url || typeof msg !== 'string') return msg;
+  return msg.split(url).join('<webhook>');
+}
+
 function formatPayload(kind, { title, body, level }) {
   const text = `*${title}*\n${body}`;
   if (kind === 'slack') return { text };

package/cli/src/openspec-bridge.js

@@ -49,15 +49,46 @@ export async function probe({ runner = execa } = {}) {
   return { version };
 }
 
+// Feature names appear in filesystem paths (`openspec/changes/<feature>/`) and in
+// the subprocess invocation of `openspec propose <feature>`. An unvalidated
+// `feature` like `../../etc` would let path.join escape the openspec/changes
+// tree and write/read files anywhere the process has access to. Validate at
+// every entry point that consumes a feature name.
+const FEATURE_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+
+export function assertSafeFeatureName(feature) {
+  if (typeof feature !== 'string' || feature.length === 0) {
+    const e = new Error('feature name is required.');
+    e.remediation = 'Provide a feature slug like `dark-mode`.';
+    throw e;
+  }
+  // Reject the obviously dangerous patterns up front for clearer error messages.
+  if (feature.includes('..') || feature.includes('/') || feature.includes('\\') || /^[a-z]:/i.test(feature)) {
+    const e = new Error(`Invalid feature name: "${feature}".`);
+    e.remediation = 'Feature names cannot contain "..", "/", "\\\\", or drive letters. Use a slug like `dark-mode`.';
+    throw e;
+  }
+  if (!FEATURE_NAME_RE.test(feature)) {
+    const e = new Error(`Invalid feature name: "${feature}".`);
+    e.remediation = 'Feature names must match /^[a-z0-9][a-z0-9._-]*$/i — start with a letter or digit; only letters, digits, `.`, `_`, `-` after that.';
+    throw e;
+  }
+}
+
 export function changeDir(feature, cwd = process.cwd()) {
+  assertSafeFeatureName(feature);
   return join(cwd, OPENSPEC_CHANGES_DIR, feature);
 }
 
 export function changeExists(feature, cwd = process.cwd()) {
+  assertSafeFeatureName(feature);
   return existsSync(changeDir(feature, cwd));
 }
 
 export async function propose(feature, prompt, { runner = execa, cwd = process.cwd() } = {}) {
+  // Validate before the subprocess call so we never hand a traversal value to
+  // the openspec CLI (it may or may not validate on its own; we don't trust).
+  assertSafeFeatureName(feature);
   await probe({ runner });
   await runner('openspec', ['propose', feature, '--prompt', prompt], { cwd, stdio: 'inherit' });
   return changeDir(feature, cwd);

package/cli/src/tracking.js

@@ -36,20 +36,45 @@ export async function loadChange(name, cwd = process.cwd()) {
   let proposal = {};
   const proposalPath = join(dir, 'proposal.md');
   if (existsSync(proposalPath)) {
-    const raw = await readFile(proposalPath, 'utf8');
-    proposal = fm.parse(raw).data ?? {};
+    const parsed = await safeParseFrontmatter(proposalPath, name, 'proposal.md');
+    proposal = parsed.data ?? {};
   }
   let items = [];
   const tasksPath = join(dir, 'tasks.md');
   if (existsSync(tasksPath)) {
-    const raw = await readFile(tasksPath, 'utf8');
-    const { data, body } = fm.parse(raw);
-    items = data.items ?? parseChecklist(body);
+    const { data, body } = await safeParseFrontmatter(tasksPath, name, 'tasks.md');
+    items = coerceItems(data.items, body, name);
   }
   const mtime = await mostRecentMtime(dir);
   return { name, dir, proposal, items, mtime };
 }
 
+export async function safeParseFrontmatter(path, changeName, fileLabel) {
+  const raw = await readFile(path, 'utf8');
+  try {
+    return fm.parse(raw);
+  } catch (err) {
+    const e = new Error(`${changeName}/${fileLabel}: YAML frontmatter is malformed (${err.message?.split('\n')[0] ?? err.name}).`);
+    e.remediation = `Repair the YAML in openspec/changes/${changeName}/${fileLabel}. Validate with \`openspecpm validate\` after fixing.`;
+    throw e;
+  }
+}
+
+export function coerceItems(rawItems, body, changeName) {
+  if (rawItems === undefined || rawItems === null) {
+    // No items: in frontmatter — fall back to the checklist body parser.
+    return parseChecklist(body);
+  }
+  if (!Array.isArray(rawItems)) {
+    const e = new Error(`${changeName}/tasks.md: frontmatter "items:" must be a YAML array, got ${Array.isArray(rawItems) ? 'array' : typeof rawItems}.`);
+    e.remediation = `Edit openspec/changes/${changeName}/tasks.md so "items:" is a list (each entry starts with "- title: ...").`;
+    throw e;
+  }
+  // Filter out malformed entries (silently skipping is better than crashing
+  // deep in a downstream consumer with `TypeError: items is not iterable`).
+  return rawItems.filter((t) => t && typeof t === 'object' && typeof t.title === 'string');
+}
+
 /**
  * Resolve a dep token against a change. Tokens may be:
  *   "task title"                — same-change reference by title

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspecpm",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Spec-driven, BDD-shaped project management for AI agents — OpenSpec proposals synced to GitHub, Azure DevOps, Jira, Linear, or GitLab.",
   "type": "module",
   "bin": {

package/skill/openspecpm/SKILL.md

@@ -5,7 +5,7 @@ description: "OpenSpecPM — spec-driven, BDD-shaped project management for any
 
 # OpenSpecPM — Spec-driven PM Agent Skill
 
-A sibling of CCPM with three differences: **OpenSpec** authors the specs, **adapters** make the PM backend pluggable (GitHub / Azure DevOps / Jira / Linear / GitLab), and the wizard is **friendly to non-engineers**.
+A sibling of CCPM with five differences: **OpenSpec** authors the specs (with a heuristic BDD linter plus an optional LLM judge), **adapters** make the PM backend pluggable (GitHub / Azure DevOps / Jira / Linear / GitLab), the wizard is **friendly to non-engineers**, every command is **audit-logged** by default, and `depends_on:` reaches **across features** so `next`/`blocked` reflect the whole project.
 
 ## Workflow
 
@@ -14,7 +14,7 @@ idea → openspecpm propose <feature>           (OpenSpec authors proposal.md, d
      → review BDD scenarios                   (Given/When/Then)
      → openspecpm sync <feature>              (push to chosen PM backend, idempotent)
      → openspecpm status / standup            (track local + remote)
-     → openspecpm ship <feature>              (Sprint 3+)
+     → openspecpm ship <feature>              (close + archive)
 ```
 
 ## Phases
@@ -25,7 +25,7 @@ idea → openspecpm propose <feature>           (OpenSpec authors proposal.md, d
 | **Structure** | A proposal exists and needs decomposition into tasks. | `references/structure.md` |
 | **Sync** | Local OpenSpec change needs to become PM-tool work items. | `references/sync.md` |
 | **Execute** | User wants to start work on a tracked item. | `references/execute.md` |
-| **Track** | User asks status / standup / what's next / what's blocked. | `references/track.md` (Sprint 3) |
+| **Track** | User asks status / standup / what's next / what's blocked. | `references/track.md` |
 
 ## Conventions
 

package/skill/openspecpm/references/conventions.md

@@ -79,7 +79,7 @@ Scenario: User toggles dark mode
   And their preference is saved to the profile
 ```
 
-Lint heuristics (enforced softly at `propose`, hard at `sync` in Sprint 3+):
+Lint heuristics (enforced softly at `propose`, hard at `sync`):
 
 - Each scenario has one `Given`, one `When`, one `Then` (with optional `And`s).
 - `Then` uses an observable verb (displays, returns, stores, rejects, emails, …).

package/skill/openspecpm/references/execute.md

@@ -29,9 +29,9 @@ A work item moved to `in_progress` in the PM tool, a local progress directory cr
 
 5. **Now do the work.** Use the spec scenarios in `openspec/changes/<feature>/specs/` as the acceptance criteria. Implement code, write tests, refactor — whatever the task requires. Use the BDD scenarios as the test plan, not just the spec.
 
-6. **Periodically broadcast progress.** Append to local `progress.md`, then sync to the PM tool with `openspecpm comment <task>` (Sprint 3). Don't post per-keystroke — once per meaningful checkpoint.
+6. **Periodically broadcast progress.** Append to local `progress.md`, then sync to the PM tool with `openspecpm comment <task>`. Don't post per-keystroke — once per meaningful checkpoint.
 
-7. **When done.** Run `openspecpm ship <feature>` (Sprint 3) to close the work item with a final comment and archive the OpenSpec change.
+7. **When done.** Run `openspecpm ship <feature>` to close the work item with a final comment and archive the OpenSpec change.
 
 ## Worktrees: hidden by default
 
@@ -41,7 +41,7 @@ Engineers may want a `git worktree` per feature so concurrent work doesn't colli
 openspecpm start <feature> --dev
 ```
 
-This creates `../openspec-<feature>/` on branch `openspec/<feature>`. **For non-technical users, do not surface this.** They will be confused by ghost folders. The default `start` command (Sprint 3+) skips the worktree and works in the current checkout.
+This creates `../openspec-<feature>/` on branch `openspec/<feature>`. **For non-technical users, do not surface this.** They will be confused by ghost folders. The default flow skips the worktree and works in the current checkout.
 
 ## Parallel agents
 
@@ -52,7 +52,7 @@ For each parallel task:
 2. Launch a sub-agent with a focused prompt: "Implement task T from the X feature. The BDD scenarios are at specs/Y.md. Use only files under <stream-scope>."
 3. Wait for completion, then merge.
 
-In Sprint 3, `openspecpm fan-out <feature>` automates the launch.
+`openspecpm fan-out <feature>` automates the launch by emitting ready-to-paste prompts for `parallel: true` tasks.
 
 ## What to avoid
 

package/skill/openspecpm/references/plan.md

@@ -42,6 +42,6 @@ A fully-formed OpenSpec change at `openspec/changes/<feature>/` containing:
 
 ## After this phase
 
-- If the user is ready to push to their PM tool: route to `references/sync.md` (Sprint 2).
-- If the user wants to decompose into tasks first: route to `references/structure.md` (Sprint 2).
+- If the user is ready to push to their PM tool: route to `references/sync.md`.
+- If the user wants to decompose into tasks first: route to `references/structure.md`.
 - If the user wants to check what other changes exist: run `openspecpm status`.

package/skill/openspecpm/references/sync.md

@@ -1,6 +1,6 @@
 # Sync — Pushing an OpenSpec change to the PM tool
 
-**When to use this:** The user has a proposal + tasks ready and wants them tracked in GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab Issues.
+**When to use this:** The user has a proposal + tasks ready and wants them tracked in GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab.
 
 ## Outcome
 
@@ -52,5 +52,5 @@ The CLI handles the translation. Author tasks in the OpenSpec/CCPM dialect descr
 ## After sync
 
 - Each item is now visible in the PM tool. The user can route stakeholders to those URLs for sign-off.
-- Progress narrative still lives locally in `openspec/changes/<feature>/updates/<task>/progress.md`. Use `openspecpm comment <task>` (Sprint 3) to broadcast a new update to the PM tool.
+- Progress narrative still lives locally in `openspec/changes/<feature>/updates/<task>/progress.md`. Use `openspecpm comment <task>` to broadcast a new update to the PM tool.
 - Route to `references/execute.md` when the user is ready to start building.