@papi-ai/server 0.7.62 → 0.7.64

package/dist/prompts.js

@@ -130,6 +130,7 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 - Updated or created Active Decisions in Part 1? \u2192 Put them in \`activeDecisions\` array (with id and full body including ### heading)
 - Found board corrections (wrong priority, missing fields, stale status) in Part 1? \u2192 Put them in \`boardCorrections\` array
 - Generated BUILD HANDOFFs in Part 1? \u2192 Put them in \`cycleHandoffs\` array
+- **\`complexity\` uses the LONG forms only** \u2014 "XS", "Small", "Medium", "Large", "XL". Do NOT reuse the handoff EFFORT short-forms (S/M/L) for task complexity.
 
 **Example with populated fields (DO NOT copy literally \u2014 adapt to your actual analysis):**
 \`\`\`json
@@ -170,13 +171,20 @@ This is Cycle 0 \u2014 the first planning cycle for a brand-new project.
    - Do NOT assume web-app patterns (routes, pages, components) unless the brief explicitly describes a web application
    - All tasks: status Backlog, priority P1-P2, reviewed true, phase "Phase 1"
 
+   **REASONING LINE (task-2868 \u2014 the first cycle must SHOW PAPI's intelligence, not read as a generic list).** For EVERY task, the \`notes\` field MUST OPEN with a single line in the exact form:
+   \`Why: <one plain-language sentence, \u2264160 chars, on why THIS task earns its place in the first cycle>\`
+   Then a blank line, then any other notes. Rules:
+   - Task 1's \`Why:\` must also justify its POSITION \u2014 say why it is the opening slice (the thinnest thing that puts the core loop in front of the user). This one line is the cycle's sequencing rationale; the dashboard surfaces it above the first task.
+   - Plain language for a semi-technical builder \u2014 no jargon, no raw IDs, not a restatement of the title.
+   - This is a hard requirement: the dashboard's first-cycle experience reads and renders this \`Why:\` line per task.
+
 4. **First Active Decision** \u2014 If the description implies a clear architectural choice, create AD-1 with Confidence: MEDIUM. If no clear choice, skip this.
 
 5. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for EVERY task created in step 3 (all 3-5 tasks). Include each in the \`cycleHandoffs\` array. **tempId join (REQUIRED \u2014 mismatches silently scramble handoffs):** give EVERY \`newTasks\` entry a unique \`tempId\` (\`"new-1"\`, \`"new-2"\`, \u2026), and set each \`cycleHandoffs\` \`taskId\` to the EXACT \`tempId\` of the newTask it belongs to. Do NOT rely on array order, and do NOT reuse a tempId. The builder needs handoffs to run \`build_execute\` \u2014 without them, tasks must be completed via \`ad_hoc\`, which breaks the normal flow.
 
 ### Structured output for Bootstrap:
 In the JSON block, you MUST include:
-- "newTasks": array of task objects with ALL fields: title, status, priority, complexity, module, epic, phase, owner, notes. **This is how tasks get created on the board. If this array is empty, NO tasks will exist.**
+- "newTasks": array of task objects with ALL fields: title, status, priority, complexity, module, epic, phase, owner, notes. **This is how tasks get created on the board. If this array is empty, NO tasks will exist.** Every \`notes\` value MUST open with the \`Why: <sentence>\` reasoning line described in step 3 (the dashboard's first-cycle experience renders it).
 - "productBrief": the full Product Brief markdown content. **If null, the brief stays as the template.**
 - "activeDecisions": array of {id, body} objects. **If you created AD-1 in Part 1 but this array is empty, the AD will NOT be saved.**
 - "recommendedTaskId": null (the handler will use the first new task)
@@ -720,10 +728,17 @@ function coerceToString(value) {
   return JSON.stringify(value, null, 2);
 }
 function coerceStructuredOutput(parsed) {
-  const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => ({
-    taskId: coerceToString(h.taskId),
-    buildHandoff: coerceToString(h.buildHandoff)
-  })) : [];
+  const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => {
+    const { taskId: _t, buildHandoff: _b, ...rest } = h;
+    if (typeof h.buildHandoff === "object" && h.buildHandoff !== null && !Array.isArray(h.buildHandoff)) {
+      Object.assign(rest, h.buildHandoff);
+    }
+    return {
+      taskId: coerceToString(h.taskId),
+      buildHandoff: typeof h.buildHandoff === "string" ? h.buildHandoff : "",
+      ...Object.keys(rest).length > 0 ? { structuredFields: rest } : {}
+    };
+  }) : [];
   const newTasks = Array.isArray(parsed.newTasks) ? parsed.newTasks.map((t) => ({
     // task-2242: stable join key (optional — undefined falls back to index).
     tempId: t.tempId !== void 0 && t.tempId !== null ? coerceToString(t.tempId) : void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.62",
+  "version": "0.7.64",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",

package/skills/papi-cycle/AGENTS.md

@@ -38,6 +38,7 @@ When a conversation starts — fresh window, new session, or after context compr
 - **All in-cycle, in-module tasks share `feat/cycle-N-<module>`** regardless of complexity. One branch per module per cycle, merged together. Module-less tasks fall back to a per-task branch.
 - **Dependent tasks (any size):** When a task's BUILD HANDOFF lists a `DEPENDS ON` task from the same cycle, `build_execute` automatically reuses the upstream task's branch so commits stack for a single PR. Do not create a separate branch manually.
 - **Commit per task within grouped branches** — traceable git history.
+- **Integration + gate before release when a cycle fans to more than 4 module branches.** A wide cycle has no single point where all branches are proven together, so a collision between two branches only surfaces at release. When a cycle has more than 4 module branches, before `release`: (1) cut an integration branch off your main branch, (2) merge every cycle module branch into it, (3) run your full local gate/test suite on the integrated result, (4) resolve any cross-branch collisions there, (5) release from the integrated branch. This is a habit, not automation — release does not block on branch count.
 - **Never use `build_execute` with `light=true` on shared branches.** Light mode commits directly to the current branch without creating a PR. When a shared branch is squash-merged, those commits are collapsed — any CLAUDE.md or documentation changes are stripped. Use light mode only on isolated single-task branches where no squash-merge will occur.
 
 ## Plumbing Is Autonomous