feat(launch-goal): add /vault-cli:launch-goal command + sync canonical guides

[bborbe]

Summary

Adds /vault-cli:launch-goal — an interview-driven goal framing command — and syncs the canonical goal/task writing guides + creator + auditor with the principles distilled from two real dogfood runs in the Personal vault.

New command

/vault-cli:launch-goal is the rigorous front door beside create-goal's template fast-path. Six phases:

1. Understand — interview, one question per turn, includes "so that…" probe
2. Explore — 5 parallel semantic searches (theme, objective, duplicate, adjacent, examples) + hard duplicate-check gate
3. Frame — 3 parallel lens subagents (user-impact, system-state, theme-alignment) → top-3 outcome candidates → user picks (or counter-proposes)
4. Sharpen — derive Title, Success Criteria (evidence-shaped), DoD, Non-goals, Tasks (as [[Wikilinks]]), Impact (lead with verbatim "so that"); write file to disk with `status: draft` + show Obsidian link
5. Verify — 3 parallel forcing tests (Adversarial Laziness + outcome traceability + hedge-word grep)
6. Audit — fan-out to goal-auditor + graph-auditor + late dup-check; on 0 MAJOR, flip status: draft → in_progress; closing summary as clickable launchpad

Mirrors /launch-agent shape (interview → scaffold → checklist).

Guide sync

docs/goal-writing.md gains 5 sections:

• Tooling-Category Exception — artifact-shaped titles accepted when the artifact IS the deliverable (mirrors existing "Release Agent - Base" example, now named)
• Tasks as Business-Value Milestones — shippable improvements, not WBS slices; explicit decomposition hierarchy (Goal → linked Tasks → inline Subtasks); [[Wikilink]] format mandate; 1-8 soft cap NOT a floor
• Evidence Shape per Success Criterion — borrowed from dark-factory/docs/rules/spec-writing.md
• Adversarial Laziness Test — borrowed from same source
• Anti-pattern: soak-time DoD on personal-laptop tools — operator IS the runtime monitor; prefer exercise-now over time-based bake

docs/task-writing.md gains:

• Subtask Hierarchy — Goal → linked Tasks (wikilink files) → inline Subtasks (checkboxes in task file); subtasks are atomic, no separate files

agents/goal-creator.md — step 9 requires [[Wikilink]] format for tasks; step 12 audit greps bold-text task entries + soak-time DoD phrases.

agents/goal-auditor.md:

• Item 8 Tasks Quality — WARN flags for bold-text tasks (disables Obsidian auto-create-on-click) and WBS-shaped task titles (Implement/Define/Add/Refactor/Migrate); count clarified to 1-8 soft cap
• Item 12 DoD Quality — WARN flag for soak-time phrases on category: tooling goals

All new auditor flags are WARN, not MAJOR — soft introduction so existing goals aren't retroactively flagged as failing. Promote to MAJOR after a few weeks of canonical use without false positives.

Test plan

• Run `/vault-cli:launch-goal ""` in a Personal-vault session — full flow lands a goal file with all 9 required sections, evidence-shaped SCs, wikilink tasks
• Run `/vault-cli:audit-goal` on an older goal with bold-text tasks — confirm new WARN flags fire correctly
• Run `/vault-cli:audit-goal` on a goal with soak-time DoD — confirm WARN fires only on tooling-category, not on prod-service goals
• Verify the Personal-vault local override (`~/Documents/Obsidian/Personal/.claude/commands/launch-goal.md`) can be removed once this lands (replaced by the marketplace plugin version)
• `make precommit` passes (no Go changes, but version-alignment check still runs)

[ben-s-pull-request-reviewer]

Based on my analysis of the changed files, here is my review:

Code Review Findings

Must Fix (Critical)

None identified — the PR adds a new command and documentation updates; no security/correctness bugs in the new code.

Should Fix (Important)

1. commands/launch-goal.md — Phase 4 write has no collision guard

Phase 4 writes the goal file directly without checking for existing files. The duplicate-check gate in Phase 2 catches near-duplicate outcome overlaps but not filename collisions (e.g., two runs with slightly different casing or title variations that passed the sniff test but still collide). The goal-creator.md has explicit collision handling (step 10), but launch-goal.md Phase 4 does not.

The file is written to {goals_dir}/{Title}.md via the Write tool. If a goal with the same title already exists on disk, it will be silently overwritten.

