@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/skills/lisa-setup-automations/scripts/generate-workflow.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * Generate the GitHub Actions workflow that fires a registered automation loop.
+ *
+ * Once `executionEnv` exists, a scheduled loop is a thin dispatcher: it wakes,
+ * picks eligible work, submits it to a remote surface, records the identifier,
+ * and exits. The heavy lifting happens elsewhere. That makes the clock's job
+ * cheap and boring, and the requirements on it are availability rather than
+ * power.
+ *
+ * The workflow is generated from `.lisa.config.json` rather than hand-written,
+ * so config stays the source of truth and swapping the scheduler later is a
+ * config change instead of a rewrite.
+ *
+ * Usage:
+ *   generate-workflow.mjs <loop-name> [--write]
+ * @module generate-workflow
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  realpathSync,
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+/** Where a generated loop workflow lands. */
+export const workflowPath = name =>
+  join(".github", "workflows", `lisa-${name}.yml`);
+
+/**
+ * Read one automation's declaration.
+ * @param {string} name Loop name.
+ * @param {string} [cwd] Repository root.
+ * @returns {object} The loop's configuration.
+ */
+export function readAutomation(name, cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) throw new Error(".lisa.config.json is missing");
+  const cfg = JSON.parse(readFileSync(path, "utf8"));
+  const loop = cfg.automations?.[name];
+  if (!loop) {
+    throw new Error(
+      `no automations["${name}"] in .lisa.config.json.\n` +
+        `Declare the loop before generating its workflow.`
+    );
+  }
+  const surface = cfg.remoteEnv?.surfaces?.[loop.executionEnv];
+  const github = cfg.github ?? {};
+  return {
+    ...loop,
+    // Only used for the fork guard, so it is a question about *this* repository
+    // rather than about the surface. Read from the surface where one records it
+    // — Codex Cloud binds an environment to a repository — and otherwise from
+    // the project's own GitHub config. A Claude cloud environment binds no
+    // repository at all, and demanding one there asked for a field that cannot
+    // exist, which refused to generate a workflow for a correctly configured
+    // loop.
+    repository:
+      surface?.repository ??
+      (github.org && github.repo ? `${github.org}/${github.repo}` : undefined),
+    // Where this project keeps its bootstrap. A workstation serving several
+    // tenants gives each its own name, so the generated workflow must template
+    // it rather than assume the default.
+    bootstrapKey: cfg.secrets?.bootstrap?.key ?? "BWS_ACCESS_TOKEN",
+  };
+}
+
+/**
+ * Emit shell that locates a Lisa skill script before running it.
+ *
+ * A hardcoded `.claude/skills/...` path is wrong in exactly the place this
+ * workflow runs. Claude and Codex receive Lisa skills as an installed plugin
+ * living in the user's home directory, which is emphatically not part of a
+ * clone — and a scheduled run is always a fresh clone with no plugin install.
+ * So the one path that reliably exists on a runner is the npm package, at the
+ * version the project pins, which is the version its automation should run.
+ *
+ * The same candidate list the remote-env entrypoint uses, for the same reason:
+ * the in-checkout copies are cheapest and need nothing installed, and
+ * `node_modules` is the fallback that makes the plugin-delivered harnesses work
+ * at all.
+ * @param {string} skill Skill slug that owns the script.
+ * @param {string} script Script filename.
+ * @param {string[]} args Arguments appended to the invocation, one per line.
+ * @returns {string} Shell, indented for a workflow `run:` block.
+ */
+function runSkillScript(skill, script, args) {
+  const candidates = [
+    `.claude/skills/${skill}/scripts/${script}`,
+    `.agents/skills/${skill}/scripts/${script}`,
+    `.codex/skills/${skill}/scripts/${script}`,
+    `node_modules/@codyswann/lisa/plugins/lisa/skills/${skill}/scripts/${script}`,
+  ]
+    .map(candidate => `            "${candidate}"`)
+    .join(" \\\n");
+  const tail = args.map(arg => `            ${arg}`).join(" \\\n");
+  return `          runner=""
+          for candidate in \\
+${candidates}; do
+            if [ -f "$candidate" ]; then runner="$candidate"; break; fi
+          done
+          if [ -z "$runner" ]; then
+            echo "cannot find ${skill}/scripts/${script}" >&2
+            echo "Checked the agent skill directories and node_modules." >&2
+            echo "Lisa skills reach Claude and Codex as an installed plugin," >&2
+            echo "so node_modules is the only copy a runner ever has." >&2
+            exit 1
+          fi
+          node "$runner" \\
+${tail}`;
+}
+
+/**
+ * Render the workflow YAML for one loop.
+ *
+ * Three choices here are load-bearing rather than stylistic.
+ *
+ * The `schedule` trigger is emitted **only when the loop is enabled**. A
+ * recurring trigger goes live after the exact production path has been proven
+ * once for one real item, so registration writes a manually-dispatchable
+ * workflow and enabling adds the clock.
+ *
+ * The concurrency group **never cancels in progress**. Cancelling could kill a
+ * dispatch after the remote accepted a task but before its identifier was
+ * recorded, which orphans irreversible work — nothing left to reconcile against,
+ * and a retry that duplicates it.
+ *
+ * The bootstrap credential is asserted **before** anything is installed, so a
+ * misconfigured secret fails in seconds rather than after a toolchain download.
+ * @param {string} name Loop name.
+ * @param {object} loop Loop configuration.
+ * @returns {string} Workflow YAML.
+ */
+export function renderWorkflow(name, loop) {
+  if (!loop.schedule) throw new Error(`automations["${name}"] has no schedule`);
+  // The repository secret and the environment variable carry the same name, so
+  // the value the workflow exports is the one `bootstrap.key` tells the resolver
+  // to look for. Translating it to the provider CLI's own variable is
+  // providers.mjs's job, not this workflow's.
+  const bootstrap = loop.bootstrapKey ?? "BWS_ACCESS_TOKEN";
+  if (!loop.repository) {
+    throw new Error(
+      `cannot determine which repository this loop belongs to.\n` +
+        `The generated workflow guards on it so a fork never dispatches. Set ` +
+        `github.org and github.repo in .lisa.config.json.`
+    );
+  }
+
+  // Always emitted, even for a surface whose dispatcher token is not consumed
+  // by use. Making it conditional on secrets.rotating would mean a project that
+  // later declares one, without regenerating its workflow, silently loses the
+  // persist step and strands the replacement. One inert step is the cheaper
+  // failure.
+  const rotation = `
+      # The dispatcher authenticates with a credential that rotates on use, so
+      # the replacement must be persisted even when the dispatch itself failed.
+      - name: Persist any credential rotation
+        if: \${{ always() }}
+        env:
+          ${bootstrap}: \${{ secrets.${bootstrap} }}
+        run: |
+          set -euo pipefail
+${runSkillScript("lisa-secrets-access", "rotate-secret.mjs", ["leases"])}`;
+
+  const trigger = loop.enabled
+    ? `  schedule:\n    - cron: '${loop.schedule}'\n  workflow_dispatch:`
+    : `  # schedule: disabled until the production path is proven once for one\n` +
+      `  # real item. Enabling adds:  - cron: '${loop.schedule}'\n  workflow_dispatch:`;
+
+  return `# Generated by lisa-setup-automations from .lisa.config.json.
+# Edit the config and regenerate; hand edits are overwritten.
+name: 🔁 Lisa ${name}
+
+on:
+${trigger}
+
+# Never cancel in progress. A cancelled dispatch can leave a remote task that
+# was accepted but whose identifier was never recorded — irreversible work with
+# nothing to reconcile against, where a retry duplicates it.
+concurrency:
+  group: lisa-${name}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  dispatch:
+    name: Dispatch one ${name} cycle
+    if: github.repository == '${loop.repository}'
+    runs-on: ubuntu-latest
+    timeout-minutes: ${loop.timeoutMinutes ?? 15}
+    env:
+      LISA_SECRETS_SURFACE: github-actions
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      # Assert first, install second: a misconfigured bootstrap should fail in
+      # seconds rather than after a toolchain download.
+      - name: Check the bootstrap credential is configured
+        env:
+          ${bootstrap}: \${{ secrets.${bootstrap} }}
+        run: |
+          set -euo pipefail
+          test -n "\${${bootstrap}}" || {
+            echo "${bootstrap} is not configured for this repository" >&2
+            exit 1
+          }
+
+      - name: Prepare the toolchain and secrets
+        env:
+          ${bootstrap}: \${{ secrets.${bootstrap} }}
+        run: bash scripts/lisa-remote-env/setup.sh
+
+      - name: Run one ${name} cycle
+        env:
+          ${bootstrap}: \${{ secrets.${bootstrap} }}
+        run: |
+          set -euo pipefail
+${runSkillScript("lisa-remote-dispatch", "dispatch.mjs", [
+  `'executionEnv=${loop.executionEnv} ${loop.payload ?? ""}'`,
+  `--skill ${loop.skill ?? `lisa-${name}`}`,
+])}
+
+${rotation}
+`;
+}
+
+function main() {
+  const [name, ...flags] = process.argv.slice(2);
+  if (!name)
+    throw new Error("usage: generate-workflow.mjs <loop-name> [--write]");
+  const loop = readAutomation(name);
+  const yaml = renderWorkflow(name, loop);
+
+  if (!flags.includes("--write")) {
+    process.stdout.write(yaml);
+    return;
+  }
+  const path = workflowPath(name);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, yaml);
+  console.log(`wrote ${path}`);
+  if (!loop.enabled) {
+    console.log(
+      "Registered DISABLED. Prove the exact production path once for one real " +
+        "item with a manual dispatch, then set enabled: true and regenerate."
+    );
+  }
+}
+
+/**
+ * Whether this module is the one node was asked to run.
+ *
+ * Both sides are realpath'd: a raw URL comparison answers "no" through a
+ * symlinked checkout, a git worktree, or a /tmp path on macOS, so the module
+ * loads, runs nothing and exits 0 — a silent no-op that reads as success.
+ *
+ * A local copy rather than an import: plugin payload scripts ship standalone,
+ * with no `lib/` sibling to import from once installed.
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/plugins/lisa-devin/skills/lisa-setup-confluence/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: lisa-setup-confluence
+description: "Configure Confluence as the PRD source for this project. Writes `confluence.spaceKey` and/or `confluence.parentPageId` into `.lisa.config.json` and offers to set top-level `source: \"confluence\"`. Depends on /lisa:setup:atlassian — atlassian.cloudId must already be present. Idempotent."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Setup Confluence: $ARGUMENTS
+
+Pin a Confluence space (or a parent page within one) as the PRD-discovery scope for this project.
+
+## Workflow
+
+### Step 1 — Verify atlassian prerequisite
+
+```bash
+cloudid=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json 2>/dev/null)
+if [ -z "$cloudid" ]; then
+  echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian first." >&2
+  exit 1
+fi
+```
+
+If `atlassian` is missing, invoke `/lisa:setup-atlassian` via the Skill tool first, then resume.
+
+### Step 2 — Resolve scope
+
+Two scoping modes (mutually compatible; both can be set):
+
+- **Space scope** — discover PRDs anywhere in a Confluence space. Honor `--space=KEY` or list spaces via the active substrate:
+  - CLI: `acli confluence space list --output json`
+  - MCP: `mcp__plugin_atlassian_atlassian__getConfluenceSpaces` with `cloudId=$cloudid`
+- **Parent-page scope** — discover PRDs only as descendants of one page. Honor `--parent=PAGE_ID` or ask the user via `AskUserQuestion` to provide it.
+
+If neither arg is supplied, ask which mode (or both). Setting only `parentPageId` is valid; setting only `spaceKey` is valid; setting both narrows the scope.
+
+### Step 3 — Create lifecycle parent pages
+
+Confluence PRD lifecycle is **parent-page-based**, not label-based (see the `config-resolution` rule for why — Atlassian's scoped API tokens cannot write labels). Each lifecycle role gets its own parent page; a PRD's state = which parent it's a child of. The full PRD lifecycle is `draft → ready → in_review → (blocked | ticketed) → shipped → verified` (the `prd-lifecycle-rollup` rule, slug `prd-lifecycle-rollup`): rollup performs the `ticketed → shipped` hop, then `/lisa:verify-prd` performs the terminal `shipped → verified` (pass) / `shipped → ticketed` (fail) hop. `verified` is the terminal lifecycle state after `shipped` (the `verified` role from the `config-resolution` rule, #591).
+
+#### 3a. Decide where the parents live
+
+If `confluence.parentPageId` is set in config, the seven parent pages are created as children of that page (keeps the lifecycle scoped to a sub-tree of the space). Otherwise, they're created at the space root.
+
+```bash
+SPACE_ID=$(curl -s -H "Authorization: Basic $AUTH" \
+  "${GW}/api/v2/spaces?keys=$(jq -r '.confluence.spaceKey' .lisa.config.json)" \
+  | jq -r '.results[0].id')
+PARENT_ROOT=$(jq -r '.confluence.parentPageId // empty' .lisa.config.json)
+```
+
+#### 3b. Create each parent page
+
+For each role in `[draft, ready, in_review, blocked, ticketed, shipped, verified]`, create a page named after the role (`Draft`, `Ready`, `In Review`, `Blocked`, `Ticketed`, `Shipped`, `Verified`). Body: a short description of what PRDs in this state mean.
+
+```bash
+create_parent() {
+  local role="$1" title="$2" body="$3"
+  local payload
+  payload=$(jq -n \
+    --arg sid "$SPACE_ID" \
+    --arg pid "$PARENT_ROOT" \
+    --arg t "$title" \
+    --arg b "$body" '
+    {
+      spaceId: $sid,
+      status: "current",
+      title: $t,
+      body: { representation: "storage", value: $b }
+    } + (if $pid != "" then { parentId: $pid } else {} end)
+  ')
+  curl -s -X POST -H "Authorization: Basic $AUTH" -H "Content-Type: application/json" \
+    -d "$payload" "${GW}/api/v2/pages" | jq -r '.id'
+}
+
+P_DRAFT=$(create_parent     draft     "Draft"     "PRDs being authored; not yet ready for the agent queue.")
+P_READY=$(create_parent     ready     "Ready"     "PRDs flagged by humans as ready for agent ticketing.")
+P_REVIEW=$(create_parent    in_review "In Review" "PRDs the agent has claimed and is validating.")
+P_BLOCKED=$(create_parent   blocked   "Blocked"   "Validation failed — clarifying comments posted by the agent. Edit the PRD, then move back to Ready.")
+P_TICKETED=$(create_parent  ticketed  "Ticketed"  "Validated and tickets created. Tracked through the build queue from here.")
+P_SHIPPED=$(create_parent   shipped   "Shipped"   "All child tickets shipped.")
+P_VERIFIED=$(create_parent  verified  "Verified"  "Shipped product empirically checked against the PRD. Terminal state.")
+```
+
+Handle the "title already exists" case (400 BAD_REQUEST) by searching for an existing page with that title first and re-using its id rather than failing. This find-or-reuse path is what makes the scaffolding **idempotent** — re-running `setup-confluence` reuses an existing `Verified` parent page rather than creating a duplicate.
+
+#### 3c. Write `confluence.parents` to config
+
+```bash
+jq --arg d "$P_DRAFT" --arg r "$P_READY" --arg iv "$P_REVIEW" \
+   --arg b "$P_BLOCKED" --arg t "$P_TICKETED" --arg s "$P_SHIPPED" \
+   --arg v "$P_VERIFIED" '
+  .confluence = ((.confluence // {})
+    | .parents = {
+        draft:     $d,
+        ready:     $r,
+        in_review: $iv,
+        blocked:   $b,
+        ticketed:  $t,
+        shipped:   $s,
+        verified:  $v
+      })
+' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+This persists `confluence.parents.verified` to config, matching the `confluence.parents.verified` schema from the `config-resolution` rule, #591.
+
+### Step 4 — Write top-level `confluence` section (spaceKey / parentPageId)
+
+```bash
+jq --arg space "$SPACE_KEY" --arg parent "$PARENT_ID" '
+  .confluence = (
+    (.confluence // {})
+    | (if $space != ""  then .spaceKey     = $space  else . end)
+    | (if $parent != "" then .parentPageId = $parent else . end)
+  )
+' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+This step is small now that the heavy lifting moved into 3c — but it's still where `spaceKey` and (optionally) `parentPageId` get persisted.
+
+### Step 5 — Offer to set top-level `source`
+
+If `.source` is unset or differs from `"confluence"`, ask via `AskUserQuestion`:
+
+> Confluence configured. Set top-level `source: "confluence"` so `/lisa:intake` (with no args) scans this space for PRDs?
+
+Recommend "Yes" if the team's PRDs live in Confluence. If the team uses Notion or Linear for PRDs and Confluence is only for ad-hoc reference, recommend "No".
+
+If yes:
+
+```bash
+jq '.source = "confluence"' .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+### Step 6 — Create / update PRD Dashboard page
+
+Confluence has no native swimlane / kanban view for label-driven lifecycles. To approximate the Notion-board experience, create a single "PRD Dashboard" page in the configured space that renders seven `Children Display` macros side-by-side — one per PRD lifecycle status (`draft`, `ready`, `in_review`, `blocked`, `ticketed`, `shipped`, `verified`). The dashboard is the team's single-screen view of the PRD pipeline.
+
+The `draft` column captures PRDs that have been created but not yet flipped to `ready` — useful for authors to track their own in-flight work and for editors to find PRDs that need a polish pass before they hit the agent queue.
+
+#### Idempotency
+
+If `confluence.dashboardPageId` already exists in `.lisa.config.json`, update that page rather than create a new one. Otherwise create.
+
+#### Build the page body (Confluence storage format)
+
+Seven columns inside a `ac:layout` block. Each column is a `Children Display` macro targeting one lifecycle parent, scoped to the configured space (or parent page, if set).
+
+Read the parent page IDs from config:
+
+```bash
+P_DRAFT=$(jq -r '.confluence.parents.draft' .lisa.config.json)
+P_READY=$(jq -r '.confluence.parents.ready' .lisa.config.json)
+P_REVIEW=$(jq -r '.confluence.parents.in_review' .lisa.config.json)
+P_BLOCKED=$(jq -r '.confluence.parents.blocked' .lisa.config.json)
+P_TICKETED=$(jq -r '.confluence.parents.ticketed' .lisa.config.json)
+P_SHIPPED=$(jq -r '.confluence.parents.shipped' .lisa.config.json)
+P_VERIFIED=$(jq -r '.confluence.parents.verified' .lisa.config.json)
+```
+
+Build a `Children Display` macro per parent. The macro shows direct children of the specified page, automatically updating as PRDs move between parents:
+
+```xml
+<ac:structured-macro ac:name="children" ac:schema-version="2">
+  <ac:parameter ac:name="page"><ac:link><ri:page ri:content-title="<TITLE>"/></ac:link></ac:parameter>
+  <ac:parameter ac:name="depth">1</ac:parameter>
+  <ac:parameter ac:name="sort">modified</ac:parameter>
+  <ac:parameter ac:name="reverse">true</ac:parameter>
+  <ac:parameter ac:name="all">false</ac:parameter>
+</ac:structured-macro>
+```
+
+Children Display targets a parent by **content-title** (not by id, in storage format). The `ri:content-title` attribute references the parent by its title within the current space.
+
+Wrap the seven macros in three rows of `ac:layout-section`. Confluence's `ac:layout` has no native 7-column preset, so lay out as three rows: two `three_equal` rows plus a final single-column row for the seventh tile. Row 1 (`three_equal`): Draft, Ready, In Review. Row 2 (`three_equal`): Blocked, Ticketed, Shipped. Row 3 (`single`): Verified.
+
+The grouping is semantic too — top row covers the human-driven lead-up to agent pickup; middle row covers agent-driven build states post-pickup; the final row is the terminal `verified` state where the shipped product has been empirically checked against the PRD itself (`/lisa:verify-prd`).
+
+Heading each column with the status name and count keeps the board scannable:
+
+```xml
+<ac:layout-cell>
+  <h2>Ready</h2>
+  <!-- Content by Label macro for prd-ready -->
+</ac:layout-cell>
+```
+
+Above the layout, include a short header describing what the page is and how to use it:
+
+```xml
+<p>This page is the PRD pipeline view. PRDs live as child pages of one of seven lifecycle
+   parents: <strong>Draft</strong>, <strong>Ready</strong>, <strong>In Review</strong>,
+   <strong>Blocked</strong>, <strong>Ticketed</strong>, <strong>Shipped</strong>,
+   <strong>Verified</strong>.
+   Move a PRD between states by re-parenting the page (drag in the page tree, or
+   via the page's location settings).</p>
+<p>To add a new PRD: create a page under <strong>Draft</strong>. When ready for
+   agent pickup, move it to <strong>Ready</strong>.</p>
+```
+
+#### Write the page
+
+Invoke `lisa-atlassian-access` with `operation: write-page`. The payload differs by mode:
+
+- **Create**: `{ "spaceKey": "$SPACE", "title": "PRD Dashboard", "body": "<the storage-format XML built above>", "parentId": "$PARENT" }` (omit `parentId` if not set).
+- **Update**: `{ "id": "<dashboardPageId>", "title": "PRD Dashboard", "body": "<...>" }` — body is fully replaced.
+
+`atlassian-access`'s `write-page` CLI adapter is currently nominal (acli's Confluence surface is `view`-only as of writing), so this call falls through to the MCP adapter. That's acceptable — the dashboard is a one-time setup-only write; the lifecycle hot path (label add/remove) doesn't go through this.
+
+#### Persist the page ID
+
+```bash
+jq --arg id "$DASHBOARD_PAGE_ID" --arg url "$DASHBOARD_URL" \
+   '.confluence = ((.confluence // {})
+                   | .dashboardPageId = $id
+                   | .dashboardUrl    = $url)' \
+   .lisa.config.json > .lisa.config.json.tmp \
+   && mv .lisa.config.json.tmp .lisa.config.json
+```
+
+Both fields are committed (shared across developers — same dashboard for everyone).
+
+#### Skip conditions
+
+Skip Step 6 entirely if:
+
+- `$ARGUMENTS` includes `--no-dashboard`.
+- The MCP fallback is unavailable AND acli can't create pages (i.e., we have no path to write).
+- The user declines via `AskUserQuestion` when offered.
+
+### Step 7 — Verify
+
+```bash
+jq -e '.confluence.spaceKey // .confluence.parentPageId' .lisa.config.json >/dev/null
+jq -e '.confluence.parents.verified' .lisa.config.json >/dev/null
+```
+
+Report success with the resolved scope (`spaceKey`, `parentPageId`, or both), the seven lifecycle parents created or reused (including the terminal `verified` parent), whether `source` was set, and the PRD Dashboard URL if Step 6 ran.
+
+## Idempotency
+
+- Re-running replaces fields cleanly (jq merge).
+- Re-running does not re-prompt for `source` if it's already `"confluence"`.
+- Re-running reuses an existing lifecycle parent page (by title) rather than duplicating it — so the terminal `Verified` parent is created once and reused on every subsequent run.
+- Re-running with an existing `dashboardPageId` updates the page in place rather than creating duplicates.
+
+## Rules
+
+- Never invent a `spaceKey` or `parentPageId`. Resolve via the substrate or have the user provide it explicitly.
+- Setting `source` is opt-in — per-skill invocations with an explicit URL always win, so `source` is just the no-arg default for batch flows.
+- If the user wants both Notion and Confluence as PRD sources (rare), pick one for `source` and document that the other requires explicit URLs.