@papi-ai/server 0.7.59 → 0.7.61

package/dist/backfill-cycle-metrics.js

@@ -1189,7 +1189,12 @@ var init_proxy_adapter = __esm({
       "listContributorReleasePrs",
       "claimReview",
       "getSiblingAds",
-      "getSiblingRepoTasks"
+      "getSiblingRepoTasks",
+      // task-2828 (C339): attributed-intelligence analytics reader — pg-only this cycle.
+      // Hosted forwarding needs a SECURITY DEFINER RPC + edge handler (like task-2394 did
+      // for getModuleEstimationStats); until then keep it here so hosted degrades to a
+      // safe `undefined` rather than forwarding into a 403. Wire under task-2390.
+      "getModelOutcomeStats"
       // task-2394 (C329) — Batch A wired: findPendingDocActionsForTask,
       // getModuleEstimationStats and getDecisionScorePatterns now have edge case handlers
       // (each backed by a SECURITY DEFINER RPC, migration 20260714140000) plus

package/dist/index.js

@@ -1306,7 +1306,12 @@ var init_proxy_adapter = __esm({
       "listContributorReleasePrs",
       "claimReview",
       "getSiblingAds",
-      "getSiblingRepoTasks"
+      "getSiblingRepoTasks",
+      // task-2828 (C339): attributed-intelligence analytics reader — pg-only this cycle.
+      // Hosted forwarding needs a SECURITY DEFINER RPC + edge handler (like task-2394 did
+      // for getModuleEstimationStats); until then keep it here so hosted degrades to a
+      // safe `undefined` rather than forwarding into a 403. Wire under task-2390.
+      "getModelOutcomeStats"
       // task-2394 (C329) — Batch A wired: findPendingDocActionsForTask,
       // getModuleEstimationStats and getDecisionScorePatterns now have edge case handlers
       // (each backed by a SECURITY DEFINER RPC, migration 20260714140000) plus
@@ -7527,6 +7532,9 @@ ${footer}`);
 function newTaskJoinKey(task, index) {
   return task.tempId ?? `new-${index + 1}`;
 }
+function isUnresolvedPlaceholder(taskId, map) {
+  return !map.has(taskId) && /^new-\d+$/i.test(taskId);
+}
 var NONE_PATTERN2 = /^none\b/i;
 function normalizeText2(text) {
   return text.trim().toLowerCase().replace(/[.,;:!]+$/, "").replace(/\s+/g, " ");
@@ -9010,7 +9018,7 @@ 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\` (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.
+   - DELIVERABLE FORMAT: What the output looks like \u2014 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.
    Add to ACCEPTANCE CRITERIA: "[ ] Deliverable format confirmed with Owner before starting" and "[ ] Design output is self-contained \u2014 includes enough context for a developer to implement without further clarification."`;
@@ -9209,6 +9217,21 @@ function buildPlanFullInstructionsConditional(flags, ctx) {
   if (!flags || !ctx) return PLAN_FULL_INSTRUCTIONS;
   return composeFullModeInstructions(flags, ctx);
 }
+var CYCLE_DENSITY_TARGETS = {
+  light: { label: "Light", range: "2-3" },
+  standard: { label: "Standard", range: "3-5" },
+  deep: { label: "Deep", range: "6-8" }
+};
+function buildCycleDensityDirective(density) {
+  if (!density) return "";
+  const target = CYCLE_DENSITY_TARGETS[density];
+  return [
+    `## CYCLE DENSITY: ${target.label}`,
+    "",
+    `The user set this cycle's density to **${density}** \u2014 aim for roughly **${target.range} tasks** this cycle.`,
+    `This is a TARGET to size toward, not a hard floor or cap: still honour explicit user direction, any pre-assigned tasks, and impact-based sizing. If fewer genuinely-valuable tasks exist, plan fewer \u2014 do NOT pad the cycle to hit the number.`
+  ].join("\n");
+}
 function buildPlanUserMessage(ctx) {
   const modeLabel = ctx.mode.toUpperCase();
   const parts = [
@@ -9226,6 +9249,10 @@ function buildPlanUserMessage(ctx) {
       ""
     );
   }
+  const densityDirective = buildCycleDensityDirective(ctx.density);
+  if (densityDirective) {
+    parts.push(densityDirective, "");
+  }
   if (ctx.mode === "bootstrap") {
     parts.push(PLAN_BOOTSTRAP_INSTRUCTIONS);
   } else {
@@ -10101,15 +10128,49 @@ phases:
 
 *No decisions locked yet. These are added as planning cycles confirm strategic choices.*`;
 }
+function buildPreScanInstruction(opts) {
+  const docRouting = opts.hosted ? "paste the relevant content (decision records, roadmap, spec excerpts) directly into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "pass local doc file paths as `sources` (comma-separated), or paste content into `description`.";
+  return [
+    `**\u{1F50E} Before you generate anything \u2014 scan the project and gather real context.**`,
+    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name. You (the agent running this) have local access that PAPI does not \u2014 do the gathering, then pass it back.`,
+    ``,
+    `1. **Confirm the environment.** Check that you are running from the root of this project's dev environment \u2014 the folder that holds its source, git history, and docs. If you are not there, or you are connected over a remote connector with no access to the user's files, say so and ask the user where the project lives before continuing.`,
+    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call.`,
+    `3. **Scan the docs.** Look through \`docs/\`, design notes, ADRs/decision records, and any roadmap or planning files \u2014 not just code.`,
+    `4. **Check for sibling / separate repos.** Many projects span more than one repo (a separate frontend, backend, infra, or mobile repo, or other packages in a monorepo). Ask the user whether any related repos or directories exist, and scan those too.`,
+    `5. **Ask the user to point you at extra context.** Prompt them: "Is there anything else I should read before setting this up \u2014 a PRD or spec, decision records, a roadmap, or links to related repos or docs?" Fold whatever they share into the scan.`,
+    `6. **Re-run \`setup\` with what you gathered:** pass the code scan as \`codebase_scan\`; for docs, decision records, and roadmap, ${docRouting} Then answer the prompts below.`,
+    ``,
+    `If there is genuinely no code and no docs yet, skip this and generate from what the user tells you \u2014 the zero-context path is fully supported.`
+  ].join("\n");
+}
+var PAPI_DOCS_QUICKSTART_URL = "https://getpapi.ai/docs/guide/quick-start";
+var PAPI_PUBLIC_REPO_URL = "https://github.com/getpapi/papi";
+function buildNewProjectSetupInstruction(opts) {
+  const visionRouting = opts.hosted ? "paste anything they share (notes, a PRD, links) into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "fold anything they share (notes, a PRD, a sketch, links) into `description`, or pass local doc paths as `sources`.";
+  return [
+    `**\u{1F331} New project \u2014 start from the vision.**`,
+    `There's no existing code to mine, so setup builds from what the user wants to create. Do two things before answering the prompts below.`,
+    ``,
+    `1. **Get oriented on PAPI.** So you can guide the user well \u2014 whatever assistant you are \u2014 skim the quick-start docs at ${PAPI_DOCS_QUICKSTART_URL} and the public repo at ${PAPI_PUBLIC_REPO_URL}. They explain the plan \u2192 build \u2192 review cycle the user will run after setup.`,
+    `2. **Draw out the vision with the user.** Ask what they're building and for whom, the core problem it solves, and what success looks like \u2014 enough to write a real brief, a North Star, and a starter backlog rather than a generic scaffold. If they already have a PRD, sketch, notes, or links, ${visionRouting}`,
+    ``,
+    `Then answer the prompts below to generate the brief, decisions, North Star, and a vision-first starter backlog.`
+  ].join("\n");
+}
 var AD_SEED_SYSTEM = `You are a technical architect seeding initial Active Decisions for a new software project managed by PAPI.
 
 Active Decisions (ADs) are documented architectural choices with confidence levels. They guide the planner and builder agents \u2014 without ADs, planning output is generic and unhelpful.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce decisions directly.
 
+## SOURCE OF TRUTH \u2014 extract real decisions first
+
+If the context includes decision records, ADRs, a roadmap, a README, or codebase analysis, your PRIMARY job is to EXTRACT the real, already-made decisions from that material \u2014 not to invent generic ones. Read the provided context and capture each load-bearing choice the project has actually made (its stack, data model, architecture, positioning, deployment posture). Only fall back to informed defaults for a project of this type when the context contains no evidenced decisions.
+
 ## OUTPUT FORMAT
 
-Return a JSON array of 3-5 Active Decisions. Each AD must have:
+Return a JSON array of Active Decisions \u2014 ONE per real decision you find. Each AD must have:
 - "id": "AD-1", "AD-2", etc.
 - "body": Full markdown block including ### heading, confidence tag, and body text
 
@@ -10123,17 +10184,20 @@ The body format for each AD:
 
 ## GUIDELINES
 
-- All seeded ADs should have Confidence: MEDIUM (they are informed defaults, not confirmed choices)
-- Focus on decisions that genuinely differ by project type \u2014 avoid generic truisms
-- Each AD should be actionable and falsifiable (something the team could decide differently)
+- **Count follows the evidence \u2014 there is NO fixed target.** Seed as many ADs as there are real, distinct decisions in the material. Do NOT pad to a number, and do NOT fabricate decisions to hit a count. When the context has no evidenced decisions, return a small set (2-4) of informed defaults for this project type.
+- **Confidence reflects evidence:** a decision explicitly documented as settled in the source may be HIGH; an informed default you inferred stays MEDIUM.
+- Never mint an AD that is not a genuine stance-with-alternatives \u2014 a preference, a fact, or a config value is NOT an AD.
+- Focus on decisions that genuinely differ by project \u2014 avoid generic truisms.
+- Each AD should be actionable and falsifiable (something the team could decide differently).
 - Cover different concerns: architecture, data, deployment, testing strategy, API design, etc.
-- Keep each AD body to 4-6 lines \u2014 concise and scannable
+- Keep each AD body to 4-6 lines \u2014 concise and scannable.
+- **Do NOT duplicate** any decision already listed as an existing Active Decision in the context \u2014 skip it entirely.
 - **Quality bar:** ADs are for product and architecture choices that constrain future work \u2014 technology selections, data model designs, UX principles, strategic positioning. They are NOT for process preferences, configuration choices, or temporary workarounds.
 
 Return ONLY valid JSON \u2014 no preamble, no code fences, no explanation.`;
 function buildAdSeedPrompt(ctx) {
   const parts = [
-    `Generate 3-5 Active Decisions for this project.`,
+    ctx.codebaseContext ? `Extract the real Active Decisions for this project from the context below. Seed one AD per genuine decision \u2014 do not cap the count, and do not fabricate.` : `Seed the informed default Active Decisions for this project (no decision docs were supplied \u2014 infer sensible MEDIUM-confidence defaults for this project type).`,
     "",
     `**Project:** ${ctx.projectName}`,
     `**Type:** ${ctx.projectType}`,
@@ -10146,12 +10210,57 @@ function buildAdSeedPrompt(ctx) {
   if (ctx.constraints) {
     parts.push(`**Constraints:** ${ctx.constraints}`);
   }
+  if (ctx.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract the real decisions from here",
+      ctx.codebaseContext
+    );
+  }
+  if (ctx.existingDecisions && ctx.existingDecisions.length > 0) {
+    parts.push(
+      "",
+      "## Existing Active Decisions \u2014 do NOT duplicate these",
+      ...ctx.existingDecisions.map((d) => `- ${d}`)
+    );
+  }
   parts.push(
     "",
     'Return a JSON array of AD objects with "id" and "body" fields. No other text.'
   );
   return parts.join("\n");
 }
+var NORTH_STAR_SYSTEM = `You are helping a builder define the North Star for a software project set up with PAPI.
+
+A North Star is the ONE outcome that best captures whether the project is succeeding \u2014 a single, measurable, user-centred statement the team can steer by. It is not a feature list and not a vision paragraph.
+
+IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions in your output.
+
+## HOW TO PRODUCE IT
+- If the provided context (brief, docs, decision records) ALREADY states a North Star, goal metric, or primary success measure, EXTRACT and restate it \u2014 do not invent a competing one.
+- Otherwise, PROPOSE the most fitting North Star from the project's purpose and users. (The calling agent will confirm it with the user before it is saved.)
+
+## OUTPUT FORMAT
+Return ONLY the North Star statement \u2014 one or two sentences, concrete and measurable where possible. No heading, no preamble, no quotes, no code fences.`;
+function buildNorthStarPrompt(inputs) {
+  const parts = [
+    `Define the North Star for this project.`,
+    "",
+    `**Project:** ${inputs.projectName}`,
+    `**Description:** ${inputs.description?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Target users:** ${inputs.targetUsers?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Problems solved:** ${inputs.problems}`
+  ];
+  if (inputs.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract an existing North Star from here if one is stated",
+      inputs.codebaseContext
+    );
+  }
+  parts.push("", "Return only the North Star statement.");
+  return parts.join("\n");
+}
 var CONVENTIONS_SYSTEM = `You are a senior software engineer generating CLAUDE.md coding conventions for a new project.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce conventions directly.
@@ -10842,7 +10951,7 @@ function computeCarryForwardStaleness(log2, doneTaskIds) {
   if (stale.length === 0) return void 0;
   const lines = stale.map(([id, count]) => `- **${id}** \u2014 deferred ${count} consecutive cycle(s)`);
   return [
-    `\u26A0\uFE0F ${stale.length} task(s) have been in carry-forward for 3+ consecutive cycles. The planner must resolve each \u2014 either escalate to P1 High or recommend cancellation with a closure reason. Deferring again without justification is not acceptable.`,
+    `\u26A0\uFE0F ${stale.length} task(s) have been in carry-forward for 3+ consecutive cycles. The planner must resolve each \u2014 either escalate it to P1 High, or move it to Deferred with a reason. Do NOT cancel a stale carry-forward task: cancelling removes it from the owner's field of view, and only the owner may cancel. Deferring again without a fresh justification is not acceptable.`,
     "",
     ...lines
   ].join("\n");
@@ -10992,6 +11101,15 @@ async function resolveOwnerGate(adapter2, config2) {
 
 // src/services/plan.ts
 var PLAN_BUILD_REPORT_BUDGET = { maxReports: 12, fieldBudget: 280 };
+function leadChainWithRecommended(chain, recommendedTaskId) {
+  const rec = recommendedTaskId?.trim();
+  const existing = (chain ?? "").trim();
+  if (!rec) return existing || void 0;
+  const firstMentioned = existing.match(/task-\d+/)?.[0];
+  if (firstMentioned === rec) return existing || void 0;
+  const lead = `Build order: ${rec} first.`;
+  return existing ? `${lead} ${existing}` : lead;
+}
 async function resolvePlanScope(adapter2, config2) {
   const gate = await resolveOwnerGate(adapter2, config2);
   return { callerUserId: gate.callerUserId, ownerUserId: gate.ownerUserId, callerIsOwner: gate.callerIsOwner };
@@ -11940,7 +12058,12 @@ ${cleanContent}`;
     // project owner when unset, so owner-operated plans stay correct).
     ...options.ownerUserId ? { userId: options.ownerUserId } : {},
     // task-2483 (C319): persist the plan's Dependency Chain build-order markdown.
-    ...data.dependencyChain ? { dependencyChain: data.dependencyChain } : {}
+    // task-2823 (C338): seed it to lead with recommendedTaskId when the plan omits a
+    // chain or it doesn't lead with the planner's pick, so the hub next-move agrees.
+    ...(() => {
+      const chain = leadChainWithRecommended(data.dependencyChain, data.recommendedTaskId);
+      return chain ? { dependencyChain: chain } : {};
+    })()
   };
   const earlyCreateWarnings = [];
   try {
@@ -12327,10 +12450,10 @@ ${cleanContent}`;
     }
     for (const handoff of data.cycleHandoffs) {
       const resolvedId = newTaskIdMap.get(handoff.taskId) ?? handoff.taskId;
-      if (resolvedId === handoff.taskId && /^new-\d+$/i.test(handoff.taskId)) {
+      if (isUnresolvedPlaceholder(handoff.taskId, newTaskIdMap)) {
         const titleLine = handoff.buildHandoff.match(/^Task:\s*(.+)/m)?.[1] ?? "(unknown)";
-        console.error(
-          `[plan] UNRESOLVED handoff reference "${handoff.taskId}" (task: ${titleLine.slice(0, 80)}) \u2014 no newTask carries this tempId/index. Handoff NOT written. Ensure each newTasks entry has a tempId matching its cycleHandoffs taskId (task-2242).`
+        warnings.push(
+          `UNRESOLVED handoff "${handoff.taskId}" (task: ${titleLine.slice(0, 80)}) \u2014 no newTask carries this tempId/index; handoff NOT written and the task is missing from the cycle. Ensure each newTasks entry has a tempId matching its cycleHandoffs taskId (task-2242).`
         );
         continue;
       }
@@ -12373,7 +12496,13 @@ ${cleanContent}`;
         ...options.ownerUserId ? { userId: options.ownerUserId } : {},
         // task-2483 (C319): persist the plan's Dependency Chain build-order markdown.
         // This full write patches the early minimal row created in Phase 1.
-        ...data.dependencyChain ? { dependencyChain: data.dependencyChain } : {}
+        // task-2823 (C338): seed it to lead with recommendedTaskId (mapped from any
+        // new-task tempId) so the hub next-move matches the planner's explicit pick.
+        ...(() => {
+          const recId = data.recommendedTaskId ? newTaskIdMap.get(data.recommendedTaskId) ?? data.recommendedTaskId : null;
+          const chain = leadChainWithRecommended(data.dependencyChain, recId);
+          return chain ? { dependencyChain: chain } : {};
+        })()
       };
       await adapter2.createCycle(cycle);
     } catch (err) {
@@ -12596,7 +12725,7 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
     skippedCancellations
   };
 }
-async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker) {
+async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density) {
   const prepareTimer = startTimer();
   tracker?.mark("validate_and_prepare");
   let t = startTimer();
@@ -12657,6 +12786,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     throw new Error("TEMPLATE_BRIEF");
   }
   if (skipHandoffs) context.skipHandoffs = true;
+  if (density) context.density = density;
   tracker?.mark("codebase_scan");
   t = startTimer();
   try {
@@ -12948,7 +13078,6 @@ function defaultHint(tool) {
 function buildSubagentDispatchPrompt(input) {
   const {
     tool,
-    applyMode,
     cycleNumber = 0,
     strategyReviewWarning = "",
     taskId,
@@ -12960,7 +13089,7 @@ function buildSubagentDispatchPrompt(input) {
   const isReview = tool === "review_submit";
   let applyNote;
   if (tool === "plan") {
-    applyNote = `\`plan\` again with mode="apply", llm_response=<sub-agent output>, plan_mode="${applyMode ?? "full"}", cycle_number=${cycleNumber + 1}, strategy_review_warning=${JSON.stringify(strategyReviewWarning)}`;
+    applyNote = `\`plan\` again with mode="apply", llm_response=<sub-agent output>, cycle_number=${cycleNumber + 1}, strategy_review_warning=${JSON.stringify(strategyReviewWarning)}`;
   } else if (tool === "strategy_review") {
     applyNote = `\`strategy_review\` again with mode="apply", llm_response=<sub-agent output>, cycle_number=${cycleNumber}`;
   } else if (tool === "zoom_out") {
@@ -13024,6 +13153,105 @@ Do NOT post-process the sub-agent reply. The apply path expects the full structu
     step2Note
   ].join("\n");
 }
+var REVIEW_PRESETS = {
+  // Minimal gate: does it work, and is every write actually read (AD-74)?
+  gate: ["correctness", "wiring"],
+  // Everything.
+  full: ["correctness", "security", "wiring", "test-quality", "scope-drift"],
+  // Security first, plus correctness and a lighter wiring check.
+  "security-focused": ["security", "correctness", "wiring"]
+};
+var LENS_INSTRUCTIONS = {
+  correctness: "CORRECTNESS lens. Does the change do what the build report claims, without bugs? Hunt logic errors, off-by-one/boundary mistakes, unhandled error branches, null/undefined hazards, race conditions, and wrong assumptions about inputs. Ignore style, security, and scope \u2014 other lenses own those.",
+  security: "SECURITY lens. Any auth/data/secret/injection risk introduced? Check for missing project_id scoping on multi-tenant SQL, RLS bypass via service role, unescaped input, leaked credentials/tokens in logs or responses, and newly-public routes (PUBLIC_PATHS). Ignore correctness/style unless it is the vector for a security issue.",
+  wiring: "WIRING lens (AD-74 \u2014 producer\u2192store\u2192consumer). A write with no reader is NOT done. For every new value produced (state, DB column, event, field), confirm something actually CONSUMES it \u2014 grep for the reader. localStorage is a cache, never a store. Flag decorative writes, dead affordances, and green gates that guard a component nothing imports. Ignore correctness/security details \u2014 focus on whether the data path is actually connected end-to-end.",
+  "test-quality": "TEST-QUALITY lens. Are the tests present and meaningful? A test that cannot fail is worse than none. Check that assertions test TRANSITIONS not snapshots, that a probe would actually go RED if the code broke, and that new behaviour is covered. Flag tests that assert on mocks instead of real behaviour, and missing coverage on the changed paths.",
+  "scope-drift": "SCOPE-DRIFT lens. Does the diff match the BUILD HANDOFF scope? Flag unrelated changes, files touched outside the stated scope, new dependencies/abstractions not asked for, and \u2014 conversely \u2014 acceptance criteria from the handoff that were skipped. Ignore whether the in-scope code is correct; only judge whether it is the RIGHT set of changes."
+};
+var SYNTHESIS_CONTRACT_SHAPE = '{"verdict":"pass|warn|fail","summary":"<one-line consolidated assessment>","findings":[{"severity":"error|warning|info","file":"<path>","line":<number>,"message":"<specific issue>"}]}';
+var LEG_CONTRACT_SHAPE = '{"lens":"<lens-name>","verdict":"pass|warn|fail","findings":[{"severity":"error|warning|info","file":"<path>","line":<number>,"message":"<specific issue>"}]}';
+function legId(lens) {
+  return `leg-${lens}`;
+}
+function buildFanoutReviewDispatchPrompt(input) {
+  const { taskId, preset, systemPrompt, userMessage, contextBytes } = input;
+  const lenses = REVIEW_PRESETS[preset];
+  const n = lenses.length;
+  const sizeNote = contextBytes !== void 0 ? ` \xB7 ~${Math.round(contextBytes / 1024)} KB context` : "";
+  const sharedContext = `<review_rubric>
+${systemPrompt}
+</review_rubric>
+
+<build_under_review>
+${userMessage}
+</build_under_review>`;
+  const legBlocks = lenses.map((lens, i) => {
+    const legPrompt = `You are lens ${i + 1} of ${n} in a PAPI multi-lens build review. Review the completed build below through ONE lens only.
+
+LENS \u2014 ${LENS_INSTRUCTIONS[lens]}
+
+CONTRACT:
+- The build report says what was intended; the diff is what actually changed.
+- Report ONLY findings your lens (${lens}) is responsible for. Do not stray into other lenses.
+- Return ONLY a single JSON object \u2014 no preamble, no commentary, no fences \u2014 in exactly this shape:
+  ${LEG_CONTRACT_SHAPE.replace("<lens-name>", lens)}
+- "pass" = no blocking issues for this lens; "warn" = minor/non-blocking; "fail" = a blocking issue this lens found. \`file\`/\`line\` are optional. Empty \`findings\` is valid when your lens is clean.
+
+${sharedContext}`;
+    return [
+      `#### Lens ${i + 1}/${n} \u2014 ${lens}  \`[${legId(lens)}]\``,
+      "",
+      `<<<BEGIN_LENS_PROMPT:${lens}>>>`,
+      legPrompt,
+      `<<<END_LENS_PROMPT:${lens}>>>`
+    ].join("\n");
+  });
+  const dependsOn = `[${lenses.map(legId).join(", ")}]`;
+  const synthesisPrompt = `You are the SYNTHESIS step of a PAPI multi-lens build review.
+
+depends_on = ${dependsOn}
+
+You receive the JSON outputs of all ${n} specialist lens legs below. Your job:
+- Merge every leg's findings into ONE consolidated review.
+- Dedupe: collapse findings that multiple lenses raised about the same file/line/issue into a single entry (keep the highest severity).
+- Prioritize: order findings most-severe first (error \u2192 warning \u2192 info).
+- Decide ONE overall verdict: "fail" if any leg found a blocking issue, "warn" if only minor nits remain, "pass" if all legs were clean.
+- Return ONLY a single JSON object \u2014 no preamble, no commentary, no fences \u2014 in exactly this shape (the review_submit auto_review contract):
+  ${SYNTHESIS_CONTRACT_SHAPE}
+
+<lens_leg_outputs>
+Paste every lens leg's JSON output here, one per line or concatenated:
+<<<PASTE_ALL_LEG_OUTPUTS_HERE>>>
+</lens_leg_outputs>`;
+  const applyNote = `\`review_submit\` with task_id="${taskId}", stage="build-acceptance", verdict=<your decision: accept / request-changes / reject>, comments=<your reasoning>, and auto_review set to the synthesis JSON object verbatim. The synthesized verdict is a RECOMMENDATION \u2014 you make the final call.`;
+  return [
+    `## PAPI review_submit \u2014 Multi-Lens Fan-Out Review (${taskId} \xB7 preset: ${preset} \xB7 ${n} lens${n === 1 ? "" : "es"} + synthesis${sizeNote})`,
+    "",
+    "This build review fans out across specialist lenses: each lens below reviews the SAME diff in parallel, then a synthesis step dedupes their findings into one prioritized verdict. **PAPI emits this prompt \u2014 YOU (the host) run the Task calls. PAPI never executes the agents itself.**",
+    "",
+    "---",
+    "",
+    `### Step 1 \u2014 Dispatch ${n} specialist lens${n === 1 ? "" : "es"} IN PARALLEL`,
+    "",
+    `Make ${n} \`Task\` call${n === 1 ? "" : "s"} in a SINGLE message so they run concurrently. Each uses \`subagent_type: general-purpose\`. For each lens, pass the prompt block between its BEGIN/END markers (trimmed of the markers). Each leg returns ONLY its own tagged JSON.`,
+    "",
+    legBlocks.join("\n\n"),
+    "",
+    "### Step 2 \u2014 Synthesis (`depends_on` = ALL lens legs)",
+    "",
+    `Wait until ALL ${n} lens legs above have returned. The synthesis step below declares \`depends_on = ${dependsOn}\` \u2014 do NOT run it before every leg is back. Make ONE more \`Task\` call (\`subagent_type: general-purpose\`) with the block below, pasting every leg's JSON output where marked.`,
+    "",
+    "<<<BEGIN_SYNTHESIS_PROMPT>>>",
+    synthesisPrompt,
+    "<<<END_SYNTHESIS_PROMPT>>>",
+    "",
+    "### Step 3 \u2014 Apply the synthesized verdict",
+    "",
+    `When synthesis returns its JSON, surface the consolidated findings, decide your verdict, then call ${applyNote}`,
+    "",
+    "Do NOT post-process the synthesis JSON \u2014 the `auto_review` apply path expects it exactly as emitted."
+  ].join("\n");
+}
 
 // src/lib/resolve-llm-response.ts
 import { readFile as readFile3, stat } from "fs/promises";
@@ -13297,11 +13525,6 @@ var planTool = {
         type: "string",
         description: 'Absolute path to a file containing the plan output (mode "apply" only). Use this when the response is too large to pass as a string parameter (some hosts cap inputs around 50KB). The file must be absolute, exist, and be \u2264500KB. Mutually exclusive with llm_response.'
       },
-      plan_mode: {
-        type: "string",
-        enum: ["bootstrap", "full"],
-        description: 'The plan mode returned from prepare phase (mode "apply" only).'
-      },
       cycle_number: {
         type: "number",
         description: 'The cycle number returned from prepare phase (mode "apply" only).'
@@ -13330,6 +13553,11 @@ var planTool = {
         type: "string",
         description: 'User direction for this cycle \u2014 what to focus on, which phase/tasks to prioritise, or constraints to respect. Overrides the autonomous priority tier system. Example: "Focus on Schema Model phase 9 tasks this cycle".'
       },
+      density: {
+        type: "string",
+        enum: ["light", "standard", "deep"],
+        description: 'Target cycle density \u2014 how many tasks the planner should aim to include. "light" \u2248 2-3 tasks, "standard" \u2248 3-5 (the default when omitted), "deep" \u2248 6-8. A TARGET, not a floor or cap: the planner still honours user direction, pre-assigned tasks, and impact sizing, and plans fewer if fewer genuinely-valuable tasks exist.'
+      },
       force: {
         type: "boolean",
         description: "Bypass planning guards (unreleased cycle block, strategy review hard-block). Only use when explicitly requested by the user."
@@ -13428,6 +13656,7 @@ async function handlePlan(adapter2, config2, args) {
   const focus = typeof args.focus === "string" ? args.focus : void 0;
   const force = args.force === true;
   const handoffsOnly = args.handoffs_only === true;
+  const density = args.density === "light" || args.density === "standard" || args.density === "deep" ? args.density : void 0;
   const tracker = new ProgressTracker(toolMode === "apply" ? "apply_validate" : "prepare_validate").bindStream(adapter2, { stage: "plan" });
   try {
     if (toolMode === "apply") {
@@ -13439,7 +13668,6 @@ async function handlePlan(adapter2, config2, args) {
         return errorResponse(resolved.error);
       }
       const llmResponse = resolved.llmResponse;
-      const planMode = args.plan_mode || "full";
       const rawCycleNumber = args.cycle_number != null ? Number(args.cycle_number) : NaN;
       const strategyReviewWarning = args.strategy_review_warning || "";
       const prep = planPrepareCache.peek(callerKey) ?? loadPrepareSpill(adapter2.getProjectId?.(), callerKey);
@@ -13469,6 +13697,7 @@ async function handlePlan(adapter2, config2, args) {
         );
       }
       const cycleNumber = newCycleNumber - 1;
+      const planMode = determineMode(cycleNumber);
       planPrepareCache.clear(callerKey);
       clearPrepareSpill(adapter2.getProjectId?.(), callerKey);
       let utilisation;
@@ -13500,7 +13729,7 @@ async function handlePlan(adapter2, config2, args) {
       } catch {
       }
       const skipHandoffs = args.skip_handoffs === true;
-      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker);
+      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density);
       const prepareState = {
         contextHashes: result.contextHashes,
         userMessage: result.userMessage,
@@ -13550,7 +13779,6 @@ Follow the system prompt and context below to generate a complete cycle plan.
 When done, call \`plan\` again with:
 - \`mode\`: "apply"
 - \`llm_response\`: your complete output (both parts)
-- \`plan_mode\`: "${result.mode}"
 - \`cycle_number\`: ${result.cycleNumber + 1}
 - \`strategy_review_warning\`: "${result.strategyReviewWarning.replace(/"/g, '\\"')}"
 
@@ -13575,7 +13803,9 @@ ${result.userMessage}
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (message === "TEMPLATE_BRIEF") {
-      return textResponse("Your Product Brief still contains template text. Run `setup` first to generate a real Product Brief for your project.");
+      return textResponse(
+        "Can't plan a full cycle yet \u2014 your Product Brief is still the placeholder template.\n\nPlan mode is derived automatically from your cycle count: your first-ever cycle runs in bootstrap mode (which tolerates a thin brief), and every cycle after that runs in full mode (which needs a real brief to scope work against). This project is past its first cycle, so full mode expected a real brief but found the template text.\n\nFix: run `setup` to generate a real Product Brief for your project, then run `plan` again."
+      );
     }
     const isKnownFriendly = /^(Cannot run plan|Strategy Review gate|No tasks assigned|llm_response is required|cycle_number|Merge conflicts|applyPlan timed out)/i.test(message);
     if (isKnownFriendly) {
@@ -18008,6 +18238,7 @@ async function prepareSetup(adapter2, config2, input) {
       codebaseContext: codebaseSummary
     })
   };
+  const existingDecisions = adapter2.getActiveDecisions ? (await adapter2.getActiveDecisions({ includeRetired: true }).catch(() => [])).filter((a) => !a.superseded).map((a) => `${a.displayId}: ${a.title}`) : [];
   const adSeedPrompt = input.projectType ? {
     system: AD_SEED_SYSTEM,
     user: buildAdSeedPrompt({
@@ -18018,7 +18249,11 @@ async function prepareSetup(adapter2, config2, input) {
       problems: input.problems,
       teamSize: input.teamSize,
       deploymentTarget: input.deploymentTarget,
-      constraints: input.constraints
+      constraints: input.constraints,
+      // task-2811: feed the pre-scanned codebase/decision-doc context so ADs are
+      // extracted from the project's real decisions, not invented generically.
+      codebaseContext: codebaseSummary,
+      existingDecisions: existingDecisions.length > 0 ? existingDecisions : void 0
     })
   } : void 0;
   const conventionsPrompt = input.projectType ? {
@@ -18052,6 +18287,21 @@ async function prepareSetup(adapter2, config2, input) {
       projectType: input.projectType
     })
   } : void 0;
+  const existingNorthStar = adapter2.getCurrentNorthStar ? await adapter2.getCurrentNorthStar().catch(() => null) : null;
+  const northStarAlreadyExists = Boolean(existingNorthStar && existingNorthStar.trim());
+  const northStarPrompt = northStarAlreadyExists ? void 0 : {
+    system: NORTH_STAR_SYSTEM,
+    user: buildNorthStarPrompt({
+      projectName: input.projectName,
+      description: input.description,
+      targetUsers: input.targetUsers,
+      problems: input.problems,
+      codebaseContext: codebaseSummary
+    })
+  };
+  const willGenerateBrief = !effectiveBriefAlreadyExists;
+  const preScanInstruction = willGenerateBrief && isExistingProject && !input.codebaseScan ? buildPreScanInstruction({ hosted: !canScanFilesystem, existingProject: true }) : void 0;
+  const newProjectInstruction = willGenerateBrief && !isExistingProject ? buildNewProjectSetupInstruction({ hosted: !canScanFilesystem }) : void 0;
   return {
     createdProject,
     projectName: input.projectName,
@@ -18059,17 +18309,21 @@ async function prepareSetup(adapter2, config2, input) {
     adSeedPrompt,
     conventionsPrompt,
     initialTasksPrompt,
+    northStarPrompt,
+    northStarAlreadyExists,
     codebaseSummary,
     detectedCodebaseType,
     autoDetected: autoDetected && detectedCodebaseType !== "new_project",
     briefAlreadyExists: effectiveBriefAlreadyExists,
     briefWillRegenerate,
     briefRegenReason,
+    preScanInstruction,
+    newProjectInstruction,
     warnings: warnings.length > 0 ? warnings : void 0,
     filesToWrite: prepareCollector.isEmpty() ? void 0 : prepareCollector
   };
 }
-async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText) {
+async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText, northStarText) {
   const collector = new FileWriteCollector();
   const createdProject = await scaffoldPapiDir(adapter2, config2, input, collector);
   let effectiveBriefText = briefText;
@@ -18096,6 +18350,21 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     }
   }
   const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, collector, effectiveBriefText, adSeedText, conventionsText);
+  let northStarSet = false;
+  const northStarStatement = northStarText?.trim();
+  if (northStarStatement && adapter2.upsertNorthStar) {
+    try {
+      const existing = adapter2.getCurrentNorthStar ? await adapter2.getCurrentNorthStar().catch(() => null) : null;
+      if (!(existing && existing.trim()) || input.force) {
+        await adapter2.upsertNorthStar(northStarStatement, 0);
+        northStarSet = true;
+      }
+    } catch (err) {
+      warnings.push(
+        `North Star not saved \u2014 ${err instanceof Error ? err.message : String(err)}. Set one later during your first \`plan\`.`
+      );
+    }
+  }
   let createdTasks = 0;
   let tasksSkipped = 0;
   if (initialTasksText?.trim()) {
@@ -18241,6 +18510,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     seededAds,
     createdTasks,
     tasksSkipped: tasksSkipped > 0 ? tasksSkipped : void 0,
+    northStarSet: northStarSet || void 0,
     briefRegenerated: briefRegenerated || void 0,
     cursorScaffolded,
     gitignoreNote,
@@ -18299,6 +18569,10 @@ var setupTool = {
         type: "string",
         description: 'Your generated conventions markdown to append to CLAUDE.md (mode "apply" only). Optional.'
       },
+      north_star_response: {
+        type: "string",
+        description: `The project's North Star statement \u2014 one or two sentences (mode "apply" only). Provide the statement you extracted from the docs or agreed with the user in response to the prepare-phase North Star prompt. Optional; omit when the project already has one.`
+      },
       project_name: {
         type: "string",
         description: "Name of the project."
@@ -18408,6 +18682,9 @@ function formatSuccessResponse(result, constraints, writesClaudeMd = true) {
   const adNote = result.seededAds > 0 ? `
 
 ${result.seededAds} Active Decision${result.seededAds > 1 ? "s" : ""} seeded based on project type \u2014 review them with \`strategy_review\` after your first cycle.` : "";
+  const northStarNote = result.northStarSet ? `
+
+\u2B50 North Star set \u2014 your project starts steered (no "define a North Star" warning on \`orient\`).` : "";
   const taskNote = result.createdTasks > 0 || (result.tasksSkipped ?? 0) > 0 ? (() => {
     const created = result.createdTasks > 0 ? `${result.createdTasks} initial backlog task${result.createdTasks > 1 ? "s" : ""} created` : "";
     const skipped = (result.tasksSkipped ?? 0) > 0 ? `${result.tasksSkipped} duplicate${(result.tasksSkipped ?? 0) > 1 ? "s" : ""} skipped` : "";
@@ -18427,7 +18704,7 @@ ${[created, skipped].filter(Boolean).join(", ")}.${idea}`;
 ${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
   const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
   return textResponse(
-    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}
+    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}
 
 **Important:** Setup created/modified files (${harnessFiles}, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.
 
@@ -18460,8 +18737,9 @@ PAPI needs the project name. Description and target users are optional \u2014 th
       const adSeedResponse = args.ad_seed_response;
       const conventionsResponse = args.conventions_response;
       const initialTasksResponse = args.initial_tasks_response;
+      const northStarResponse = args.north_star_response;
       tracker.mark("apply_setup_writeback");
-      const result = await applySetup(adapter2, config2, input, briefResponse, adSeedResponse, conventionsResponse, initialTasksResponse);
+      const result = await applySetup(adapter2, config2, input, briefResponse, adSeedResponse, conventionsResponse, initialTasksResponse, northStarResponse);
       tracker.mark("apply_format_response");
       return formatSuccessResponse(result, args.constraints, writesClaudeMd);
     }
@@ -18517,7 +18795,13 @@ PAPI needs the project name. Description and target users are optional \u2014 th
           ""
         );
       }
-      if (result.briefPrompt && !result.briefAlreadyExists) {
+      if (result.preScanInstruction) {
+        sections.push(result.preScanInstruction, "");
+      }
+      if (result.newProjectInstruction) {
+        sections.push(result.newProjectInstruction, "");
+      }
+      if (!result.preScanInstruction && !result.newProjectInstruction && result.briefPrompt && !result.briefAlreadyExists) {
         sections.push(
           `**\u{1F4C4} Before you write the brief \u2014 does the user already have a PRD, brief, spec, or design doc?**`,
           `A brief generated from the user's real spec produces a far better first plan than a generic scaffold.`,
@@ -18534,6 +18818,7 @@ PAPI needs the project name. Description and target users are optional \u2014 th
         result.briefPrompt ? `- \`brief_response\`: your Product Brief markdown` : "",
         result.adSeedPrompt ? `- \`ad_seed_response\`: your AD seed JSON array` : "",
         result.conventionsPrompt ? `- \`conventions_response\`: your conventions markdown` : "",
+        result.northStarPrompt ? `- \`north_star_response\`: the North Star statement (confirm it with the user first)` : "",
         result.initialTasksPrompt ? `- \`initial_tasks_response\`: your initial tasks JSON array` : "",
         `- Plus all the original setup fields (project_name, description, target_users${isExisting ? ", existing_project: true" : ""})`,
         "",
@@ -18586,6 +18871,25 @@ ${result.conventionsPrompt.system}
           "",
           `<context>
 ${result.conventionsPrompt.user}
+</context>`
+        );
+      }
+      if (result.northStarPrompt) {
+        sectionNum++;
+        sections.push(
+          "",
+          `---`,
+          "",
+          `### ${sectionNum}. North Star`,
+          "",
+          `This project has no North Star yet \u2014 define one now so it starts steered (otherwise \`orient\` will warn that none is set). Extract it from the docs if one is already stated there; otherwise propose one and **confirm it with the user** before applying. Return it as \`north_star_response\`.`,
+          "",
+          `<system_prompt>
+${result.northStarPrompt.system}
+</system_prompt>`,
+          "",
+          `<context>
+${result.northStarPrompt.user}
 </context>`
         );
       }
@@ -20868,6 +21172,7 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     completed: capitalizeCompleted(input.completed),
     actualEffort: input.effort,
     estimatedEffort: input.estimatedEffort,
+    model: input.model,
     surprises: input.surprises,
     discoveredIssues: input.discoveredIssues,
     architectureNotes: input.architectureNotes,
@@ -21804,6 +22109,11 @@ var buildExecuteTool = {
         enum: ["XS", "S", "M", "L", "XL"],
         description: "Estimated effort from the BUILD HANDOFF. Required for complete."
       },
+      model: {
+        type: "string",
+        maxLength: 120,
+        description: "The model/agent that executed this build, self-reported, e.g. 'claude-opus-4' / 'gpt-5' \u2014 optional; powers attributed-intelligence analytics. PAPI never selects a model (AD-58) \u2014 report the model YOU are running as."
+      },
       surprises: {
         type: "string",
         maxLength: 800,
@@ -21812,7 +22122,7 @@ var buildExecuteTool = {
       discovered_issues: {
         type: "string",
         maxLength: 800,
-        description: `Problems found DURING this build that are OUTSIDE this task's scope. Include severity (P0-P3). Good: "P2: Auth middleware doesn't validate token expiry \u2014 affects all protected routes." Bad: "Had to install a dependency." Only real bugs or gaps that need their own task. Use "None" if none. Required for complete. TIP: When submitting a follow-up idea for a discovered issue, include "learning:<uuid>" in the idea notes to link it to this cycle learning entry \u2014 use the UUID returned in the build completion output.`
+        description: `A REAL bug or gap OUTSIDE this task's scope that needs its own task. Include severity (P0-P3). INCLUSION TEST \u2014 file it only if BOTH are true: (1) the bug would exist even if this task had never run, and (2) it is outside this task's scope. If either is false, it is NOT a discovered_issue. NEVER file a trivial in-file cleanup you noticed while editing (an em-dash tidy, a rename, a lint nit, a stray console.log) \u2014 those are not bugs, just clean them up or leave them. Good: "P2: Auth middleware doesn't validate token expiry \u2014 affects all protected routes." Bad: "Two em dashes remain in the file" / "Had to install a dependency." Use "None" if none. Required for complete. TIP: When submitting a follow-up idea for a discovered issue, include "learning:<uuid>" in the idea notes to link it to this cycle learning entry \u2014 use the UUID returned in the build completion output.`
       },
       architecture_notes: {
         type: "string",
@@ -22098,7 +22408,7 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
 **PRE-BUILD VERIFICATION:** Before writing any code, read these files and check if the functionality already exists:
 ${verificationFiles.map((f) => `- ${f}`).join("\n")}
 If >80% of the scope is already implemented, call \`build_execute\` with completed="yes" and note "already built" in surprises instead of re-implementing.` : "";
-    const chainInstruction = '\n\n---\n\n**IMPORTANT:** After implementing this task, immediately call `build_execute` again with report fields (`completed`, `effort`, `estimated_effort`, `surprises`, `discovered_issues`, `architecture_notes`) to complete the build. Do not wait for user confirmation.\n\n**Build Report Quality Bar:**\n- **surprises**: What was DIFFERENT from expected \u2014 wrong assumptions, scope changes, missing infrastructure. NOT implementation mechanics ("used X library").\n- **discovered_issues**: Bugs/gaps OUTSIDE this task\'s scope, with severity (P0-P3). NOT "had to install a dependency".\n- **architecture_notes**: Patterns/decisions that AFFECT FUTURE WORK. NOT "used React hooks".\n- If nothing meaningful to report for a field, use "None" \u2014 empty signal is better than noise.\n- **dead_ends**: approaches you tried and RULED OUT (with why). Ruled-out paths are first-class intelligence \u2014 send "None" only if nothing you tried failed.';
+    const chainInstruction = '\n\n---\n\n**IMPORTANT:** After implementing this task, immediately call `build_execute` again with report fields (`completed`, `effort`, `estimated_effort`, `surprises`, `discovered_issues`, `architecture_notes`) to complete the build. Do not wait for user confirmation.\n\n**Build Report Quality Bar:**\n- **surprises**: What was DIFFERENT from expected \u2014 wrong assumptions, scope changes, missing infrastructure. NOT implementation mechanics ("used X library").\n- **discovered_issues**: REAL bugs/gaps OUTSIDE this task\'s scope, with severity (P0-P3). Inclusion test: file it only if the bug would exist even if this task had never run AND it is outside this task\'s scope. NEVER a trivial in-file cleanup you noticed while editing (em-dash tidy, rename, lint nit) \u2014 those are not discovered_issues. NOT "had to install a dependency".\n- **architecture_notes**: Patterns/decisions that AFFECT FUTURE WORK. NOT "used React hooks".\n- If nothing meaningful to report for a field, use "None" \u2014 empty signal is better than noise.\n- **dead_ends**: approaches you tried and RULED OUT (with why). Ruled-out paths are first-class intelligence \u2014 send "None" only if nothing you tried failed.';
     const buildDisciplineNote = "\n\n---\n\n**BUILD DISCIPLINE:**\n- **Read before you claim.** Before asserting how something works \u2014 or that it is already done \u2014 read the actual code/state. Don't rely on memory or earlier context.\n- **Sweep existing material first.** Check the docs (`doc_search` or your docs index) and prior tasks, not just whether a file exists \u2014 the work may already be covered.\n- **Ranged reads.** For large or unfamiliar files, read the relevant range rather than the whole file.";
     let adSection = "";
     try {
@@ -22174,6 +22484,7 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
   const completed = args.completed;
   const effort = args.effort;
   const estimatedEffort = args.estimated_effort;
+  const model = typeof args.model === "string" && args.model.trim() !== "" ? args.model.trim() : void 0;
   const surprises = args.surprises;
   const discoveredIssues = args.discovered_issues;
   const architectureNotes = args.architecture_notes;
@@ -22229,6 +22540,7 @@ async function handleExecuteComplete(adapter2, config2, taskId, args, light = fa
       completed,
       effort: parsedEffort,
       estimatedEffort: parsedEstimatedEffort,
+      model,
       surprises,
       discoveredIssues,
       architectureNotes,
@@ -23877,7 +24189,7 @@ var REVIEW_RUBRIC = [
   "- Quality: tests present and meaningful, no obvious debt or dead code.",
   "Be specific and cite file/line where you can. Recommend fail only for blocking issues."
 ].join("\n");
-async function buildReviewDispatch(adapter2, config2, taskId) {
+async function assembleReviewContext(adapter2, config2, taskId) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
     return { ok: false, error: `Task ${taskId} not found \u2014 cannot assemble review context.` };
@@ -23910,13 +24222,13 @@ ${report}
 
 ${diffBlock}`;
   const contextBytes = Buffer.byteLength(userMessage, "utf-8");
-  const prompt2 = buildSubagentDispatchPrompt({
-    tool: "review_submit",
-    taskId,
-    systemPrompt: REVIEW_RUBRIC,
-    userMessage,
-    contextBytes
-  });
+  return { ok: true, userMessage, contextBytes };
+}
+async function buildReviewDispatch(adapter2, config2, taskId, preset) {
+  const ctx = await assembleReviewContext(adapter2, config2, taskId);
+  if (!ctx.ok) return ctx;
+  const { userMessage, contextBytes } = ctx;
+  const prompt2 = preset ? buildFanoutReviewDispatchPrompt({ taskId, preset, systemPrompt: REVIEW_RUBRIC, userMessage, contextBytes }) : buildSubagentDispatchPrompt({ tool: "review_submit", taskId, systemPrompt: REVIEW_RUBRIC, userMessage, contextBytes });
   return { ok: true, prompt: prompt2, contextBytes };
 }
 var reviewListTool = {
@@ -23968,6 +24280,11 @@ var reviewSubmitTool = {
         enum: ["inline", "subagent"],
         description: `task-1864: set "subagent" (build-acceptance only) to offload code review to a fresh sub-agent. Returns a Task() invocation prompt that feeds the build report + branch diff to the sub-agent, which returns structured auto_review findings. Verdict is NOT required on this call \u2014 you call review_submit again with the human verdict + the sub-agent's auto_review. Default "inline" (record the verdict directly).`
       },
+      review_preset: {
+        type: "string",
+        enum: ["gate", "full", "security-focused"],
+        description: 'task-2824 (opt-in): upgrade the sub-agent dispatch to a MULTI-LENS fan-out. Requires dispatch:"subagent" (build-acceptance only). Emits N specialist lens legs (correctness/security/wiring/test-quality/scope-drift) that review the same diff in parallel, plus a synthesis leg that dedupes their findings into ONE prioritized auto_review verdict. "gate" = correctness+wiring, "full" = all 5, "security-focused" = security+correctness+wiring. Omit for the existing single-lens review (unchanged default).'
+      },
       reviewer_confirmed: {
         type: "boolean",
         description: "Set to true to confirm you have reviewed the build (read the build report or the pending list via review_list) before submitting an accept verdict. Required to accept a build-acceptance review unless review_list was called in the same session within the last 15 minutes. Defense-in-depth against SUP-2026-010 (Codex prematurely accepted a task because review_list was missing from its tool surface)."
@@ -24182,11 +24499,24 @@ async function handleReviewSubmit(adapter2, config2, args) {
     caps = {};
   }
   const explicitDispatch = args.dispatch === "subagent";
+  const rawPreset = args.review_preset;
+  const reviewPreset = typeof rawPreset === "string" && rawPreset in REVIEW_PRESETS ? rawPreset : void 0;
+  if (rawPreset !== void 0 && !explicitDispatch) {
+    return errorResponse('review_preset requires dispatch:"subagent" (multi-lens fan-out is only available on an explicit sub-agent dispatch).');
+  }
+  if (typeof rawPreset === "string" && rawPreset.length > 0 && !reviewPreset) {
+    return errorResponse(`review_preset "${rawPreset}" is not valid. Use "gate", "full", or "security-focused".`);
+  }
   const autoDispatchOptIn = args.dispatch !== "inline" && process.env.PAPI_AUTO_DISPATCH !== "false" && isCapabilityEnabled(caps, "prReviewer");
   const autoDispatchEligible = !verdict && autoDispatchOptIn;
   const capabilityAutoReviewEligible = verdict === "accept" && !autoReview && autoDispatchOptIn;
   if ((explicitDispatch || autoDispatchEligible || capabilityAutoReviewEligible) && stage === "build-acceptance" && taskId) {
-    const dispatch = await buildReviewDispatch(adapter2, config2, taskId);
+    const dispatch = await buildReviewDispatch(
+      adapter2,
+      config2,
+      taskId,
+      explicitDispatch ? reviewPreset : void 0
+    );
     if (!dispatch.ok) {
       if (explicitDispatch) return errorResponse(dispatch.error);
     } else if (explicitDispatch || capabilityAutoReviewEligible || dispatch.contextBytes > REVIEW_DISPATCH_THRESHOLD) {

package/dist/prompts.js

@@ -236,7 +236,7 @@ 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\` (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.
+   - DELIVERABLE FORMAT: What the output looks like \u2014 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.
    Add to ACCEPTANCE CRITERIA: "[ ] Deliverable format confirmed with Owner before starting" and "[ ] Design output is self-contained \u2014 includes enough context for a developer to implement without further clarification."`;
@@ -435,6 +435,21 @@ function buildPlanFullInstructionsConditional(flags, ctx) {
   if (!flags || !ctx) return PLAN_FULL_INSTRUCTIONS;
   return composeFullModeInstructions(flags, ctx);
 }
+var CYCLE_DENSITY_TARGETS = {
+  light: { label: "Light", range: "2-3" },
+  standard: { label: "Standard", range: "3-5" },
+  deep: { label: "Deep", range: "6-8" }
+};
+function buildCycleDensityDirective(density) {
+  if (!density) return "";
+  const target = CYCLE_DENSITY_TARGETS[density];
+  return [
+    `## CYCLE DENSITY: ${target.label}`,
+    "",
+    `The user set this cycle's density to **${density}** \u2014 aim for roughly **${target.range} tasks** this cycle.`,
+    `This is a TARGET to size toward, not a hard floor or cap: still honour explicit user direction, any pre-assigned tasks, and impact-based sizing. If fewer genuinely-valuable tasks exist, plan fewer \u2014 do NOT pad the cycle to hit the number.`
+  ].join("\n");
+}
 function buildPlanUserMessage(ctx) {
   const modeLabel = ctx.mode.toUpperCase();
   const parts = [
@@ -452,6 +467,10 @@ function buildPlanUserMessage(ctx) {
       ""
     );
   }
+  const densityDirective = buildCycleDensityDirective(ctx.density);
+  if (densityDirective) {
+    parts.push(densityDirective, "");
+  }
   if (ctx.mode === "bootstrap") {
     parts.push(PLAN_BOOTSTRAP_INSTRUCTIONS);
   } else {
@@ -1327,15 +1346,49 @@ phases:
 
 *No decisions locked yet. These are added as planning cycles confirm strategic choices.*`;
 }
+function buildPreScanInstruction(opts) {
+  const docRouting = opts.hosted ? "paste the relevant content (decision records, roadmap, spec excerpts) directly into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "pass local doc file paths as `sources` (comma-separated), or paste content into `description`.";
+  return [
+    `**\u{1F50E} Before you generate anything \u2014 scan the project and gather real context.**`,
+    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name. You (the agent running this) have local access that PAPI does not \u2014 do the gathering, then pass it back.`,
+    ``,
+    `1. **Confirm the environment.** Check that you are running from the root of this project's dev environment \u2014 the folder that holds its source, git history, and docs. If you are not there, or you are connected over a remote connector with no access to the user's files, say so and ask the user where the project lives before continuing.`,
+    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call.`,
+    `3. **Scan the docs.** Look through \`docs/\`, design notes, ADRs/decision records, and any roadmap or planning files \u2014 not just code.`,
+    `4. **Check for sibling / separate repos.** Many projects span more than one repo (a separate frontend, backend, infra, or mobile repo, or other packages in a monorepo). Ask the user whether any related repos or directories exist, and scan those too.`,
+    `5. **Ask the user to point you at extra context.** Prompt them: "Is there anything else I should read before setting this up \u2014 a PRD or spec, decision records, a roadmap, or links to related repos or docs?" Fold whatever they share into the scan.`,
+    `6. **Re-run \`setup\` with what you gathered:** pass the code scan as \`codebase_scan\`; for docs, decision records, and roadmap, ${docRouting} Then answer the prompts below.`,
+    ``,
+    `If there is genuinely no code and no docs yet, skip this and generate from what the user tells you \u2014 the zero-context path is fully supported.`
+  ].join("\n");
+}
+var PAPI_DOCS_QUICKSTART_URL = "https://getpapi.ai/docs/guide/quick-start";
+var PAPI_PUBLIC_REPO_URL = "https://github.com/getpapi/papi";
+function buildNewProjectSetupInstruction(opts) {
+  const visionRouting = opts.hosted ? "paste anything they share (notes, a PRD, links) into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "fold anything they share (notes, a PRD, a sketch, links) into `description`, or pass local doc paths as `sources`.";
+  return [
+    `**\u{1F331} New project \u2014 start from the vision.**`,
+    `There's no existing code to mine, so setup builds from what the user wants to create. Do two things before answering the prompts below.`,
+    ``,
+    `1. **Get oriented on PAPI.** So you can guide the user well \u2014 whatever assistant you are \u2014 skim the quick-start docs at ${PAPI_DOCS_QUICKSTART_URL} and the public repo at ${PAPI_PUBLIC_REPO_URL}. They explain the plan \u2192 build \u2192 review cycle the user will run after setup.`,
+    `2. **Draw out the vision with the user.** Ask what they're building and for whom, the core problem it solves, and what success looks like \u2014 enough to write a real brief, a North Star, and a starter backlog rather than a generic scaffold. If they already have a PRD, sketch, notes, or links, ${visionRouting}`,
+    ``,
+    `Then answer the prompts below to generate the brief, decisions, North Star, and a vision-first starter backlog.`
+  ].join("\n");
+}
 var AD_SEED_SYSTEM = `You are a technical architect seeding initial Active Decisions for a new software project managed by PAPI.
 
 Active Decisions (ADs) are documented architectural choices with confidence levels. They guide the planner and builder agents \u2014 without ADs, planning output is generic and unhelpful.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce decisions directly.
 
+## SOURCE OF TRUTH \u2014 extract real decisions first
+
+If the context includes decision records, ADRs, a roadmap, a README, or codebase analysis, your PRIMARY job is to EXTRACT the real, already-made decisions from that material \u2014 not to invent generic ones. Read the provided context and capture each load-bearing choice the project has actually made (its stack, data model, architecture, positioning, deployment posture). Only fall back to informed defaults for a project of this type when the context contains no evidenced decisions.
+
 ## OUTPUT FORMAT
 
-Return a JSON array of 3-5 Active Decisions. Each AD must have:
+Return a JSON array of Active Decisions \u2014 ONE per real decision you find. Each AD must have:
 - "id": "AD-1", "AD-2", etc.
 - "body": Full markdown block including ### heading, confidence tag, and body text
 
@@ -1349,17 +1402,20 @@ The body format for each AD:
 
 ## GUIDELINES
 
-- All seeded ADs should have Confidence: MEDIUM (they are informed defaults, not confirmed choices)
-- Focus on decisions that genuinely differ by project type \u2014 avoid generic truisms
-- Each AD should be actionable and falsifiable (something the team could decide differently)
+- **Count follows the evidence \u2014 there is NO fixed target.** Seed as many ADs as there are real, distinct decisions in the material. Do NOT pad to a number, and do NOT fabricate decisions to hit a count. When the context has no evidenced decisions, return a small set (2-4) of informed defaults for this project type.
+- **Confidence reflects evidence:** a decision explicitly documented as settled in the source may be HIGH; an informed default you inferred stays MEDIUM.
+- Never mint an AD that is not a genuine stance-with-alternatives \u2014 a preference, a fact, or a config value is NOT an AD.
+- Focus on decisions that genuinely differ by project \u2014 avoid generic truisms.
+- Each AD should be actionable and falsifiable (something the team could decide differently).
 - Cover different concerns: architecture, data, deployment, testing strategy, API design, etc.
-- Keep each AD body to 4-6 lines \u2014 concise and scannable
+- Keep each AD body to 4-6 lines \u2014 concise and scannable.
+- **Do NOT duplicate** any decision already listed as an existing Active Decision in the context \u2014 skip it entirely.
 - **Quality bar:** ADs are for product and architecture choices that constrain future work \u2014 technology selections, data model designs, UX principles, strategic positioning. They are NOT for process preferences, configuration choices, or temporary workarounds.
 
 Return ONLY valid JSON \u2014 no preamble, no code fences, no explanation.`;
 function buildAdSeedPrompt(ctx) {
   const parts = [
-    `Generate 3-5 Active Decisions for this project.`,
+    ctx.codebaseContext ? `Extract the real Active Decisions for this project from the context below. Seed one AD per genuine decision \u2014 do not cap the count, and do not fabricate.` : `Seed the informed default Active Decisions for this project (no decision docs were supplied \u2014 infer sensible MEDIUM-confidence defaults for this project type).`,
     "",
     `**Project:** ${ctx.projectName}`,
     `**Type:** ${ctx.projectType}`,
@@ -1372,12 +1428,57 @@ function buildAdSeedPrompt(ctx) {
   if (ctx.constraints) {
     parts.push(`**Constraints:** ${ctx.constraints}`);
   }
+  if (ctx.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract the real decisions from here",
+      ctx.codebaseContext
+    );
+  }
+  if (ctx.existingDecisions && ctx.existingDecisions.length > 0) {
+    parts.push(
+      "",
+      "## Existing Active Decisions \u2014 do NOT duplicate these",
+      ...ctx.existingDecisions.map((d) => `- ${d}`)
+    );
+  }
   parts.push(
     "",
     'Return a JSON array of AD objects with "id" and "body" fields. No other text.'
   );
   return parts.join("\n");
 }
+var NORTH_STAR_SYSTEM = `You are helping a builder define the North Star for a software project set up with PAPI.
+
+A North Star is the ONE outcome that best captures whether the project is succeeding \u2014 a single, measurable, user-centred statement the team can steer by. It is not a feature list and not a vision paragraph.
+
+IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions in your output.
+
+## HOW TO PRODUCE IT
+- If the provided context (brief, docs, decision records) ALREADY states a North Star, goal metric, or primary success measure, EXTRACT and restate it \u2014 do not invent a competing one.
+- Otherwise, PROPOSE the most fitting North Star from the project's purpose and users. (The calling agent will confirm it with the user before it is saved.)
+
+## OUTPUT FORMAT
+Return ONLY the North Star statement \u2014 one or two sentences, concrete and measurable where possible. No heading, no preamble, no quotes, no code fences.`;
+function buildNorthStarPrompt(inputs) {
+  const parts = [
+    `Define the North Star for this project.`,
+    "",
+    `**Project:** ${inputs.projectName}`,
+    `**Description:** ${inputs.description?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Target users:** ${inputs.targetUsers?.trim() || "(not provided \u2014 infer from context below)"}`,
+    `**Problems solved:** ${inputs.problems}`
+  ];
+  if (inputs.codebaseContext) {
+    parts.push(
+      "",
+      "## Project context \u2014 extract an existing North Star from here if one is stated",
+      inputs.codebaseContext
+    );
+  }
+  parts.push("", "Return only the North Star statement.");
+  return parts.join("\n");
+}
 var CONVENTIONS_SYSTEM = `You are a senior software engineer generating CLAUDE.md coding conventions for a new project.
 
 IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce conventions directly.
@@ -1497,9 +1598,13 @@ export {
   AD_REJECTION_RULES,
   AD_SEED_SYSTEM,
   CONVENTIONS_SYSTEM,
+  CYCLE_DENSITY_TARGETS,
   HANDOFF_REGEN_SYSTEM,
   INITIAL_TASKS_SYSTEM,
+  NORTH_STAR_SYSTEM,
   OUTPUT_QUALITY_RUBRIC,
+  PAPI_DOCS_QUICKSTART_URL,
+  PAPI_PUBLIC_REPO_URL,
   PLAN_BOOTSTRAP_INSTRUCTIONS,
   PLAN_FULL_INSTRUCTIONS,
   PLAN_SYSTEM,
@@ -1509,11 +1614,15 @@ export {
   VISION_TASKS_SYSTEM,
   buildAdSeedPrompt,
   buildConventionsPrompt,
+  buildCycleDensityDirective,
   buildHandoffRegenMessage,
   buildHandoffsOnlyUserMessage,
   buildInitialTasksPrompt,
+  buildNewProjectSetupInstruction,
+  buildNorthStarPrompt,
   buildPlanFullInstructionsConditional,
   buildPlanUserMessage,
+  buildPreScanInstruction,
   buildProductBriefPrompt,
   buildReviewSystemPrompt,
   buildReviewUserMessage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.59",
+  "version": "0.7.61",
   "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",