Fix: Add a collision check before writing — read the target path and present AskUserQuestion with options to pick a different name or abort, matching goal-creator.md step 10 behavior.

---

2. agents/goal-auditor.md — Soak-time DoD WARN not scoped to category: tooling

Item 12 (Definition of Done Quality) says in the soak-time anti-pattern section:

"flag DoD checkboxes whose evidence is time-based bake… Don't flag on production-service goals (k8s, multi-user, trading hot path) — soak-time is appropriate there."

But the detection logic (grep for phrase patterns) has no category check. The agent would WARN on a goal whose DoD says "runs for 24h without incident" even if the goal is explicitly about a prod k8s service, contradicting the "don't flag on production-service goals" instruction.

The concern from the PR plan: "verify WARN not MAJOR and only fires on correct goal category" — the WARN/MAJOR part is correct, but the category scoping is not implemented.

---

Nice to Have (Optional)

3. commands/launch-goal.md — Test plan override path hardcoded

Phase 5 references:

~/Documents/Obsidian/Personal/.claude/commands/launch-goal.md

This path appears in the Phase 5 scope-check text but is not used in the actual verification logic. If a user has no local override at that path, there's no fallback behavior described. Either wire it up as an actual override mechanism or remove the reference.

---

4. docs/task-writing.md + docs/goal-writing.md — Evidence shape example uses vault-cli internal path

In goal-writing.md § Evidence Shape per Success Criterion:

- ✅ "After `/vault-cli:create-task`, `cat tasks/<id>.md` shows `phase: todo` in frontmatter"

This references an internal vault-cli path (tasks/<id>.md) that may not match the user's configured tasks_dir. Consider generalizing to "the task file exists in the vault's tasks directory with phase: todo in frontmatter."

---

Concerns Addressed (from PR plan)

