@papi-ai/server 0.7.14 → 0.7.16

package/dist/prompts.js

@@ -193,6 +193,7 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    Also set complexity using the full range \u2014 **XS, Small, Medium, Large, XL** \u2014 based on actual scope, not conservatively. XS = single-line or config change. Small = one file, < 50 lines. Medium = 2-5 files. Large = cross-module, multiple components. XL = architectural, multi-day.
+   **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
    If a task is clearly obsolete, duplicated, or rejected, set its status to "Cancelled" with a \`closureReason\` explaining why.
    **\u2192 PERSIST:** For each task you set reviewed: true, corrected fields on, or marked "Cancelled", include it in \`boardCorrections\` in Part 2.
 
@@ -285,11 +286,11 @@ ${AD_REJECTION_RULES}
 
    **UI/visual task detection:** Apply these additions ONLY to tasks whose PRIMARY scope is frontend visual work \u2014 the task's main deliverable must be a UI change, new component, visual design, or page. Do NOT apply to backend tasks, DB migrations, or prompt/config changes that merely mention a dashboard or page in passing. Signal: the task would fail if no .tsx/.css files were changed. If uncertain, skip the UI additions.
    When a task IS a UI task (primary scope is visual/frontend):
-   - Add to SCOPE: "Read \`.impeccable.md\` for brand palette, design principles, and audience context before writing any code. Use the \`frontend-design\` skill for implementation."
+   - Add to SCOPE: "Read \`.impeccable.md\` for component patterns, anti-patterns, and dev-loop design rules. Read \`docs/branding/brand-book.html\` for brand identity (positioning, voice, palette as final canon). Use the \`frontend-design\` skill for implementation."
    - For M/L UI tasks, add to SCOPE: "Use the full UI toolchain: Playground (design preview) \u2192 Frontend-design (build) \u2192 Playwright (verify). The playground is the quality bar. Expect 2-3 iterations."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser \u2014 provide localhost URL or screenshot to user for review." and "[ ] No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips."
-   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection."
-   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` and the frontend-design skill \u2014 don't try to write design specs in the handoff.
+   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 pull from \`docs/branding/brand-book.html\` for canonical brand identity."
+   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` (dev patterns) + \`docs/branding/brand-book.html\` (brand identity) and the frontend-design skill \u2014 don't try to write design specs in the handoff.
 
 11. **New Tasks (max 3 per cycle)** \u2014 Actively mine the Recent Build Reports for task candidates. For each report, check:
    - **Discovered Issues:** If a build report lists a discovered issue and no existing board task covers it, propose a new task.
@@ -357,7 +358,7 @@ var PLAN_FRAGMENT_SPIKE = `
 var PLAN_FRAGMENT_DESIGN_BRIEF = `
    **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Replace the standard SCOPE (DO THIS) section with these type-specific sections:
    - AUDIENCE: Who this design is for \u2014 persona and context of use (e.g. "non-technical Owner, first dashboard visit")
-   - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` and \`docs/design/brand-system.md\` if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
+   - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` (dev patterns, anti-patterns, component rules) AND \`docs/branding/brand-book.html\` (brand identity, positioning, voice canon) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
    - DELIVERABLE FORMAT: What the output looks like \u2014 Claude Design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
    - REVIEW POINTS: What the Owner must approve before the design is considered done (e.g. layout, copy, colour, imagery).
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
@@ -389,11 +390,11 @@ var PLAN_FRAGMENT_OPS_BRIEF = `
 var PLAN_FRAGMENT_UI = `
    **UI/visual task detection:** Apply these additions ONLY to tasks whose PRIMARY scope is frontend visual work \u2014 the task's main deliverable must be a UI change, new component, visual design, or page. Do NOT apply to backend tasks, DB migrations, or prompt/config changes that merely mention a dashboard or page in passing. Signal: the task would fail if no .tsx/.css files were changed. If uncertain, skip the UI additions.
    When a task IS a UI task (primary scope is visual/frontend):
-   - Add to SCOPE: "Read \`.impeccable.md\` for brand palette, design principles, and audience context before writing any code. Use the \`frontend-design\` skill for implementation."
+   - Add to SCOPE: "Read \`.impeccable.md\` for component patterns, anti-patterns, and dev-loop design rules. Read \`docs/branding/brand-book.html\` for brand identity (positioning, voice, palette as final canon). Use the \`frontend-design\` skill for implementation."
    - For M/L UI tasks, add to SCOPE: "Use the full UI toolchain: Playground (design preview) \u2192 Frontend-design (build) \u2192 Playwright (verify). The playground is the quality bar. Expect 2-3 iterations."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser \u2014 provide localhost URL or screenshot to user for review." and "[ ] No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips."
-   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection."
-   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` and the frontend-design skill \u2014 don't try to write design specs in the handoff.`;
+   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 pull from \`docs/branding/brand-book.html\` for canonical brand identity."
+   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` (dev patterns) + \`docs/branding/brand-book.html\` (brand identity) and the frontend-design skill \u2014 don't try to write design specs in the handoff.`;
 var PLAN_FRAGMENT_PRODUCT_BRIEF = `
 12. **Product Brief** \u2014 Check whether the product brief still reflects reality. Update the brief when ANY of these apply:
    - A new AD was created or an existing AD was superseded that changes product scope, target user, or positioning
@@ -431,6 +432,7 @@ Standard planning cycle with full board review.
    - **P3 Low** \u2014 Nice-to-have, speculative, or future-horizon work.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    Also set complexity using the full range \u2014 **XS, Small, Medium, Large, XL** \u2014 based on actual scope, not conservatively. XS = single-line or config change. Small = one file, < 50 lines. Medium = 2-5 files. Large = cross-module, multiple components. XL = architectural, multi-day.
+   **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
    If a task is clearly obsolete, duplicated, or rejected, set its status to "Cancelled" with a \`closureReason\` explaining why.
    **\u2192 PERSIST:** For each task you set reviewed: true, corrected fields on, or marked "Cancelled", include it in \`boardCorrections\` in Part 2.
 
@@ -645,6 +647,16 @@ function buildPlanUserMessage(ctx) {
     if (ctx.registeredDocs) {
       parts.push("### Relevant Research Docs", "", ctx.registeredDocs, "");
     }
+    if (ctx.unactionedDocs) {
+      parts.push(
+        "### Unactioned Research (soft-warn)",
+        "",
+        "These registered docs still have pending actions. Before adding net-new tasks, consider whether one of these unactioned items should be promoted into this cycle via `doc_action_promote`. Surface this in your plan output so the user can decide.",
+        "",
+        ctx.unactionedDocs,
+        ""
+      );
+    }
     if (ctx.carryForwardStaleness) {
       parts.push("### Carry-Forward Staleness", "", ctx.carryForwardStaleness, "");
     }
@@ -857,6 +869,13 @@ ${AD_REJECTION_RULES}
 
 **Registered Documents:** If a "### Registered Documents" section is present in context, scan it for: (a) research findings that contradict current ADs or strategy, (b) unactioned research that should influence the next plan. Reference relevant docs by title in your review. If unregistered docs are listed, flag 1-2 that look strategically relevant and suggest registering them.
 
+**Doc Action Staleness:** If a "### Doc Action Staleness" section is present, treat it as a research-to-action audit. For each entry:
+- **Stale** (no Done task, >20 cycles old): explicitly call it out in section 2 (Product Gaps) or 3 (Opportunities) \u2014 research that's been sitting unactioned this long is either (a) no longer relevant (recommend marking the doc archived) or (b) silently dropped (recommend promoting via \`doc_action_promote\` into the next plan).
+- **Completed but not closed** (linked task is Done): instruct in your review that the action should be marked resolved \u2014 it's done work the registry hasn't caught up to.
+- **Deferred** (<20 cycles, no matching Done task): only mention if it relates to a current strategic theme; otherwise leave it.
+
+For every stale or unresolved item you call out, propose a concrete next step (promote, archive, or supersede) \u2014 don't just observe.
+
 ## CONDITIONAL SECTIONS (include only when genuinely useful \u2014 most reviews should have 0-2 of these)
 
 6. **Security Posture Review** \u2014 Only if \`[SECURITY]\` tags exist in recent cycle logs.
@@ -965,7 +984,7 @@ After your natural language output, include this EXACT format on its own line:
       "content": "string \u2014 specific observation from using PAPI on this project (e.g. 'deprioritise clears handoffs unnecessarily, wasting planner tokens')"
     }
   ],
-  "northStar": "string or null \u2014 the current North Star statement. Include if you assessed it in section 4 and it is still accurate (copy the current statement verbatim). Include the updated version if you revised it. Use null ONLY if no North Star has ever been set for this project."
+  "northStar": "string or null \u2014 the current North Star statement. Include if you assessed it in section 4 and it is still accurate (copy the current statement verbatim). Include the updated version if you revised it. Use null ONLY if no North Star has ever been set for this project. PLAIN TEXT ONLY \u2014 no markdown formatting, no **bold**, no _italic_, no ##headings, no quote marks around the whole statement. Just the statement itself."
 }
 \`\`\`
 
@@ -1273,12 +1292,16 @@ This is an existing project being adopted into PAPI. Use the codebase analysis b
 
 ${inputs.codebaseContext}
 ` : "";
