@chief-clancy/brief 0.2.0 → 0.3.0

package/README.md

@@ -52,15 +52,36 @@ Briefs are saved to `.clancy/briefs/` in your project.
 
 ## Board ticket mode (optional)
 
-To brief from board tickets and push approved briefs back to the board without installing the full pipeline:
+To brief from board tickets without installing the full pipeline:
 
 1. Run `/clancy:board-setup` in Claude Code
 2. Follow the prompts to configure your board credentials
-3. Run `/clancy:brief #42` (or your board's ticket format) to brief from an existing ticket
-4. Run `/clancy:approve-brief <slug>` to convert an approved brief into child tickets on your board (creates one ticket per row in the brief's decomposition table, links dependencies, and posts a tracking summary)
+3. Run `/clancy:brief #42` (or your board's ticket format)
 
 Credentials are stored in `.clancy/.env` and are per-project (not global).
 
+Supported boards: Jira, GitHub Issues, Linear, Shortcut, Notion, Azure DevOps.
+
+## Approving briefs
+
+The brief package ships `/clancy:approve-brief` so the approval gate works without the full pipeline. The behaviour depends on the install mode.
+
+### Standalone (no board)
+
+`/clancy:approve-brief` requires board credentials. Approve-brief's job is to create child tickets ON the board, so without a board there is nothing for it to do. Run `/clancy:board-setup` first to configure your board, then re-run `/clancy:approve-brief`.
+
+### Standalone+board (board credentials but no full pipeline)
+
+`/clancy:approve-brief <slug>` walks the brief's decomposition table, creates one child ticket per row on the board (in topological/dependency order), links dependencies, and posts a tracking summary as a comment on the parent ticket. Each child ticket gets a pipeline label so downstream queue commands (`/clancy:plan`, `/clancy:implement`) know which queue picks it up.
+
+In standalone+board mode, child tickets default to `CLANCY_LABEL_PLAN` (default `clancy:plan`), even though `CLANCY_ROLES` is unset — passing `--skip-plan` overrides this and forces `CLANCY_LABEL_BUILD` (default `clancy:build`) instead. This is the **single-source-of-truth pipeline label rule**: standalone+board users have installed both `@chief-clancy/brief` and `@chief-clancy/plan` as standalone packages and clearly intend to use plan, so the workflow defaults to the planning queue rather than the build queue.
+
+Partial failures stop immediately. The brief file's approve marker tracks which rows already shipped to the board, so re-running `/clancy:approve-brief` resumes from where the previous run stopped — it never duplicates a ticket.
+
+### Terminal mode (full pipeline)
+
+Existing behaviour, unchanged. The pipeline label respects `CLANCY_ROLES`: if `planner` is enabled (or `CLANCY_ROLES` is unset, indicating a global install), child tickets get `CLANCY_LABEL_PLAN`; if `planner` is explicitly excluded, child tickets get `CLANCY_LABEL_BUILD` (the terminal user has opted out of the planning queue). The `--skip-plan` flag overrides both and forces the build label.
+
 ## Full pipeline
 
 `@chief-clancy/brief` covers brief generation and ticket creation from briefs. For planning and the full development pipeline (autopilot, implementation, review), install the complete Clancy package:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chief-clancy/brief",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Strategic brief generator for Claude Code — grill, decompose, and document feature ideas",
   "author": "Alex Clapperton",
   "license": "MIT",

package/src/workflows/approve-brief.md

@@ -8,39 +8,60 @@ Approve a reviewed strategic brief by creating child tickets on the board, linki
 
 ## Step 1 — Preflight checks
 
-1. Check `.clancy/` exists and `.clancy/.env` is present. If not:
+### 1. Detect installation context
 
-   ```
-   .clancy/ not found. Run /clancy:init to set up Clancy first.
-   ```
+Check for `.clancy/.env`:
 
-   Stop.
+- **Absent** → **standalone mode**. The brief package has been installed via `npx @chief-clancy/brief` but board credentials have never been configured. There is nothing approve-brief can do without a board (its job is to create tickets ON the board), so stop with:
 
-2. Source `.clancy/.env` and check board credentials are present.
+  ```
+  No board credentials found. Run /clancy:board-setup first to configure your board, then re-run /clancy:approve-brief.
+  ```
 
-3. Check `CLANCY_ROLES` includes `strategist` (or env var is unset, which indicates a global install where all roles are available). If `CLANCY_ROLES` is set but does not include `strategist`:
+  Stop.
 
-   ```
-   The Strategist role is not enabled. Add "strategist" to CLANCY_ROLES in .clancy/.env or run /clancy:settings.
-   ```
+- **Present** → continue to `.clancy/clancy-implement.js` check below.
 
-   Stop.
+If `.clancy/.env` is present, check for `.clancy/clancy-implement.js`:
 
-4. Branch freshness check:
+- **Present** → **terminal mode**. Full Clancy pipeline installed.
+- **Absent** → **standalone+board mode**. Board credentials available via `/clancy:board-setup`. Brief and plan are installed as standalone packages but the full pipeline (`clancy-implement.js`) is not.
 
-   ```bash
-   git fetch origin
-   ```
+The detected install mode is captured for Step 6's pipeline label decision.
 
-   Compare HEAD with `origin/$CLANCY_BASE_BRANCH`. If behind:
+### 2. Terminal-mode preflight (skip in standalone+board mode)
 
-   **AFK mode** (`--afk` flag or `CLANCY_MODE=afk`): auto-pull without prompting.
+If in **terminal mode** (`.clancy/.env` present AND `.clancy/clancy-implement.js` present):
 
-   **Interactive mode:**
+a. Source `.clancy/.env` and check board credentials are present.
 
-   ```
-   Behind by N commits. [1] Pull latest  [2] Continue  [3] Abort
-   ```
+b. Check `CLANCY_ROLES` includes `strategist` (or env var is unset, which indicates a global install where all roles are available). If `CLANCY_ROLES` is set but does not include `strategist`:
+
+```
+The Strategist role is not enabled. Add "strategist" to CLANCY_ROLES in .clancy/.env or run /clancy:settings.
+```
+
+Stop.
+
+### 3. Standalone+board preflight (only in standalone+board mode)
+
+If in **standalone+board mode**, source `.clancy/.env` and check board credentials are present (same presence check as the terminal-mode preflight above — an empty or partial `.clancy/.env` should fail loudly here, not later in Step 6/7). Standalone+board users came in via `npx @chief-clancy/brief` and `/clancy:board-setup`, so they have no `CLANCY_ROLES` configured and the strategist role check above does not apply.
+
+### 4. Branch freshness check (all modes)
+
+```bash
+git fetch origin
+```
+
+Compare HEAD with `origin/$CLANCY_BASE_BRANCH`. If behind:
+
+**AFK mode** (`--afk` flag or `CLANCY_MODE=afk`): auto-pull without prompting.
+
+**Interactive mode:**
+
+```
+Behind by N commits. [1] Pull latest  [2] Continue  [3] Abort
+```
 
 ---
 
@@ -298,14 +319,20 @@ Continue — omit parent fields from creation payloads. No tracking comment will
 
 Platform-specific pre-creation lookups.
 
-### GitHub
+### Pipeline label selection rule (applies to all six platforms below)
+
+Every child ticket gets exactly one pipeline label. The label determines which queue picks the ticket up downstream (`/clancy:plan` for the planning queue, `/clancy:implement` for the build queue). The selection rule, in order of precedence:
 
-**Pipeline label for children — this is mandatory, always apply a pipeline label to every child ticket.** Determine which label to use:
+1. `--skip-plan` flag is set → use `CLANCY_LABEL_BUILD` from `.clancy/.env` if set, otherwise `clancy:build`. The user has explicitly opted out of the planning queue for this run.
+2. Install mode is **standalone+board** (Step 1 detected this) → use `CLANCY_LABEL_PLAN` from `.clancy/.env` if set, otherwise `clancy:plan`. Standalone+board users have installed both `@chief-clancy/brief` and `@chief-clancy/plan` as standalone packages and clearly intend to use plan, even though they have no `CLANCY_ROLES` configured.
+3. Install mode is **terminal** AND `CLANCY_ROLES` includes `planner` (or `CLANCY_ROLES` is unset, indicating a global install where all roles are available) → use `CLANCY_LABEL_PLAN` from `.clancy/.env` if set, otherwise `clancy:plan`.
+4. Install mode is **terminal** AND `CLANCY_ROLES` is set but does NOT include `planner` → use `CLANCY_LABEL_BUILD` from `.clancy/.env` if set, otherwise `clancy:build`. The terminal user has explicitly opted out of the planning queue by not enabling the planner role.
+
+This rule replaces the per-platform fallthrough that used to live in each of the six platform subsections below. Each subsection now applies the rule rather than re-enumerating it. Apply the chosen label to each child ticket, creating it first only on platforms that require explicit label creation (the per-platform subsections below document which platforms auto-create vs require pre-creation).
+
+### GitHub
 
-- `--skip-plan` flag → use `CLANCY_LABEL_BUILD` from `.clancy/.env` if set, otherwise `clancy:build`
-- Planner role enabled (`CLANCY_ROLES` includes `planner`) → use `CLANCY_LABEL_PLAN` from `.clancy/.env` if set, otherwise `clancy:plan`
-- Planner role NOT enabled → use `CLANCY_LABEL_BUILD` from `.clancy/.env` if set, otherwise `clancy:build`
-  Ensure the label exists on the board (create it if missing), then add it to each child ticket.
+**Pipeline label for children — mandatory.** Apply the pipeline label per the rule above to every child ticket.
 
 **Labels to apply per ticket:**
 
@@ -362,7 +389,7 @@ Set CLANCY_BRIEF_ISSUE_TYPE in .clancy/.env.
 
 Stop.
 
-**Pipeline label for children — mandatory, same logic as GitHub.** Use `CLANCY_LABEL_PLAN` or `CLANCY_LABEL_BUILD` from `.clancy/.env` (defaults: `clancy:plan` / `clancy:build`). Always apply to every child ticket.
+**Pipeline label for children — mandatory.** Apply the pipeline label per the rule at the top of Step 6. Defaults: `clancy:plan` / `clancy:build`. Always apply to every child ticket.
 
 **Labels:** Jira auto-creates labels — no pre-creation needed. Apply: the pipeline label determined above, `clancy:afk` or `clancy:hitl`. `CLANCY_LABEL` is NOT applied to children when pipeline labels are active.
 
@@ -404,7 +431,7 @@ query {
 }
 ```
 
-**Pipeline label for children — mandatory, same logic as GitHub/Jira.** Use `CLANCY_LABEL_PLAN` or `CLANCY_LABEL_BUILD` from `.clancy/.env` (defaults: `clancy:plan` / `clancy:build`). Always apply to every child ticket.
+**Pipeline label for children — mandatory.** Apply the pipeline label per the rule at the top of Step 6. Defaults: `clancy:plan` / `clancy:build`. Always apply to every child ticket.
 
 For each required label (the pipeline label, `component:{CLANCY_COMPONENT}`, `clancy:afk`, `clancy:hitl`): search by exact name. `CLANCY_LABEL` is NOT applied to children when pipeline labels are active. If not found in team labels, check workspace labels:
 
@@ -448,7 +475,7 @@ curl -s \
 
 If the specified type is not found, stop with the available types listed.
 
-**Pipeline tag for children — mandatory, same logic as other boards.** Use `CLANCY_LABEL_PLAN` or `CLANCY_LABEL_BUILD` from `.clancy/.env` (defaults: `clancy:plan` / `clancy:build`). Tags are applied via the `System.Tags` field (semicolon-delimited).
+**Pipeline tag for children — mandatory.** Apply the pipeline tag determined by the rule at the top of Step 6. Defaults: `clancy:plan` / `clancy:build`. Tags are applied via the `System.Tags` field (semicolon-delimited).
 
 **Tags:** Azure DevOps auto-creates tags — no pre-creation needed. Apply: the pipeline tag, `clancy:afk` or `clancy:hitl`. `CLANCY_LABEL` is NOT applied to children when pipeline tags are active.
 
@@ -467,7 +494,7 @@ Use `authenticatedUser.providerDisplayName` for the `System.AssignedTo` field.
 
 **Story type:** Shortcut creates stories by default. Use `story_type` field if needed (`feature`, `bug`, `chore` — default: `feature`).
 
-**Pipeline label for children — mandatory, same logic as other boards.** Use `CLANCY_LABEL_PLAN` or `CLANCY_LABEL_BUILD` from `.clancy/.env` (defaults: `clancy:plan` / `clancy:build`).
+**Pipeline label for children — mandatory.** Apply the pipeline label per the rule at the top of Step 6. Defaults: `clancy:plan` / `clancy:build`.
 
 **Labels:** Resolve label IDs via `GET /api/v3/labels`. If the required label does not exist, create it:
 
@@ -494,7 +521,7 @@ Use `id` as the `owner_ids` value for story creation.
 
 ### Notion
 
-**Pipeline label for children — mandatory, same logic as other boards.** Use `CLANCY_LABEL_PLAN` or `CLANCY_LABEL_BUILD` from `.clancy/.env` (defaults: `clancy:plan` / `clancy:build`). Labels are applied via multi-select properties.
+**Pipeline label for children — mandatory.** Apply the pipeline label per the rule at the top of Step 6. Defaults: `clancy:plan` / `clancy:build`. Labels are applied via multi-select properties.
 
 **Labels:** Notion auto-creates multi-select options when first used — no pre-creation needed. Apply: the pipeline label, `clancy:afk` or `clancy:hitl`. `CLANCY_LABEL` is NOT applied to children when pipeline labels are active.
 

package/src/workflows/workflows.test.ts

@@ -55,6 +55,204 @@ describe('workflows directory structure', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// approve-brief Step 1 install-mode preflight assertions
+// ---------------------------------------------------------------------------
+
+describe('approve-brief Step 1 install-mode preflight', () => {
+  const content = readFileSync(
+    new URL('approve-brief.md', import.meta.url),
+    'utf8',
+  );
+
+  it('detects three installation states', () => {
+    expect(content).toContain('standalone mode');
+    expect(content).toContain('standalone+board mode');
+    expect(content).toContain('terminal mode');
+  });
+
+  it('uses the same env-var probes as approve-plan and plan workflows', () => {
+    // Schema-pair contract: must mirror approve-plan.md and plan.md exactly.
+    expect(content).toContain('.clancy/.env');
+    expect(content).toContain('.clancy/clancy-implement.js');
+  });
+
+  it('hard-stops in standalone mode with the board-setup message', () => {
+    expect(content).toContain('No board credentials found');
+    expect(content).toContain('Run /clancy:board-setup first');
+  });
+
+  it('does NOT use the old /clancy:init standalone hard-stop', () => {
+    expect(content).not.toContain('Run /clancy:init to set up Clancy first');
+  });
+
+  it('terminal-mode preflight gates the strategist role check', () => {
+    expect(content).toContain(
+      '### 2. Terminal-mode preflight (skip in standalone+board mode)',
+    );
+    expect(content).toContain('CLANCY_ROLES` includes `strategist`');
+  });
+
+  it('standalone+board preflight notes the strategist role check does not apply', () => {
+    expect(content).toContain(
+      '### 3. Standalone+board preflight (only in standalone+board mode)',
+    );
+    expect(content).toContain('strategist role check above does not apply');
+  });
+
+  it('captures the install mode for Step 6 to read', () => {
+    expect(content).toContain(
+      "The detected install mode is captured for Step 6's pipeline label decision",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// approve-brief Step 6 pipeline label selection rule
+// ---------------------------------------------------------------------------
+
+describe('approve-brief Step 6 pipeline label selection rule', () => {
+  const content = readFileSync(
+    new URL('approve-brief.md', import.meta.url),
+    'utf8',
+  );
+
+  it('has the preamble heading at the top of Step 6', () => {
+    expect(content).toContain(
+      '### Pipeline label selection rule (applies to all six platforms below)',
+    );
+  });
+
+  it('preamble enumerates rule 1 — --skip-plan flag uses build label', () => {
+    expect(content).toMatch(
+      /1\. `--skip-plan` flag is set → use `CLANCY_LABEL_BUILD`/,
+    );
+  });
+
+  it('preamble enumerates rule 2 — standalone+board uses plan label', () => {
+    expect(content).toMatch(
+      /2\. Install mode is \*\*standalone\+board\*\*[^\n]*→ use `CLANCY_LABEL_PLAN`/,
+    );
+  });
+
+  it('preamble enumerates rule 3 — terminal + planner enabled uses plan label', () => {
+    expect(content).toMatch(
+      /3\. Install mode is \*\*terminal\*\* AND `CLANCY_ROLES` includes `planner`[^\n]*→ use `CLANCY_LABEL_PLAN`/,
+    );
+  });
+
+  it('preamble enumerates rule 4 — terminal + planner not enabled uses build label', () => {
+    expect(content).toMatch(
+      /4\. Install mode is \*\*terminal\*\* AND `CLANCY_ROLES` is set but does NOT include `planner` → use `CLANCY_LABEL_BUILD`/,
+    );
+  });
+
+  it('GitHub subsection delegates to the preamble (no inline 3-rule fallthrough)', () => {
+    expect(content).toContain(
+      'Apply the pipeline label per the rule above to every child ticket',
+    );
+    // The old per-platform fallthrough must be gone — no leftover
+    // "Planner role enabled" / "Planner role NOT enabled" lines anywhere.
+    expect(content).not.toContain('Planner role enabled');
+    expect(content).not.toContain('Planner role NOT enabled');
+  });
+
+  it('all five non-GitHub platform subsections delegate to the preamble', () => {
+    // Each non-GitHub platform must reference the preamble explicitly
+    // and must NOT use the old "same logic as GitHub/other boards" wording.
+    expect(content).not.toContain('same logic as GitHub');
+    expect(content).not.toContain('same logic as other boards');
+
+    // GitHub uses "above"; the other 5 use "at the top of Step 6". Of those
+    // 5, four are "pipeline label per the rule" (Jira, Linear, Shortcut,
+    // Notion) and one is "pipeline tag determined by the rule" (Azure
+    // DevOps, which uses System.Tags rather than labels).
+    const labelDelegations = content.match(
+      /Apply the pipeline label per the rule at the top of Step 6/g,
+    );
+    const tagDelegations = content.match(
+      /Apply the pipeline tag determined by the rule at the top of Step 6/g,
+    );
+
+    expect(labelDelegations).not.toBeNull();
+    expect(labelDelegations?.length).toBe(4);
+    expect(tagDelegations).not.toBeNull();
+    expect(tagDelegations?.length).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// approve-brief test permissiveness audit
+// ---------------------------------------------------------------------------
+
+describe('approve-brief test regex permissiveness audit', () => {
+  // These tests guard against the `\\?d` class of trap from
+  // feedback_workflow_md_gotchas.md by walking through the simplest wrong
+  // inputs that the regexes above SHOULD reject.
+  const content = readFileSync(
+    new URL('approve-brief.md', import.meta.url),
+    'utf8',
+  );
+
+  /**
+   * Slice the workflow content between two literal markers, asserting both
+   * markers are present AND the end marker comes after the start marker.
+   * Without these guards a missing marker would return -1 from indexOf,
+   * which slice() interprets as a negative index — that produces a
+   * substring counted from the END of the file and silently passes
+   * (or silently fails) the body assertions for the wrong reason. Per
+   * Copilot finding on PR #222 + the test permissiveness audit discipline.
+   */
+  const sliceBetween = (start: string, end: string): string => {
+    const startIdx = content.indexOf(start);
+    const endIdx = content.indexOf(end);
+
+    expect(startIdx, `start marker not found: ${start}`).toBeGreaterThanOrEqual(
+      0,
+    );
+    expect(endIdx, `end marker not found: ${end}`).toBeGreaterThanOrEqual(0);
+    expect(endIdx, `end marker before start marker`).toBeGreaterThan(startIdx);
+
+    return content.slice(startIdx, endIdx);
+  };
+
+  it('rule-2 body does NOT contain a swapped label', () => {
+    // Sanity check: rule 2 must reference CLANCY_LABEL_PLAN, not _BUILD.
+    // If someone accidentally swapped the labels in the preamble, the
+    // existing rule-2 assertion above would still match the heading; this
+    // assertion makes the swap fail loudly.
+    const rule2ToRule3 = sliceBetween(
+      '2. Install mode is **standalone+board**',
+      '3. Install mode is **terminal** AND `CLANCY_ROLES` includes `planner`',
+    );
+
+    expect(rule2ToRule3).not.toContain('CLANCY_LABEL_BUILD');
+  });
+
+  it('rule-3 body does NOT contain a swapped label', () => {
+    // Symmetric to rule-2 / rule-4. Rule 3 must reference CLANCY_LABEL_PLAN.
+    const rule3ToRule4 = sliceBetween(
+      '3. Install mode is **terminal** AND `CLANCY_ROLES` includes `planner`',
+      '4. Install mode is **terminal** AND `CLANCY_ROLES` is set but does NOT include `planner`',
+    );
+
+    expect(rule3ToRule4).not.toContain('CLANCY_LABEL_BUILD');
+  });
+
+  it('rule-4 body does NOT contain a swapped label', () => {
+    // Symmetric to the rule-2 check: rule 4 must reference
+    // CLANCY_LABEL_BUILD, not _PLAN. Slice from rule-4 to the rule-block
+    // terminator paragraph (the "This rule replaces..." line that follows
+    // rule 4 in the preamble).
+    const rule4ToTerminator = sliceBetween(
+      '4. Install mode is **terminal** AND `CLANCY_ROLES` is set but does NOT include `planner`',
+      'This rule replaces the per-platform fallthrough',
+    );
+
+    expect(rule4ToTerminator).not.toContain('CLANCY_LABEL_PLAN');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // board-setup.md content assertions
 // ---------------------------------------------------------------------------