Concern	Status
Phase 4 file write with status: draft — safe, no overwrites (but no collision check — see Should Fix #1)	⚠️ Partially addressed
Phase 5 parallel forcing tests — fan-out/fan-in pattern, errors don't cascade	✅ Addressed
Phase 6 audit fan-out + status flip on 0 MAJOR	✅ Addressed
goal-auditor.md WARN not MAJOR for bold-text tasks	✅ Addressed
goal-auditor.md WARN not MAJOR for soak-time DoD	⚠️ Correct severity, but category scoping missing (see Should Fix #2)
goal-creator.md wikilink format enforcement (step 9 + step 12 grep)	✅ Addressed
Test plan override path absent	⚠️ Reference present but not wired (see Nice to Have #3)

---

{
  "verdict": "request-changes",
  "summary": "PR adds a well-structured launch-goal command with proper fan-out/fan-in patterns and correct WARN/MAJOR severity separation in goal-auditor. Two issues need resolution: Phase 4 lacks filename collision protection before writing to disk, and the soak-time DoD WARN in goal-auditor is not scoped to tooling-category goals as the documentation promises.",
  "comments": [
    {
      "file": "commands/launch-goal.md",
      "line": 149,
      "severity": "major",
      "message": "Should Fix: Phase 4 file write has no collision guard. Unlike goal-creator.md step 10, launch-goal writes to {goals_dir}/{Title}.md without checking if the file already exists — silent overwrite risk. Add a pre-write collision check matching goal-creator's approach: on collision, AskUserQuestion to pick a different name or abort."
    },
    {
      "file": "agents/goal-auditor.md",
      "line": 124,
      "severity": "major",
      "message": "Should Fix: Soak-time DoD WARN is not scoped to category: tooling goals. The documentation says 'don't flag on production-service goals (k8s, multi-user, trading hot path)' but the grep-based detection has no category check — it would incorrectly WARN on a prod k8s goal. Either add a category check to the detection logic, or remove the 'don't flag on prod' carve-out from the documentation."
    },
    {
      "file": "commands/launch-goal.md",
      "line": 185,
      "severity": "nit",
      "message": "Nice to Have: Test plan references hardcoded path ~/Documents/Obsidian/Personal/.claude/commands/launch-goal.md but it's not wired as an actual override mechanism. Either implement the override or remove the reference to avoid misleading operators."
    },
    {
      "file": "docs/goal-writing.md",
      "line": 337,
      "severity": "nit",
      "message": "Nice to Have: Evidence shape example uses vault-cli internal path 'cat tasks/<id>.md' which may not match user's configured tasks_dir. Consider generalizing to 'the task file exists in the vault's tasks directory'."
    }
  ],
  "concerns_addressed": [
    "correctness: Phase 4 write safe (status:draft, no hardcoded path) but missing collision guard — raised as Should Fix #1",
    "correctness: Phase 5 parallel tests fan-out/fan-in, errors don't cascade — confirmed addressed",
    "correctness: Phase 6 audit fan-out + draft→in_progress flip on 0 MAJOR — confirmed addressed",
    "correctness: goal-auditor WARN for bold-text tasks — confirmed addressed",
    "correctness: goal-auditor WARN for soak-time DoD, severity correct but category scoping missing — raised as Should Fix #2",
    "correctness: goal-creator wikilink enforcement (step 9 + step 12 grep) — confirmed addressed",
    "tests: local override path reference present but not wired — raised as Nice to Have"
  ]
}

superseded by new automated review

[ben-s-pull-request-reviewer]

Based on my analysis, I can now produce the consolidated report. Here's my review:

---

PR Review: feat(launch-goal): add /vault-cli:launch-goal command + sync canonical guides

Changed Files (6 files, +503/-4 lines)

• CHANGELOG.md — +12 lines
• commands/launch-goal.md — new 276-line command
• agents/goal-auditor.md — +30 lines (WBS detection, soak-time DoD gate)
• agents/goal-creator.md — +4 lines (wikilink format, soak-time audit)
• docs/goal-writing.md — +154 lines (tooling exception, task milestones, evidence shape, laziness test, soak-time anti-pattern)
• docs/task-writing.md — +31 lines (subtask hierarchy)

---

Must Fix (Critical)

1. Version alignment violation — CHANGELOG vs plugin manifests

File	Value
CHANGELOG.md (top section)	## Unreleased
.claude-plugin/plugin.json	"version": "0.88.0"
.claude-plugin/marketplace.json (metadata)	"version": "0.88.0"
.claude-plugin/marketplace.json (plugins[0])	"version": "0.88.0"

The top changelog section says Unreleased while all three plugin JSON fields say 0.88.0. Per CLAUDE.md § Version Alignment, all four MUST equal. make precommit runs check-versions which will fail this. The CHANGELOG ## Unreleased section needs a version header (## v0.88.0) or the plugin manifests need to be bumped to the next patch/minor.

---

Should Fix (Important)

None identified from this diff.

---

Nice to Have (Optional)

1. Phase 6 fan-out agent name — confirm vault-cli: prefix resolves

In commands/launch-goal.md:321, the audit fan-out references:

Task(subagent_type: "vault-cli:graph-auditor", ...)
Task(subagent_type: "vault-cli:goal-auditor", ...)

The agents are defined with name: graph-auditor and name: goal-auditor. The vault-cli: prefix is presumably a namespace convention — verify this prefix resolves correctly at runtime (i.e., the Task subagent dispatcher strips the prefix to match the agent name). If the prefix doesn't resolve, these fan-out calls will silently fail and the Phase 6 audit will run without the graph-auditor or goal-auditor subagents.

---

Concerns from Plan — Status

Concern	File	Verdict
Phase 2/3/5/6 fan-out concurrency limits	commands/launch-goal.md	Not a concern — appropriate for agent-based workflow; no fixed thread pool exhaustion risk
Phase 5 scope check ratio ≤2.5× logic	commands/launch-goal.md	Not a concern — correctly implemented
Phase 4 filename collision Glob pattern	commands/launch-goal.md	Not a concern — standard path-based Glob
Phase 3/5 mcp__semantic-search__search_related injection risk	commands/launch-goal.md	Not a concern — tool is in allowed-tools; search queries constructed from user-provided rough idea are low-risk
Soak-time DoD two-step gate (category + grep)	agents/goal-auditor.md	Not a concern — correctly implemented with case-insensitive substring matching
WBS detection pattern (≥3 leading-verb tasks)	agents/goal-auditor.md	Not a concern — correctly implemented
Bold-text task grep pattern	agents/goal-creator.md	Not a concern — grep -E '^\\s*[0-9]+\\.\\s+\\*\\*[^[]' correctly identifies 1. **Task** but not 1. [[Task]]
Tooling-Category Exception edge cases	docs/goal-writing.md	Not a concern — rule clearly distinguishes artifact-as-outcome from tool-as-means
Tasks as Business-Value Milestones consistency with task-writing	docs/goal-writing.md + docs/task-writing.md	Not a concern — both docs consistently define Goal → linked Tasks → inline Subtasks hierarchy
Evidence Shape per SC examples	docs/goal-writing.md	Not a concern — examples properly scoped with metric naming conventions
Test coverage for new command	commands/launch-goal.md	Not applicable — this is a Claude agent/command implementation, not compiled code; no unit test harness for slash commands
Subtask Hierarchy consistency with wikilink requirement	docs/task-writing.md + docs/goal-writing.md	Not a concern — both docs are consistent; wikilinks are for goal-level tasks, checkboxes for inline subtasks

---

Selector Mode Traceability

• ast-grep-runner: not available in this environment (ast-grep binary found at /usr/bin/ast-grep but ast-grep-runner.sh script not accessible from allowed working directories) — skipped per Step 4.0 fail-fast
• Judgment rules: diff touches only markdown docs (commands/, agents/, docs/) — no Go/Python source files, no Makefiles, no LICENSE files; no judgment rules are triggered by this diff scope
• Context-specific conventions: none applicable (no .env, k8s/, main.go touched)

---

Verdict JSON

{
  "verdict": "request-changes",
  "summary": "PR adds a comprehensive launch-goal command with strong documentation hygiene. One blocking issue: version alignment violation — CHANGELOG.md top section is 'Unreleased' while all three plugin JSON fields say '0.88.0'; make precommit check-versions will fail. All technical concerns from the plan (fan-out concurrency, scope ratio, soak-time gate, grep patterns, tooling exception edge cases) are correctly implemented.",
  "comments": [
    {
      "file": "CHANGELOG.md",
      "line": 11,
      "severity": "critical",
      "message": "Must Fix: Top section reads '## Unreleased' but plugin manifests (plugin.json, marketplace.json) both say version '0.88.0'. Per CLAUDE.md Version Alignment rules, all four version strings must match. Either rename '## Unreleased' to '## v0.88.0' or bump the plugin manifests to the next patch. Run 'make precommit' to confirm."
    },
    {
      "file": "commands/launch-goal.md",
      "line": 321,
      "severity": "minor",
      "message": "Nice to Have: Phase 6 audit fan-out calls Task(subagent_type: 'vault-cli:graph-auditor', ...) and Task(subagent_type: 'vault-cli:goal-auditor', ...). Confirm the 'vault-cli:' prefix resolves to the agent names ('graph-auditor', 'goal-auditor') defined in agents/. If the prefix doesn't resolve, these subagents silently fail and the audit runs without them."
    }
  ],
  "concerns_addressed": [
    "correctness: Phase 2 dup-check gate — hard gate correctly implemented with AskUserQuestion and 3 options (extend/separate/abort)",
    "correctness: Phase 5 scope check ratio ≤2.5× — logic correctly implemented",
    "correctness: Phase 4 filename collision via Glob — standard path-based Glob handles titles correctly",
    "security: mcp__semantic-search__search_related in fan-out — tool is in allowed-tools; user rough-idea queries are low injection risk",
    "correctness: soak-time DoD two-step gate (category + grep) — case-insensitive substring matching correctly implemented",
    "correctness: WBS-shaped task detection (≥3 leading-verb) — pattern correctly identifies Implement/Define/Add(noun)/Refactor/Migrate/Wire/Configure",
    "correctness: bold-text task grep — grep -E '^\\s*[0-9]+\\.\\s+\\*\\*[^[]' correctly identifies '1. **Task**' but not '1. [[Task]]'",
    "correctness: Tooling-Category Exception — rule clearly distinguishes artifact-as-outcome from tool-as-means; no edge-case ambiguity in practice",
    "correctness: Tasks as Business-Value Milestones consistency — docs/goal-writing.md and docs/task-writing.md consistently define Goal → linked Tasks → inline Subtasks hierarchy",
    "correctness: Evidence Shape per SC — examples properly scoped with metric naming (foo_total{label=x})",
    "tests: no test files for new command — not applicable for Claude agent/slash command implementation (no unit test harness for markdown commands)",
    "correctness: Subtask Hierarchy + wikilink consistency — task-writing.md correctly distinguishes wikilinks (goal-level) from checkboxes (inline subtasks)"
  ]
}