+  const description = inputs.description?.trim() ? `**Description:** ${inputs.description}
+` : `**Description:** (not provided \u2014 derive from the codebase analysis below)
+`;
+  const targetUsers = inputs.targetUsers?.trim() ? `**Target users:** ${inputs.targetUsers}
+` : `**Target users:** (not provided \u2014 derive from the codebase analysis below)
+`;
   return `Generate a Product Brief for this project.
 
 **Project name:** ${inputs.projectName}
-**Description:** ${inputs.description}
-**Target users:** ${inputs.targetUsers}
-**Key problems it solves:** ${inputs.problems}${codebaseSection}
+${description}${targetUsers}**Key problems it solves:** ${inputs.problems}${codebaseSection}
 
 Return the Product Brief using this exact markdown structure (fill in each section with specific, concrete content \u2014 no placeholder text):
 
@@ -1366,8 +1389,8 @@ function buildAdSeedPrompt(ctx) {
     "",
     `**Project:** ${ctx.projectName}`,
     `**Type:** ${ctx.projectType}`,
-    `**Description:** ${ctx.description}`,
-    `**Target users:** ${ctx.targetUsers}`,
+    `**Description:** ${ctx.description?.trim() || "(not provided \u2014 derive from project type and problems)"}`,
+    `**Target users:** ${ctx.targetUsers?.trim() || "(not provided \u2014 infer reasonable defaults from project type)"}`,
     `**Problems solved:** ${ctx.problems}`
   ];
   parts.push(`**Team size:** ${ctx.teamSize}`);
@@ -1412,8 +1435,8 @@ function buildConventionsPrompt(ctx) {
     "",
     `**Project:** ${ctx.projectName}`,
     `**Type:** ${ctx.projectType}`,
-    `**Description:** ${ctx.description}`,
-    `**Target users:** ${ctx.targetUsers}`,
+    `**Description:** ${ctx.description?.trim() || "(not provided \u2014 infer from project type)"}`,
+    `**Target users:** ${ctx.targetUsers?.trim() || "(not provided \u2014 infer reasonable defaults from project type)"}`,
     `**Problems solved:** ${ctx.problems}`,
     `**Team size:** ${ctx.teamSize}`,
     `**Deployment:** ${ctx.deploymentTarget}`
@@ -1451,12 +1474,16 @@ Return a JSON array of 3-10 tasks. Each task must have:
 - Tasks should be specific enough to execute without further investigation
 - Maximum 10 tasks \u2014 fewer is better if the codebase is well-maintained`;
 function buildInitialTasksPrompt(inputs) {
+  const description = inputs.description?.trim() ? `**Description:** ${inputs.description}
+` : `**Description:** (not provided \u2014 derive from the codebase analysis below)
+`;
+  const targetUsers = inputs.targetUsers?.trim() ? `**Target users:** ${inputs.targetUsers}
+` : `**Target users:** (not provided \u2014 derive from the codebase analysis below)
+`;
   return `Analyse this existing codebase and generate initial backlog tasks.
 
 **Project:** ${inputs.projectName}
-**Description:** ${inputs.description}
-**Target users:** ${inputs.targetUsers}
-
+${description}${targetUsers}
 ${inputs.codebaseContext}
 
 Return a JSON array of 3-10 tasks based on gaps, improvements, and next steps visible from the codebase analysis above.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "type": "module",
@@ -23,6 +23,7 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
+    "lint": "eslint src",
     "prepack": "rm -rf dist && npm run build"
   },
   "keywords": [