@pourkit/cli 0.0.0-next-20260625073725 → 0.0.0-next-20260627024509

package/dist/managed/docs/agents/domain.md

@@ -50,6 +50,8 @@ After PRD-0040 migration, the **Async Adapter Seam** entry in `.pourkit/CONTEXT.
 
 Durable planning lives in PRD Plan Workspaces under `.pourkit/plans/<NNNN>-<slug>/`. See the **PRD Plan Workspace** entry in `.pourkit/CONTEXT.md` for the full definition. Explicit `publish-prd` publication is required to publish workspace content to GitHub — direct authoring skills (`to-prd`, `to-issues`) write workspace files only.
 
+In Beads-backed PRD workflows, `to-prd` and `to-issues` write workspace files only — they do not publish to GitHub or write directly to Beads. Explicit `publish-prd` publication validates the workspace through the PRD Plan Workspace Publication Gate, registers the PRD and child Issues in the Beads Work Graph using deterministic IDs (`PRD-0078 -> bd-0078`, `I-01 -> bd-0078.1`), and projects GitHub Issues and labels as collaboration surfaces. GitHub Issues and labels are projections in Beads-backed workflows — they are not the authority for PRD child work readiness.
+
 ## Flag ADR conflicts
 
 If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:

package/dist/managed/skills/publish-prd/SKILL.md

@@ -5,7 +5,7 @@ description: Publish a PRD Plan Workspace to GitHub explicitly and write PUBLISH
 
 # Publish PRD
 
-Publish a PRD Plan Workspace to GitHub by creating or updating a parent PRD Issue and its child Issues from authored workspace files, or a single Task Issue from a oneshot workspace. Publication metadata is written to workspace root `PUBLISH.md`. Authored `PRD.md`, `TASK.md`, and `issues/*.md` bodies are never mutated.
+Publish a PRD Plan Workspace by running the PRD Plan Workspace Publication Gate, publishing GitHub Issues and labels as collaboration surfaces, and writing `PUBLISH.md` as publication metadata. When the current Pourkit install exposes a Pourkit-owned Beads publication transaction, that transaction also registers the workspace in the Beads Work Graph before GitHub projection. Agents must not perform Beads side effects manually. Authored `PRD.md`, `TASK.md`, and `issues/*.md` bodies are never mutated. The Task route remains GitHub-backed — it does not use the Beads Work Graph.
 
 ## Process
 
@@ -32,11 +32,19 @@ Inspect the workspace root to determine which route to follow:
 
 #### 2a. PRD/Plan validation
 
-Block before any GitHub mutation if:
+Block before any Beads or GitHub mutation if:
 
 - `PRD.md` is missing or empty.
 - No `issues/I-0N-*.md` files exist — the PRD/Plan route requires at least one child Issue to publish. Block with a clear message rather than publishing an empty parent-only Issue set.
 
+After file-existence checks pass, run the hard PRD Plan Workspace Publication Gate:
+
+```sh
+pourkit validate-artifact prd-plan-workspace <workspace> --prd-ref <PRD-NNNN>
+```
+
+If validation fails (non-zero exit), block before any Beads, GitHub Issue, or `PUBLISH.md` side effect. Authored files (`PRD.md`, `issues/*.md`), Beads state, GitHub state, and `PUBLISH.md` must remain unchanged. Report the validation diagnostics and require human review/repair — do not auto-repair.
+
 #### 2b. Task validation
 
 Block before any GitHub mutation if:
@@ -58,16 +66,27 @@ Read the full contents of the relevant authored files based on workspace type:
 
 Record content hashes or store the raw text for comparison at handoff. These are the exact bodies published to GitHub; do not modify them during publication.
 
-### 4. Publish or update GitHub Issues
-
-Using the GitHub context available to the agent:
+### 4. Publish through the Pourkit-owned transaction
 
 **PRD/Plan route:**
 
-1. Create or update the parent PRD Issue using the `PRD.md` body. Apply the PRD title derived from the first line or frontmatter of `PRD.md`.
-2. For each `issues/I-0N-*.md`, create or update a child GitHub Issue using the exact file body. Derive the title from the first line or frontmatter of the file.
-3. Apply intended labels to each Issue. Child Issues default to `ready-for-agent` plus exactly one `type:*` label; include `blocked` when the child has unresolved dependencies. Infer labels from file content if present, but treat `needs-triage` on PRD child Issues as stale authoring metadata and publish `ready-for-agent` instead. Parent PRDs default to `needs-triage` and must not receive `ready-for-agent` unless explicitly requested by the maintainer.
-4. In the publication flow only, resolve local dependency placeholders (e.g. `I-01`, `I-02`) to GitHub issue numbers (e.g. `#124`, `#125`) in body text. This resolution happens in the GitHub publication flow only; local files are not modified.
+Run the Pourkit-owned Beads-backed publication transaction:
+
+```sh
+pourkit prd-plan-workspace publish <workspace> --prd-ref <PRD-NNNN>
+```
+
+This command owns the full transaction:
+
+1. Validates the PRD Plan Workspace gate before side effects.
+2. Creates or updates Beads parent/child records and `blocks` dependency edges.
+3. Creates or updates parent and child GitHub Issues as projections.
+4. Backfills Beads `pourkit` metadata with `githubIssueNumber` and `githubIssueUrl`.
+5. Writes `PUBLISH.md` as the human-readable receipt.
+
+Agents must not shell out to `bd` directly or hand-maintain Beads records. Beads registration, dependency edges, and metadata backfill are Pourkit implementation responsibilities only.
+
+If this command is unavailable because the operator is running an older Pourkit install, continue with GitHub-backed publication after the validation gate. Record a warning in `PUBLISH.md` that no Beads Work Graph records were written and PRD Run must use its GitHub-compatible path until the PRD has a valid Beads epic.
 
 **Task route:**
 
@@ -79,7 +98,36 @@ Using the GitHub context available to the agent:
 
 Write workspace root `PUBLISH.md` with the appropriate structure based on workspace type:
 
-**PRD/Plan route:**
+**PRD/Plan route with Beads-backed publication:**
+
+Use `renderPrdPublishReceipt` or `writePrdPublishReceipt` from `pourkit/prd-plan-workspace/publish-receipt.ts` to generate the receipt programmatically. The receipt shape:
+
+```yaml
+workspace: .pourkit/plans/<NNNN>-<slug>
+route: prd
+parent:
+  prd_ref: <PRD-NNNN>
+  beads_id: bd-<NNNN>
+  number: <number>
+  url: https://github.com/OWNER/REPO/issues/<number>
+children:
+  - child_ref: I-0N
+    beads_id: bd-<NNNN>.<N>
+    number: <number>
+    url: https://github.com/OWNER/REPO/issues/<number>
+    source_file: issues/I-0N-<slug>.md
+dependency_mappings:
+  - from: I-0N
+    to: I-0N
+    beads_edge_type: blocks
+publication_timestamp: <ISO-8601>
+authored_bodies_mutated: false
+warnings: []
+```
+
+**PRD/Plan route with GitHub-compatible publication:**
+
+Use this shape when no Pourkit-owned Beads publication transaction is available and no Beads records were written:
 
 ```yaml
 workspace: .pourkit/plans/<NNNN>-<slug>
@@ -96,11 +144,14 @@ children:
       - ready-for-agent
       - type:feature
 dependency_mappings:
-  - local: I-0N
-    github: "#<number>"
+  - from: I-0N
+    to: I-0N
+    github_from: "#<number>"
+    github_to: "#<number>"
 publication_timestamp: <ISO-8601>
 authored_bodies_mutated: false
-warnings: []
+warnings:
+  - Beads publication transaction unavailable; no Beads Work Graph records were written.
 ```
 
 **Task route:**
@@ -130,24 +181,51 @@ Compare content hashes or raw text of all authored files against what was read i
 
 ## Validation receipt
 
-**PRD/Plan route success:**
+**PRD/Plan route success with Beads-backed publication:**
 
 ```yaml
 workspace: .pourkit/plans/<NNNN>-<slug>
 route: prd
 parent:
+  prd_ref: PRD-0078
+  beads_id: bd-0078
   number: 123
   url: https://github.com/OWNER/REPO/issues/123
 children:
-  - id: I-01
+  - child_ref: I-01
+    beads_id: bd-0078.1
     number: 124
     url: https://github.com/OWNER/REPO/issues/124
+    source_file: issues/I-01-example.md
 dependency_mappings: []
-publish_path: .pourkit/plans/<NNNN>-<slug>/PUBLISH.md
+publication_timestamp: <ISO-8601>
 authored_bodies_mutated: false
 warnings: []
 ```
 
+**PRD/Plan route success with GitHub-compatible publication:**
+
+```yaml
+workspace: .pourkit/plans/<NNNN>-<slug>
+route: prd
+parent:
+  number: 123
+  url: https://github.com/OWNER/REPO/issues/123
+children:
+  - id: I-01
+    title: PRD-0078 / I-01: Example
+    number: 124
+    url: https://github.com/OWNER/REPO/issues/124
+    labels:
+      - ready-for-agent
+      - type:feature
+dependency_mappings: []
+publication_timestamp: <ISO-8601>
+authored_bodies_mutated: false
+warnings:
+  - Beads publication transaction unavailable; no Beads Work Graph records were written.
+```
+
 **Task route success:**
 
 ```yaml
@@ -166,10 +244,14 @@ On block or failure, return a blocker summary with the reason and required actio
 ## Edge cases
 
 - **Missing `PRD.md` in PRD/Plan route**: block before any GitHub mutation. Report the missing file path.
+- **Validation gate failure in PRD/Plan route**: `pourkit validate-artifact prd-plan-workspace` exits non-zero. Block before any Beads, GitHub Issue, or `PUBLISH.md` side effect. Diagnostics are from the gate command. Authored files, Beads state, GitHub state, and `PUBLISH.md` remain unchanged. Do not auto-repair — require human review/repair.
 - **Missing `TASK.md` in Task route**: block before any GitHub mutation. Report the missing file path.
 - **No `issues/I-0N-*.md` in PRD/Plan route**: block — PRD/Plan route requires at least one child Issue. Do not publish parent-only.
 - **Both `PRD.md` and `TASK.md` present**: ask the user which to publish before proceeding.
 - **Neither `PRD.md` nor `TASK.md` present**: block with a clear message naming the workspace path.
+- **Beads publication transaction unavailable**: continue with GitHub-compatible publication after validation. Do not call `bd` manually. Include the warning in `PUBLISH.md`.
+- **Beads registration failure from a Pourkit-owned transaction**: block before any GitHub Issue mutation. Pourkit reports this when Beads is unavailable (missing binary or unusable state) or when a Beads command fails. Report the failure and require human intervention.
+- **Beads metadata update failure after GitHub projection in a Pourkit-owned transaction**: block before writing `PUBLISH.md`. Report the parent or child Beads ID and GitHub issue number/URL that failed to persist. Do not treat `PUBLISH.md` as a substitute runtime database.
 - **Existing `PUBLISH.md`**: update it as publication metadata. This is a receipt update, not source behavior mutation.
 - **Existing GitHub Issues**: update bodies and labels rather than creating duplicates. Match by title heuristic or by previous `PUBLISH.md` record.
 - **Missing GitHub token or repo context**: block with setup guidance.
@@ -179,23 +261,84 @@ On block or failure, return a blocker summary with the reason and required actio
 **PRD/Plan route:**
 
 ```yaml
+workspace: string
+route: "prd"
 parent:
+  prd_ref: string
+  beads_id: string
   number: number
   url: string
 children:
-  - id: I-0N
+  - child_ref: string
+    beads_id: string
+    number: number
+    url: string
+    source_file: string
+dependency_mappings:
+  - from: string
+    to: string
+    beads_edge_type: "blocks"
+publication_timestamp: ISO-8601 string
+authored_bodies_mutated: false
+warnings: string[]
+```
+
+**PRD/Plan route with GitHub-compatible publication:**
+
+```yaml
+workspace: string
+route: "prd"
+parent:
+  number: number
+  url: string
+children:
+  - id: string
     title: string
     number: number
     url: string
     labels: string[]
 dependency_mappings:
-  - local: I-0N
-    github: "#<number>"
+  - from: string
+    to: string
+    github_from: string
+    github_to: string
 publication_timestamp: ISO-8601 string
 authored_bodies_mutated: false
 warnings: string[]
 ```
 
+> **Contract**: `PUBLISH.md` is a human-readable receipt and is not the runtime authority for PRD Run selection. When Beads-backed publication is used, Beads metadata is the authoritative source for PRD child work identity, dependencies, and readiness. When GitHub-compatible publication is used because no Pourkit-owned Beads transaction exists, no Beads authority is claimed for that PRD and PRD Run must use its GitHub-compatible path unless a valid Beads epic is later created by Pourkit.
+
+TypeScript contract (from `pourkit/prd-plan-workspace/publish-receipt.ts`):
+
+```ts
+export type PrdPublishReceiptOptions = {
+  workspacePath: string;
+  parent: {
+    prdRef: string;
+    beadsId: string;
+    githubIssue: { number: number; url: string };
+  };
+  children: Array<{
+    childRef: string;
+    beadsId: string;
+    githubIssue: { number: number; url: string };
+    sourceFile: string;
+  }>;
+  dependencyMappings: Array<{
+    from: string;
+    to: string;
+    beadsEdgeType: "blocks";
+  }>;
+  publicationTimestamp: string;
+  authoredBodiesMutated: false;
+  warnings: string[];
+};
+
+export function renderPrdPublishReceipt(options: PrdPublishReceiptOptions): string;
+export function writePrdPublishReceipt(options: PrdPublishReceiptOptions & { workspaceRoot: string }): Promise<string>;
+```
+
 **Task route:**
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pourkit/cli",
-  "version": "0.0.0-next-20260625073725",
+  "version": "0.0.0-next-20260627024509",
   "private": false,
   "type": "module",
   "repository": {