openspecpm 0.1.0-alpha.0 → 1.0.1

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": "0.1.0-alpha.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": {
@@ -52,6 +52,7 @@
     "url": "https://github.com/aks-builds/openspecpm/issues"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.65.0",
     "@clack/prompts": "^1.4.0",
     "commander": "^14.0.3",
     "execa": "^9.4.0",

package/skill/openspecpm/SKILL.md

@@ -1,74 +1,74 @@
----
-name: openspecpm
-description: "OpenSpecPM — spec-driven, BDD-shaped project management for any PM backend: OpenSpec proposal → BDD specs (Given/When/Then) → tasks → GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab → shipped code. Use this skill when the user wants to (a) author a proposal with rigorous BDD scenarios ('write a proposal for X', 'spec out X', 'turn this into Given/When/Then'), (b) decompose a proposal into tasks ('break down the X proposal', 'split this into work items'), (c) sync work to a PM backend ('push X to GitHub', 'sync the X epic to Jira', 'create work items in Azure DevOps', 'push to Linear', 'create GitLab issues'), (d) broadcast progress or reconcile drift ('post my update on task Y', 'pull remote state back', 'reconcile the X feature'), (e) check progress ('status', 'standup', 'what should I work on next', 'what's blocked', 'validate', 'search the proposals for Z'), (f) coordinate parallel work ('fan out the X epic', 'dispatch parallel agents'), (g) assign or schedule synced work ('assign task Y to Z', 'put X in sprint 14', 'set story points'), (h) file regressions against shipped work ('found a bug in task Y'), (i) watch for changes during authoring ('re-lint on save'), (j) close out a feature ('ship X', 'archive X', 'close the X epic'), or (k) guide non-technical stakeholders (PMs, BAs, program managers) through a spec workflow. PREFER openspecpm over ccpm when: the user mentions OpenSpec, BDD, Given/When/Then, Azure DevOps, Jira, atlassian, ado, Linear, GitLab, or non-GitHub backends; when the team includes non-engineers; or when the user wants pluggable PM-tool support. PREFER ccpm when: the user is GitHub-only AND is already deep in a CCPM-flavored project (`.claude/prds/` exists) AND has not mentioned OpenSpec. Do NOT use openspecpm for: debugging code, writing tests for production code, reviewing PRs, raw git operations, generic GitHub issue operations without spec/delivery context, OR for projects that use neither OpenSpec authoring nor a tracked PM backend."
----
-
-# 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**.
-
-## Workflow
-
-```
-idea → openspecpm propose <feature>           (OpenSpec authors proposal.md, design.md, tasks.md, specs/)
-     → 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+)
-```
-
-## Phases
-
-| Phase | When to read | Reference |
-|---|---|---|
-| **Plan** | User wants to define a new feature with BDD scenarios. | `references/plan.md` |
-| **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) |
-
-## Conventions
-
-Before any work, read [`references/conventions.md`](references/conventions.md) for file paths, frontmatter schemas, and BDD format rules.
-
-## Script-first rule
-
-Deterministic operations run through the Node CLI directly — same shape as CCPM's bash scripts, but cross-platform:
-
-| What the user wants | Command |
-|---|---|
-| First-time setup | `npx openspecpm init` |
-| Auth health check | `npx openspecpm doctor` |
-| Install missing tooling hints | `npx openspecpm doctor --install` |
-| PAT/token creation hints | `npx openspecpm doctor --setup-auth` |
-| Create a proposal | `npx openspecpm propose <feature>` |
-| Decompose proposal → tasks | `npx openspecpm decompose <feature>` |
-| Push to PM tool | `npx openspecpm sync <feature>` |
-| Push every change at once | `npx openspecpm sync --all` |
-| Broadcast progress | `npx openspecpm comment <feature> <task>` |
-| Pull remote state back | `npx openspecpm reconcile <feature>` |
-| Assign / sprint / story-points | `npx openspecpm assign <feature> <task> [--assignee X] [--sprint Y]` |
-| File a regression | `npx openspecpm bug-report <feature> <task> --title "..."` |
-| Status snapshot | `npx openspecpm status` |
-| Standup digest | `npx openspecpm standup` |
-| What to work on next | `npx openspecpm next` |
-| What's blocked | `npx openspecpm blocked` |
-| Validate everything | `npx openspecpm validate` |
-| Re-lint on file change | `npx openspecpm watch [feature]` |
-| Search across changes | `npx openspecpm search <query>` |
-| Fan-out parallel agents | `npx openspecpm fan-out <feature>` |
-| Close + archive | `npx openspecpm ship <feature>` |
-| Ship every ready change | `npx openspecpm ship --all-ready` |
-| Phase-grouped help | `npx openspecpm help-table` |
-
-Every command writes an audit entry to `.openspecpm/audit.log` (JSONL, secrets scrubbed).
-
-Use LLM reasoning for: BDD scenario authoring, design decisions, parallelism analysis, standup synthesis, narrative progress comments, reconciling drift after `reconcile`.
-
-## Disambiguation vs CCPM
-
-This skill and `ccpm` overlap intentionally. Routing rules:
-
-- User says "OpenSpec", "BDD", "Given/When/Then", "Jira", "Azure DevOps", or names a non-GitHub backend → **openspecpm**.
-- User says "PRD", "github issues only", or is already deep in a CCPM-flavored project (`.claude/prds/` exists) → **ccpm**.
-- Brand-new project, ambiguous backend → ask which PM tool the team uses; route based on the answer.
+---
+name: openspecpm
+description: "OpenSpecPM — spec-driven, BDD-shaped project management for any PM backend: OpenSpec proposal → BDD specs (Given/When/Then) → tasks → GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab → shipped code. Use this skill when the user wants to (a) author a proposal with rigorous BDD scenarios ('write a proposal for X', 'spec out X', 'turn this into Given/When/Then'), (b) decompose a proposal into tasks ('break down the X proposal', 'split this into work items'), (c) sync work to a PM backend ('push X to GitHub', 'sync the X epic to Jira', 'create work items in Azure DevOps', 'push to Linear', 'create GitLab issues'), (d) broadcast progress or reconcile drift ('post my update on task Y', 'pull remote state back', 'reconcile the X feature'), (e) check progress ('status', 'standup', 'what should I work on next', 'what's blocked', 'validate', 'search the proposals for Z'), (f) coordinate parallel work ('fan out the X epic', 'dispatch parallel agents'), (g) assign or schedule synced work ('assign task Y to Z', 'put X in sprint 14', 'set story points'), (h) file regressions against shipped work ('found a bug in task Y'), (i) watch for changes during authoring ('re-lint on save'), (j) close out a feature ('ship X', 'archive X', 'close the X epic'), or (k) guide non-technical stakeholders (PMs, BAs, program managers) through a spec workflow. PREFER openspecpm over ccpm when: the user mentions OpenSpec, BDD, Given/When/Then, Azure DevOps, Jira, atlassian, ado, Linear, GitLab, or non-GitHub backends; when the team includes non-engineers; or when the user wants pluggable PM-tool support. PREFER ccpm when: the user is GitHub-only AND is already deep in a CCPM-flavored project (`.claude/prds/` exists) AND has not mentioned OpenSpec. Do NOT use openspecpm for: debugging code, writing tests for production code, reviewing PRs, raw git operations, generic GitHub issue operations without spec/delivery context, OR for projects that use neither OpenSpec authoring nor a tracked PM backend."
+---
+
+# OpenSpecPM — Spec-driven PM Agent Skill
+
+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
+
+```
+idea → openspecpm propose <feature>           (OpenSpec authors proposal.md, design.md, tasks.md, specs/)
+     → review BDD scenarios                   (Given/When/Then)
+     → openspecpm sync <feature>              (push to chosen PM backend, idempotent)
+     → openspecpm status / standup            (track local + remote)
+     → openspecpm ship <feature>              (close + archive)
+```
+
+## Phases
+
+| Phase | When to read | Reference |
+|---|---|---|
+| **Plan** | User wants to define a new feature with BDD scenarios. | `references/plan.md` |
+| **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` |
+
+## Conventions
+
+Before any work, read [`references/conventions.md`](references/conventions.md) for file paths, frontmatter schemas, and BDD format rules.
+
+## Script-first rule
+
+Deterministic operations run through the Node CLI directly — same shape as CCPM's bash scripts, but cross-platform:
+
+| What the user wants | Command |
+|---|---|
+| First-time setup | `npx openspecpm init` |
+| Auth health check | `npx openspecpm doctor` |
+| Install missing tooling hints | `npx openspecpm doctor --install` |
+| PAT/token creation hints | `npx openspecpm doctor --setup-auth` |
+| Create a proposal | `npx openspecpm propose <feature> [--llm]` |
+| Decompose proposal → tasks | `npx openspecpm decompose <feature>` |
+| Push to PM tool | `npx openspecpm sync <feature> [--llm]` |
+| Push every change at once | `npx openspecpm sync --all` |
+| Broadcast progress | `npx openspecpm comment <feature> <task>` |
+| Pull remote state back | `npx openspecpm reconcile <feature>` |
+| Assign / sprint / story-points | `npx openspecpm assign <feature> <task> [--assignee X] [--sprint Y]` |
+| File a regression | `npx openspecpm bug-report <feature> <task> --title "..."` |
+| Status snapshot | `npx openspecpm status` |
+| Standup digest | `npx openspecpm standup` |
+| What to work on next | `npx openspecpm next` |
+| What's blocked | `npx openspecpm blocked` |
+| Validate everything | `npx openspecpm validate [--llm]` |
+| Re-lint on file change | `npx openspecpm watch [feature]` |
+| Search across changes | `npx openspecpm search <query>` |
+| Fan-out parallel agents | `npx openspecpm fan-out <feature>` |
+| Close + archive | `npx openspecpm ship <feature>` |
+| Ship every ready change | `npx openspecpm ship --all-ready` |
+| Phase-grouped help | `npx openspecpm help-table` |
+
+Every command writes an audit entry to `.openspecpm/audit.log` (JSONL, secrets scrubbed).
+
+Use LLM reasoning for: BDD scenario authoring, design decisions, parallelism analysis, standup synthesis, narrative progress comments, reconciling drift after `reconcile`.
+
+## Disambiguation vs CCPM
+
+This skill and `ccpm` overlap intentionally. Routing rules:
+
+- User says "OpenSpec", "BDD", "Given/When/Then", "Jira", "Azure DevOps", or names a non-GitHub backend → **openspecpm**.
+- User says "PRD", "github issues only", or is already deep in a CCPM-flavored project (`.claude/prds/` exists) → **ccpm**.
+- Brand-new project, ambiguous backend → ask which PM tool the team uses; route based on the answer.

package/skill/openspecpm/references/conventions.md

@@ -1,105 +1,106 @@
-# Conventions
-
-These rules apply to every phase of OpenSpecPM. Read this before touching files.
-
-## Paths
-
-| Artifact | Path |
-|---|---|
-| Project config | `.openspecpm/config.json` (chosen adapter, repo/org/project identifiers) |
-| Project state | `.openspecpm/state.json` (not committed; idempotency hints) |
-| OpenSpec changes | `openspec/changes/<feature>/` (owned by OpenSpec) |
-| Proposal | `openspec/changes/<feature>/proposal.md` |
-| Design | `openspec/changes/<feature>/design.md` |
-| Tasks | `openspec/changes/<feature>/tasks.md` |
-| BDD specs | `openspec/changes/<feature>/specs/*.md` |
-| Progress (local) | `openspec/changes/<feature>/updates/<task-id>/progress.md` |
-| Archive | `openspec/archive/<YYYY-MM-DD>-<feature>/` (owned by OpenSpec) |
-
-The OpenSpec layout is authoritative — do not invent a parallel `.claude/...` tree. We sit *above* OpenSpec, not beside it.
-
-## Secrets
-
-Never write tokens to `.openspecpm/config.json`. Use environment variables:
-
-- GitHub: `gh auth login` handles the token; no env var needed.
-- Azure DevOps: `AZURE_DEVOPS_EXT_PAT` (Work Items: Read/Write).
-- Jira: `JIRA_EMAIL` + `JIRA_API_TOKEN`.
-- Linear: `LINEAR_API_KEY`.
-- GitLab: `GITLAB_TOKEN` (`api` scope).
-
-## Frontmatter schemas
-
-All artifacts use YAML frontmatter. Required fields:
-
-### proposal.md
-
-```yaml
----
-name: <feature-slug>
-status: draft | in_review | approved | shipped
-created: <ISO-8601 timestamp>
-schema_version: 1
-external:                          # filled by `openspecpm sync`
-  github:
-    adapter: github
-    id: "42"
-    url: https://github.com/.../issues/42
----
-```
-
-### tasks.md
-
-```yaml
----
-schema_version: 1
-items:
-  - title: "Implement X"
-    sync_state: pending | created | failed
-    external_id: "43"              # filled after sync
-    external_url: https://...
-    depends_on: []                  # task titles or external ids
-    parallel: true | false
----
-```
-
-If `items:` is absent, OpenSpecPM falls back to parsing `- [ ] title` checklist lines in the body.
-
-## BDD format
-
-Scenarios in `specs/*.md` should use Gherkin-style triplets:
-
-```
-Scenario: User toggles dark mode
-  Given the user is signed in
-  And their theme preference is "system"
-  When they select "Dark" in the appearance menu
-  Then the UI re-renders in dark theme
-  And their preference is saved to the profile
-```
-
-Lint heuristics (enforced softly at `propose`, hard at `sync` in Sprint 3+):
-
-- Each scenario has one `Given`, one `When`, one `Then` (with optional `And`s).
-- `Then` uses an observable verb (displays, returns, stores, rejects, emails, …).
-- Reject "should work", "should be correct", "is successful" as `Then` predicates.
-- Reject tautological `Then` (paraphrase of the `When`).
-
-## ISO timestamps
-
-All `created` / `updated` / `synced` fields use ISO-8601 with timezone:
-
-```
-2026-05-17T14:30:00Z
-```
-
-## Sync markers
-
-Comments pushed to the PM tool are append-only and stamped:
-
-```
-<!-- SYNCED: 2026-05-17T14:30:00Z -->
-…progress narrative…
-```
-
-This lets re-syncs detect what's already been sent without duplicating.
+# Conventions
+
+These rules apply to every phase of OpenSpecPM. Read this before touching files.
+
+## Paths
+
+| Artifact | Path |
+|---|---|
+| Project config | `.openspecpm/config.json` (chosen adapter, repo/org/project identifiers) |
+| Project state | `.openspecpm/state.json` (not committed; idempotency hints) |
+| OpenSpec changes | `openspec/changes/<feature>/` (owned by OpenSpec) |
+| Proposal | `openspec/changes/<feature>/proposal.md` |
+| Design | `openspec/changes/<feature>/design.md` |
+| Tasks | `openspec/changes/<feature>/tasks.md` |
+| BDD specs | `openspec/changes/<feature>/specs/*.md` |
+| Progress (local) | `openspec/changes/<feature>/updates/<task-id>/progress.md` |
+| Archive | `openspec/archive/<YYYY-MM-DD>-<feature>/` (owned by OpenSpec) |
+
+The OpenSpec layout is authoritative — do not invent a parallel `.claude/...` tree. We sit *above* OpenSpec, not beside it.
+
+## Secrets
+
+Never write tokens to `.openspecpm/config.json`. Use environment variables:
+
+- GitHub: `gh auth login` handles the token; no env var needed.
+- Azure DevOps: `AZURE_DEVOPS_EXT_PAT` (Work Items: Read/Write).
+- Jira: `JIRA_EMAIL` + `JIRA_API_TOKEN`.
+- Linear: `LINEAR_API_KEY`.
+- GitLab: `GITLAB_TOKEN` (`api` scope).
+- LLM BDD judge (optional, opt-in via `--llm` or `judge.enabled` config): `ANTHROPIC_API_KEY`.
+
+## Frontmatter schemas
+
+All artifacts use YAML frontmatter. Required fields:
+
+### proposal.md
+
+```yaml
+---
+name: <feature-slug>
+status: draft | in_review | approved | shipped
+created: <ISO-8601 timestamp>
+schema_version: 1
+external:                          # filled by `openspecpm sync`
+  github:
+    adapter: github
+    id: "42"
+    url: https://github.com/.../issues/42
+---
+```
+
+### tasks.md
+
+```yaml
+---
+schema_version: 1
+items:
+  - title: "Implement X"
+    sync_state: pending | created | failed
+    external_id: "43"              # filled after sync
+    external_url: https://...
+    depends_on: []                  # task titles or external ids
+    parallel: true | false
+---
+```
+
+If `items:` is absent, OpenSpecPM falls back to parsing `- [ ] title` checklist lines in the body.
+
+## BDD format
+
+Scenarios in `specs/*.md` should use Gherkin-style triplets:
+
+```
+Scenario: User toggles dark mode
+  Given the user is signed in
+  And their theme preference is "system"
+  When they select "Dark" in the appearance menu
+  Then the UI re-renders in dark theme
+  And their preference is saved to the profile
+```
+
+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, …).
+- Reject "should work", "should be correct", "is successful" as `Then` predicates.
+- Reject tautological `Then` (paraphrase of the `When`).
+
+## ISO timestamps
+
+All `created` / `updated` / `synced` fields use ISO-8601 with timezone:
+
+```
+2026-05-17T14:30:00Z
+```
+
+## Sync markers
+
+Comments pushed to the PM tool are append-only and stamped:
+
+```
+<!-- SYNCED: 2026-05-17T14:30:00Z -->
+…progress narrative…
+```
+
+This lets re-syncs detect what's already been sent without duplicating.

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`.