@papi-ai/server 0.5.0 → 0.5.1

package/dist/index.js

@@ -280,6 +280,9 @@ function splitSections(text) {
 function parseBulletList(text) {
   return text.split("\n").map((l) => l.replace(/^\s*-\s*/, "").trim()).filter((l) => l.length > 0);
 }
+function parseBulletsOnly(text) {
+  return text.split("\n").filter((l) => /^\s*-\s/.test(l)).map((l) => l.replace(/^\s*-\s*/, "").trim()).filter((l) => l.length > 0);
+}
 function parseChecklist(text) {
   return text.split("\n").map((l) => l.replace(/^\s*\[[ x]]\s*/, "").trim()).filter((l) => l.length > 0);
 }
@@ -314,6 +317,7 @@ function parseBuildHandoff(markdown) {
     scopeBoundary: parseBulletList(sections.get("SCOPE BOUNDARY (DO NOT DO THIS)") ?? ""),
     acceptanceCriteria: parseChecklist(sections.get("ACCEPTANCE CRITERIA") ?? ""),
     securityConsiderations: (sections.get("SECURITY CONSIDERATIONS") ?? "").trim(),
+    verificationFiles: parseBulletsOnly(sections.get("PRE-BUILD VERIFICATION") ?? ""),
     filesLikelyTouched: parseBulletList(sections.get("FILES LIKELY TOUCHED") ?? ""),
     effort
   };
@@ -345,6 +349,15 @@ function serializeBuildHandoff(handoff) {
   lines.push("");
   lines.push("SECURITY CONSIDERATIONS");
   lines.push(handoff.securityConsiderations);
+  if (handoff.verificationFiles && handoff.verificationFiles.length > 0) {
+    lines.push("");
+    lines.push("PRE-BUILD VERIFICATION");
+    lines.push("Before implementing, read these files and check if the functionality already exists:");
+    for (const item of handoff.verificationFiles) {
+      lines.push(`- ${item}`);
+    }
+    lines.push('If >80% of the scope is already implemented, call build_execute with completed="yes" and note "already built" in surprises instead of re-implementing.');
+  }
   lines.push("");
   lines.push("FILES LIKELY TOUCHED");
   for (const item of handoff.filesLikelyTouched) {
@@ -1422,6 +1435,7 @@ var init_dist2 = __esm({
       "SCOPE BOUNDARY (DO NOT DO THIS)",
       "ACCEPTANCE CRITERIA",
       "SECURITY CONSIDERATIONS",
+      "PRE-BUILD VERIFICATION",
       "FILES LIKELY TOUCHED",
       "EFFORT"
     ];
@@ -4540,7 +4554,7 @@ function rowToDecisionScore(row) {
     createdAt: row.created_at
   };
 }
-function rowToSprintLogEntry(row) {
+function rowToCycleLogEntry(row) {
   const entry = {
     uuid: row.id,
     cycleNumber: row.cycle_number,
@@ -6133,14 +6147,14 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
         ORDER BY cycle_number DESC
         LIMIT ${limit}
       `;
-          return rows2.map(rowToSprintLogEntry);
+          return rows2.map(rowToCycleLogEntry);
         }
         const rows = await this.sql`
       SELECT * FROM planning_log_entries
       WHERE project_id = ${this.projectId}
       ORDER BY cycle_number DESC
     `;
-        return rows.map(rowToSprintLogEntry);
+        return rows.map(rowToCycleLogEntry);
       }
       async getCycleLogSince(cycleNumber) {
         const rows = await this.sql`
@@ -6149,7 +6163,7 @@ EXCEPTION WHEN duplicate_object THEN NULL; END $$;
         AND cycle_number >= ${cycleNumber}
       ORDER BY cycle_number DESC
     `;
-        return rows.map(rowToSprintLogEntry);
+        return rows.map(rowToCycleLogEntry);
       }
       async setCycleHealth(updates) {
         if (updates.boardHealth != null || updates.strategicDirection != null) {
@@ -6243,7 +6257,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
                board_health, strategic_direction, full_analysis,
                velocity_assessment, structured_data, created_at
         FROM strategy_reviews
-        WHERE project_id = ${this.projectId}
+        WHERE project_id = ${this.projectId} AND cycle_number > 0
         ORDER BY cycle_number DESC
         LIMIT ${limit}
       `;
@@ -6283,6 +6297,139 @@ ${newParts.join("\n")}` : newParts.join("\n");
           createdAt: r.created_at ?? void 0
         }));
       }
+      async savePendingReviewResponse(cycleNumber, rawResponse) {
+        await this.sql`
+      INSERT INTO strategy_reviews (
+        project_id, cycle_number, title, content, full_analysis
+      ) VALUES (
+        ${this.projectId}, ${0}, ${"[PENDING] Strategy Review"}, ${"Pending write-back retry"}, ${rawResponse}
+      )
+      ON CONFLICT (project_id, cycle_number)
+      DO UPDATE SET
+        full_analysis = ${rawResponse},
+        notes = ${`original_cycle:${cycleNumber}`}
+    `;
+      }
+      async getPendingReviewResponse() {
+        const rows = await this.sql`
+      SELECT full_analysis, notes FROM strategy_reviews
+      WHERE project_id = ${this.projectId} AND cycle_number = 0
+      LIMIT 1
+    `;
+        if (rows.length === 0 || !rows[0].full_analysis) return null;
+        const cycleMatch = rows[0].notes?.match(/original_cycle:(\d+)/);
+        const cycleNumber = cycleMatch ? parseInt(cycleMatch[1], 10) : 0;
+        return { cycleNumber, rawResponse: rows[0].full_analysis };
+      }
+      async clearPendingReviewResponse() {
+        await this.sql`
+      DELETE FROM strategy_reviews
+      WHERE project_id = ${this.projectId} AND cycle_number = 0
+    `;
+      }
+      // -------------------------------------------------------------------------
+      // Doc Registry
+      // -------------------------------------------------------------------------
+      async registerDoc(entry) {
+        const [row] = await this.sql`
+      INSERT INTO doc_registry (
+        project_id, title, type, path, status, summary, tags,
+        cycle_created, cycle_updated, superseded_by, actions
+      ) VALUES (
+        ${this.projectId}, ${entry.title}, ${entry.type}, ${entry.path},
+        ${entry.status}, ${entry.summary}, ${entry.tags},
+        ${entry.cycleCreated}, ${entry.cycleUpdated ?? null},
+        ${entry.supersededBy ?? null},
+        ${entry.actions ? JSON.stringify(entry.actions) : "[]"}
+      )
+      ON CONFLICT (project_id, path)
+      DO UPDATE SET
+        title = EXCLUDED.title,
+        type = EXCLUDED.type,
+        status = EXCLUDED.status,
+        summary = EXCLUDED.summary,
+        tags = EXCLUDED.tags,
+        cycle_updated = EXCLUDED.cycle_updated,
+        superseded_by = EXCLUDED.superseded_by,
+        actions = EXCLUDED.actions,
+        updated_at = now()
+      RETURNING id, created_at, updated_at
+    `;
+        return {
+          ...entry,
+          id: row.id,
+          createdAt: row.created_at,
+          updatedAt: row.updated_at
+        };
+      }
+      async searchDocs(input) {
+        const status = input.status ?? "active";
+        const limit = input.limit ?? 10;
+        const keyword = input.keyword ? `%${input.keyword}%` : null;
+        const sinceCycle = input.sinceCycle ?? 0;
+        const hasPending = input.hasPendingActions ?? false;
+        const rows = await this.sql`
+      SELECT * FROM doc_registry
+      WHERE project_id = ${this.projectId}
+        AND status = ${status}
+        AND (${input.type ?? null}::text IS NULL OR type = ${input.type ?? null})
+        AND (${keyword}::text IS NULL OR (title ILIKE ${keyword} OR summary ILIKE ${keyword}))
+        AND (${sinceCycle} = 0 OR COALESCE(cycle_updated, cycle_created) >= ${sinceCycle})
+        AND (${hasPending} = false OR actions::text LIKE '%"pending"%')
+        AND (${input.tags ?? []}::text[] = '{}' OR tags && ${input.tags ?? []})
+      ORDER BY COALESCE(cycle_updated, cycle_created) DESC
+      LIMIT ${limit}
+    `;
+        return rows.map((r) => ({
+          id: r.id,
+          title: r.title,
+          type: r.type,
+          path: r.path,
+          status: r.status,
+          summary: r.summary,
+          tags: r.tags ?? [],
+          cycleCreated: r.cycle_created,
+          cycleUpdated: r.cycle_updated ?? void 0,
+          supersededBy: r.superseded_by ?? void 0,
+          actions: r.actions,
+          createdAt: r.created_at,
+          updatedAt: r.updated_at
+        }));
+      }
+      async getDoc(idOrPath) {
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(idOrPath);
+        const rows = isUuid ? await this.sql`
+          SELECT * FROM doc_registry WHERE id = ${idOrPath} AND project_id = ${this.projectId}
+        ` : await this.sql`
+          SELECT * FROM doc_registry WHERE path = ${idOrPath} AND project_id = ${this.projectId}
+        `;
+        if (rows.length === 0) return null;
+        const r = rows[0];
+        return {
+          id: r.id,
+          title: r.title,
+          type: r.type,
+          path: r.path,
+          status: r.status,
+          summary: r.summary,
+          tags: r.tags ?? [],
+          cycleCreated: r.cycle_created,
+          cycleUpdated: r.cycle_updated ?? void 0,
+          supersededBy: r.superseded_by ?? void 0,
+          actions: r.actions,
+          createdAt: r.created_at,
+          updatedAt: r.updated_at
+        };
+      }
+      async updateDocStatus(id, status, supersededBy) {
+        await this.sql`
+      UPDATE doc_registry
+      SET status = ${status},
+          superseded_by = ${supersededBy ?? null},
+          updated_at = now()
+      WHERE id = ${id} AND project_id = ${this.projectId}
+    `;
+      }
       async writeDogfoodEntries(entries) {
         if (entries.length === 0) return;
         const values2 = entries.map((entry) => ({
@@ -7045,7 +7192,7 @@ ${newParts.join("\n")}` : newParts.join("\n");
           status: "pending",
           content: r.content,
           createdCycle: r.created_cycle,
-          actionedSprint: r.actioned_cycle ?? void 0,
+          actionedCycle: r.actioned_cycle ?? void 0,
           target: r.target ?? void 0
         }));
       }
@@ -7328,7 +7475,7 @@ ${r.content}` + (r.carry_forward ? `
         }));
         await this.sql`INSERT INTO entity_references ${this.sql(values2)}`;
       }
-      async getDecisionUsage(currentSprint) {
+      async getDecisionUsage(currentCycle) {
         const rows = await this.sql`
       SELECT decision_id, reference_count, last_referenced_cycle
       FROM v_decision_usage
@@ -7338,7 +7485,7 @@ ${r.content}` + (r.carry_forward ? `
           decisionId: r.decision_id,
           referenceCount: parseInt(r.reference_count, 10),
           lastReferencedCycle: r.last_referenced_cycle,
-          cyclesSinceLastReference: currentSprint - r.last_referenced_cycle
+          cyclesSinceLastReference: currentCycle - r.last_referenced_cycle
         }));
       }
       async getContextUtilisation() {
@@ -7979,6 +8126,7 @@ function loadConfig() {
   const autoCommit2 = process.env.PAPI_AUTO_COMMIT !== "false";
   const baseBranch = process.env.PAPI_BASE_BRANCH ?? "main";
   const autoPR = process.env.PAPI_AUTO_PR !== "false";
+  const lightMode = process.env.PAPI_LIGHT_MODE === "true";
   const papiEndpoint = process.env.PAPI_ENDPOINT;
   const dataEndpoint = process.env.PAPI_DATA_ENDPOINT;
   const databaseUrl = process.env.DATABASE_URL;
@@ -7992,7 +8140,8 @@ function loadConfig() {
     baseBranch,
     autoPR,
     adapterType,
-    papiEndpoint
+    papiEndpoint,
+    lightMode
   };
 }
 
@@ -8000,7 +8149,6 @@ function loadConfig() {
 init_dist2();
 import path2 from "path";
 var HOSTED_PROXY_ENDPOINT = "https://guewgygcpcmrcoppihzx.supabase.co/functions/v1/data-proxy";
-var HOSTED_PROXY_KEY = "e9891a0a2225ac376f88ebdad78b4814b52ce0a39a41c5ec";
 var PLACEHOLDER_PATTERNS = [
   "<YOUR_DATABASE_URL>",
   "your-database-url",
@@ -8091,7 +8239,12 @@ async function createAdapter(optionsOrType, maybePapiDir) {
         );
       }
       const dataEndpoint = process.env["PAPI_DATA_ENDPOINT"] || HOSTED_PROXY_ENDPOINT;
-      const dataApiKey = process.env["PAPI_DATA_API_KEY"] || HOSTED_PROXY_KEY;
+      const dataApiKey = process.env["PAPI_DATA_API_KEY"];
+      if (!dataApiKey) {
+        throw new Error(
+          "PAPI_DATA_API_KEY is required for proxy mode.\nTo get your API key:\n  1. Sign in at https://papi-web-three.vercel.app with GitHub\n  2. Your API key is shown on the onboarding page (save it \u2014 shown only once)\n  3. Add PAPI_DATA_API_KEY to your .mcp.json env config\nIf you already have a key, set it in your MCP configuration."
+        );
+      }
       const adapter2 = new ProxyPapiAdapter2({
         endpoint: dataEndpoint,
         apiKey: dataApiKey,
@@ -8985,6 +9138,9 @@ SECURITY CONSIDERATIONS
 REFERENCE DOCS
 [Optional \u2014 paths to docs/ files that provide background context for this task. Include only when the task originated from research or scoping work and the doc contains context the builder will need beyond what is in this handoff. Omit this section entirely for tasks that don't need supplementary context.]
 
+PRE-BUILD VERIFICATION
+[List 2-5 specific file paths the builder should read BEFORE implementing to check if the functionality already exists. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. If >80% of the scope is already implemented, the builder should report "already built" instead of re-implementing. Include this section for EVERY task \u2014 it prevents wasted build slots on already-shipped code.]
+
 FILES LIKELY TOUCHED
 [files]
 
@@ -9112,7 +9268,8 @@ Standard planning cycle with full board review.
    - Tier 4: Data visualization
    - Tier 5: New capability
    Within a tier: smaller effort wins. Justify in 2-3 sentences.
-   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge from the tasks themselves. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 3-5 tasks. A 1-task cycle is almost never correct \u2014 if only 1 task qualifies, check if lower-priority tasks could also ship.
+   **Blocked tasks:** Tasks with status "Blocked" MUST be skipped during task selection \u2014 they are waiting on external dependencies or gates and cannot be built. Do NOT generate BUILD HANDOFFs for blocked tasks. Do NOT recommend blocked tasks. If a blocked task's gate has been resolved (check the notes and recent build reports), emit a \`boardCorrections\` entry to move it back to Backlog. Report blocked task count in the cycle log.
+   **Cycle sizing:** Size the cycle based on what the selected tasks actually require \u2014 not a fixed budget. Select the highest-priority unblocked tasks, estimate each one's effort from its scope, and let the total emerge from the tasks themselves. The historical average effort from Methodology Trends is a reference point for calibration, not a target or floor. A healthy cycle has 4-6 tasks. Cycles with fewer than 4 tasks require explicit justification in the cycle log \u2014 explain why more tasks could not be included. When the backlog has 10+ tasks, the cycle SHOULD have 5+ tasks \u2014 undersized cycles waste planning overhead relative to the available work. If fewer than 4 tasks qualify after filtering (blocked, deferred, raw), check Deferred tasks \u2014 some may be ready to un-defer via a \`boardCorrections\` entry. A 1-task cycle is almost never correct.
 
 8. **Cycle Log** \u2014 Write 5-10 line entry: what was triaged, what was recommended and why, observations, AD updates.
    **Cycle Notes** \u2014 Optionally include 1-3 lines of cycle-level observations in \`cycleLogNotes\`: estimation accuracy patterns, recurring blockers, velocity trends, or dependency signals. These notes persist across cycles so future planning runs can learn from them. Use null if there are no noteworthy observations this cycle.
@@ -9122,11 +9279,13 @@ Standard planning cycle with full board review.
 
 10. **BUILD HANDOFFs** \u2014 Generate a full BUILD HANDOFF block for the recommended task and up to 4 additional high-priority unblocked tasks (5 total max). Include each handoff in the \`cycleHandoffs\` array in the structured output. The handoffs are written to each task on the board for durability. Remaining tasks will get handoffs in subsequent plans \u2014 do NOT try to cover the entire backlog.
    **SKIP existing handoffs:** Tasks marked with "Has BUILD HANDOFF: yes" or "\u2713 handoff" on the board already have a valid handoff from a previous plan. Do NOT regenerate handoffs for these tasks \u2014 omit them from the \`cycleHandoffs\` array entirely. Only generate handoffs for tasks that do NOT have one yet. Exception: if a task's dependencies have been completed since its handoff was written, or a relevant Active Decision has changed, you MAY regenerate its handoff \u2014 but note this explicitly in the cycle log.
+   **Scope pre-check:** Before writing the SCOPE section of each handoff, check whether the described functionality already exists based on the task's context, recent build reports, and the FILES LIKELY TOUCHED. If the infrastructure likely exists (e.g. a status type, a DB constraint, an API route), reduce the scope to only the missing pieces and explicitly note what already exists. C126 task-728 was over-scoped because the planner assumed Blocked status needed creating from scratch \u2014 it already existed in types, DB, orient, and build_list. Over-scoped handoffs waste builder time on verification and cause estimation mismatches.
    **Simplest Viable Path rule:** Before writing each BUILD HANDOFF, identify the simplest approach that satisfies the task's goal \u2014 the minimum change, fewest new abstractions, and smallest blast radius. Write the SCOPE (DO THIS) section for that simplest path FIRST. If you believe a more complex approach is warranted (new abstractions, multi-file refactors, framework changes), you MUST include a "WHY NOT SIMPLER" line in the handoff explaining why the simple path is insufficient. If you cannot articulate a concrete reason, use the simpler path. Pay special attention to tasks involving auth, data access, multi-user features, and infrastructure \u2014 these are the most common over-engineering targets.
    **Maturity gate applies here:** Do NOT generate BUILD HANDOFFs for tasks that failed the maturity gate in step 6. This includes raw tasks (\`maturity: "raw"\`) and tasks whose phase prerequisites are not met. Only cycle-ready tasks should receive handoffs.
    **Security section guidance:** Each handoff includes a SECURITY CONSIDERATIONS section. Populate it when the task involves: data exposure risks (PII, secrets in logs/storage), secrets or credentials handling (API keys, tokens, env vars), auth/access control changes, or dependency security risks (new packages, version changes). For pure refactoring, documentation, prompt-text, or UI-only tasks, write "None \u2014 no security-relevant changes".
    **Estimation calibration:** Tasks that wire existing adapter methods, add API routes following established patterns, modify prompts, or make documentation-only changes should be estimated **S** unless they require new abstractions, new DB tables, or multi-file architectural changes. Default to S for pattern-following work. Only use M when genuine new architecture is needed. If an "Estimation Calibration (Historical)" section is provided in the context below, use its data to adjust your estimates \u2014 it shows how often each estimated size matched the actual effort. Pay special attention to systematic over/under-estimation patterns (e.g. if M\u2192S happens frequently, estimate S instead of M for similar work).
    **Reference docs:** If a task's notes include a \`Reference:\` path (e.g. \`Reference: docs/architecture/papi-brain-v1.md\`), include a REFERENCE DOCS section in the BUILD HANDOFF with those paths. This tells the builder to read the referenced doc for background context before implementing. Do NOT omit or summarise the reference \u2014 pass it through so the builder can access the full document. Only tasks with explicit \`Reference:\` paths in their notes should have this section.
+   **Pre-build verification:** EVERY handoff MUST include a PRE-BUILD VERIFICATION section listing 2-5 specific file paths the builder should read before implementing. Derive these from FILES LIKELY TOUCHED \u2014 pick the files most likely to already contain the target functionality. This is the #1 prevention mechanism for wasted build slots (C120, C125, C126 all scheduled already-shipped work). If the builder finds >80% of the scope already implemented, they report "already built" instead of re-implementing.
    **UI/visual task detection:** When a task's title or notes contain keywords suggesting frontend visual work (e.g. "visual", "design", "UI", "styling", "refresh", "frontend", "landing page", "hero", "carousel", "theme", "layout"), apply these handoff additions:
    - Add to SCOPE: "Use the \`frontend-design\` skill for implementation \u2014 it produces higher-quality visual output than manual styling."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser before reporting done \u2014 provide localhost URL or screenshot to the user for review."
@@ -9147,7 +9306,7 @@ Standard planning cycle with full board review.
    - The North Star changed or was validated in a way that the brief doesn't reflect
    - A phase completed that shifts what the product IS (not just what was built)
    - The brief describes capabilities, architecture, or direction that are no longer accurate
-   - **STALENESS CHECK:** Look at the "Last updated" line in the brief. If it references a cycle number more than 10 cycles behind the current cycle, the brief is stale and MUST be updated \u2014 even if no single trajectory-changing event occurred, cumulative drift over 10+ cycles means the brief no longer represents the product. This is the #1 source of planner drift.
+   - **DRIFT CHECK:** Compare the brief's content against current reality. The brief is drifted if: (a) it describes capabilities that don't exist or have been removed, (b) it references user types, architecture, or positioning that ADs have since changed, (c) the current phase/stage has shifted from what the brief describes, or (d) key metrics or success criteria no longer match the project's direction. Cycle count since last update is a secondary signal only \u2014 a brief updated 15 cycles ago that still accurately describes the product is NOT stale. A brief updated 3 cycles ago that contradicts a recent AD IS drifted.
    If any of these apply, include an updated \`productBrief\` in the structured output. Include the FULL updated brief (not a diff). Preserve all existing sections and user-added content; update facts, numbers, and status to reflect current reality. Do not regenerate the brief every cycle \u2014 but do not let it go stale either.
 
 13. **Forward Horizon** \u2014 If a Forward Horizon section is provided in the context below, write a "## Forward Horizon" section in Part 1. Surface 2-3 decisions the team should make before the next phase starts. Each item must be:
@@ -9345,7 +9504,7 @@ You MUST cover these 6 sections. Each is mandatory unless explicitly noted as co
    - Is the product brief still an accurate description of what this product IS and WHERE it's going? If ADs have been created or superseded since the brief was last updated, the brief may be wrong.
    - Has the target user changed? Has the scope expanded or contracted in ways the brief doesn't capture?
    - Are we building for the right problem? Has evidence emerged (from builds, feedback, or market) that the core problem statement needs revision?
-   - If the North Star hasn't been referenced in 10+ cycles, flag it as potentially stale.
+   - Assess North Star drift: Does the North Star's key metric and success definition still align with the current phase, active ADs, and recent build directions? A North Star is drifted when: the metric it tracks is no longer the team's focus, the success criteria reference capabilities that have been deprioritised, or ADs have shifted the product direction away from what the North Star describes. Cycle count since last update is a secondary signal \u2014 a stable, accurate North Star is not stale regardless of age.
    If this analysis reveals the brief needs updating, you MUST include updated content in \`productBriefUpdates\` in Part 2. Don't just note "the brief is stale" \u2014 write the update.
 
 6. **Active Decision Review + Scoring** \u2014 For each non-superseded AD: is the confidence level still correct? Has evidence emerged that changes anything? Score on 5 dimensions (1-5, lower = better):
@@ -9397,11 +9556,11 @@ ${compressionJob}
    - If no phase data is provided, skip this section.
    Report findings in a "Hierarchy Assessment" section in Part 1. Persist findings in the \`stalePhases\` array in Part 2 (include stage/horizon observations too). If no issues found, omit the section and use an empty array.
 
-12. **Structural Staleness Detection** \u2014 If decision usage data is provided in context, identify structural decay:
-   - ADs that haven't been **referenced in 10+ cycles** \u2192 flag as potentially obsolete, recommend review or resolution.
-   - Carry-forward items that have persisted across **3+ cycles** without resolution \u2192 flag as stuck.
-   - ADs with LOW confidence that have persisted for 5+ cycles without evidence \u2192 flag as unvalidated.
-   Reference the decision usage data for quantitative staleness signals rather than guessing. Report findings in a "Structural Staleness" section in Part 1. Persist findings in the \`staleDecisions\` array in Part 2. If no issues found, omit the section and use an empty array.
+12. **Structural Drift Detection** \u2014 If decision usage data is provided in context, identify structural decay using drift-based criteria (not pure cycle counts):
+   - **AD drift:** An AD is drifted when its content contradicts recent build evidence, references architecture/capabilities that no longer exist, or has been made redundant by newer ADs. Reference frequency is a secondary signal \u2014 an unreferenced AD that is still accurate is not necessarily stale; an AD referenced last cycle that contradicts shipped code IS drifted.
+   - **Carry-forward drift:** Carry-forward items that have persisted across **3+ cycles** without resolution \u2192 flag as stuck.
+   - **Confidence drift:** ADs with LOW confidence that have not gained supporting evidence within 5 cycles \u2192 flag as unvalidated. ADs where build reports contradict the decision \u2192 flag as confidence should decrease.
+   Use decision usage data as a secondary signal (unreferenced ADs are more likely to be drifted, but verify by checking content alignment). Report findings in a "Structural Drift" section in Part 1. Persist findings in the \`staleDecisions\` array in Part 2. If no issues found, omit the section and use an empty array.
 
 ## OUTPUT FORMAT
 
@@ -9422,7 +9581,7 @@ Then include conditional sections only if relevant:
 - **Architecture Health** \u2014 only if issues found
 - **Discovery Canvas Audit** \u2014 only if gaps or staleness found
 - **Hierarchy Assessment** \u2014 only if hierarchy staleness, phase closure, or stage progression signals detected
-- **Structural Staleness** \u2014 only if unreferenced ADs or stuck carry-forwards found${compressionPart1}
+- **Structural Drift** \u2014 only if drifted ADs or stuck carry-forwards found${compressionPart1}
 
 ### Part 2: Structured Data Block
 After your natural language output, include this EXACT format on its own line:
@@ -9584,6 +9743,12 @@ function buildReviewUserMessage(ctx) {
   if (ctx.recommendationEffectiveness) {
     parts.push("### Recommendation Follow-Through", "", ctx.recommendationEffectiveness, "");
   }
+  if (ctx.adHocCommits) {
+    parts.push("### Ad-hoc Work (Non-Task Commits)", "", ctx.adHocCommits, "");
+  }
+  if (ctx.pendingRecommendations) {
+    parts.push("### Pending Strategy Recommendations", "", ctx.pendingRecommendations, "");
+  }
   return parts.join("\n");
 }
 function parseReviewStructuredOutput(raw) {
@@ -10069,9 +10234,19 @@ function autoCommitPapi(config2, cycleNumber, mode) {
     return `Auto-commit failed: ${err instanceof Error ? err.message : String(err)}`;
   }
 }
-function formatStrategyRecommendations(recs) {
-  const byType = /* @__PURE__ */ new Map();
+var REC_EXPIRY_CYCLES = 3;
+function formatStrategyRecommendations(recs, currentCycle) {
+  const active = [];
+  const expired = [];
   for (const rec of recs) {
+    if (currentCycle !== void 0 && rec.createdCycle && currentCycle - rec.createdCycle > REC_EXPIRY_CYCLES) {
+      expired.push(rec);
+    } else {
+      active.push(rec);
+    }
+  }
+  const byType = /* @__PURE__ */ new Map();
+  for (const rec of active) {
     const list = byType.get(rec.type) ?? [];
     list.push(rec);
     byType.set(rec.type, list);
@@ -10091,6 +10266,12 @@ function formatStrategyRecommendations(recs) {
       sections.push(`- (Cycle ${item.createdCycle}) ${item.content}${targetSuffix}`);
     }
   }
+  if (expired.length > 0) {
+    sections.push(`**Expired (${expired.length} recs skipped \u2014 older than ${REC_EXPIRY_CYCLES} cycles):**`);
+    for (const item of expired) {
+      sections.push(`- (Cycle ${item.createdCycle}) ${item.content.slice(0, 80)}...`);
+    }
+  }
   return sections.join("\n");
 }
 function formatDiscoveryCanvas(canvas) {
@@ -10311,7 +10492,7 @@ async function assembleContext(adapter2, mode, _config, filters, focus) {
     try {
       const pendingRecs = await adapter2.getPendingRecommendations();
       if (pendingRecs.length > 0) {
-        strategyRecommendationsText2 = formatStrategyRecommendations(pendingRecs);
+        strategyRecommendationsText2 = formatStrategyRecommendations(pendingRecs, health.totalCycles);
       }
     } catch {
     }
@@ -11240,6 +11421,7 @@ ${result.userMessage}
 // src/services/strategy.ts
 init_dist2();
 import { randomUUID as randomUUID8, createHash as createHash2 } from "crypto";
+import { execFileSync as execFileSync2 } from "child_process";
 
 // src/lib/phase-realign.ts
 function extractPhaseNumber(phaseField) {
@@ -11556,6 +11738,45 @@ function formatTaskCompact(t) {
   Reviewed: ${t.reviewed}${t.dependsOn ? ` | Depends on: ${t.dependsOn}` : ""}` + (notesSnippet ? `
   Notes: ${notesSnippet}` : "") + "\n";
 }
+function getAdHocCommits(projectRoot, sinceTag) {
+  try {
+    const logArgs = ["log", "--oneline", "--no-merges", "-100"];
+    if (sinceTag) {
+      logArgs.splice(1, 0, `${sinceTag}..HEAD`);
+    }
+    const output = execFileSync2("git", logArgs, {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+    if (!output) return void 0;
+    const allCommits = output.split("\n");
+    const taskPattern = /task-\d+/i;
+    const nonTaskCommits = allCommits.filter((line) => !taskPattern.test(line));
+    if (nonTaskCommits.length === 0) return void 0;
+    const capped = nonTaskCommits.slice(0, 20);
+    const groups = {};
+    const typePattern = /^[a-f0-9]+ (feat|fix|chore|refactor|docs|style|test|ci|perf|build|release)[\s(:]/i;
+    for (const line of capped) {
+      const match = line.match(typePattern);
+      const type = match ? match[1].toLowerCase() : "other";
+      (groups[type] ??= []).push(line);
+    }
+    const lines = [];
+    lines.push(`${nonTaskCommits.length} non-task commits found${nonTaskCommits.length > 20 ? " (showing 20 most recent)" : ""}:
+`);
+    for (const [type, commits] of Object.entries(groups).sort((a, b2) => b2[1].length - a[1].length)) {
+      lines.push(`**${type}** (${commits.length}):`);
+      for (const c of commits) {
+        lines.push(`- ${c}`);
+      }
+      lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+  } catch {
+    return void 0;
+  }
+}
 async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, projectRoot) {
   const lastReviewCycleNum = cycleNumber - cyclesSinceLastReview;
   const [
@@ -11571,7 +11792,8 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     currentNorthStar,
     canvas,
     decisionUsage,
-    recData
+    recData,
+    pendingRecs
   ] = await Promise.all([
     adapter2.readProductBrief(),
     adapter2.getActiveDecisions(),
@@ -11592,7 +11814,8 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     // Previously sequential — now parallel
     adapter2.readDiscoveryCanvas().catch(() => ({})),
     adapter2.getDecisionUsage(cycleNumber).catch(() => []),
-    adapter2.getRecommendationEffectiveness?.()?.catch(() => []) ?? Promise.resolve([])
+    adapter2.getRecommendationEffectiveness?.()?.catch(() => []) ?? Promise.resolve([]),
+    adapter2.getPendingRecommendations().catch(() => [])
   ]);
   const tasks = [...activeTasks, ...recentDoneTasks];
   const recentLog = log;
@@ -11667,12 +11890,32 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     }
   } catch {
   }
+  let pendingRecsText;
+  try {
+    if (pendingRecs.length > 0) {
+      const lines = pendingRecs.map((r) => {
+        const targetSuffix = r.target ? ` \u2192 ${r.target}` : "";
+        return `- [${r.status}] (Cycle ${r.createdCycle}, ${r.type}) ${r.content}${targetSuffix}`;
+      });
+      pendingRecsText = `${pendingRecs.length} pending recommendation(s) from prior reviews:
+${lines.join("\n")}`;
+    }
+  } catch {
+  }
+  let adHocCommitsText;
+  try {
+    const sinceTag = `v0.${lastReviewCycleNum}.0`;
+    adHocCommitsText = getAdHocCommits(projectRoot, sinceTag);
+  } catch {
+  }
   logDataSourceSummary("strategy_review_audit", [
     { label: "discoveryCanvas", hasData: discoveryCanvasText !== void 0 },
     { label: "briefImplications", hasData: briefImplicationsText !== void 0 },
     { label: "phases", hasData: phasesText !== void 0 },
     { label: "decisionUsage", hasData: decisionUsageText !== void 0 },
-    { label: "recEffectiveness", hasData: recEffectivenessText !== void 0 }
+    { label: "recEffectiveness", hasData: recEffectivenessText !== void 0 },
+    { label: "pendingRecs", hasData: pendingRecsText !== void 0 },
+    { label: "adHocCommits", hasData: adHocCommitsText !== void 0 }
   ]);
   const context = {
     sessionNumber: cycleNumber,
@@ -11692,7 +11935,9 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     phases: phasesText,
     decisionUsage: decisionUsageText,
     northStar: currentNorthStar ?? void 0,
-    recommendationEffectiveness: recEffectivenessText
+    recommendationEffectiveness: recEffectivenessText,
+    adHocCommits: adHocCommitsText,
+    pendingRecommendations: pendingRecsText
   };
   const BUDGET_SOFT2 = 8e4;
   const BUDGET_HARD2 = 1e5;
@@ -11904,8 +12149,16 @@ async function processReviewOutput(adapter2, rawOutput, cycleNumber) {
       phaseChanges = await writeBack2(adapter2, cycleNumber, data, displayText);
     } catch (err) {
       writeBackFailed = err instanceof Error ? err.message : String(err);
+      try {
+        await adapter2.savePendingReviewResponse?.(cycleNumber, rawOutput);
+      } catch {
+      }
     }
     if (!writeBackFailed) {
+      try {
+        await adapter2.clearPendingReviewResponse?.();
+      } catch {
+      }
       const webhookUrl = process.env.PAPI_SLACK_WEBHOOK_URL;
       slackWarning = await sendSlackWebhook(webhookUrl, buildSlackSummary(data));
     }
@@ -11953,6 +12206,28 @@ async function prepareStrategyReview(adapter2, force, projectRoot, adapterType)
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
   }
+  try {
+    const pending = await adapter2.getPendingReviewResponse?.();
+    if (pending) {
+      return {
+        cycleNumber: pending.cycleNumber || cycleNumber,
+        systemPrompt: "",
+        userMessage: `\u26A0\uFE0F **Pending Strategy Review Found**
+
+A previous strategy review (Cycle ${pending.cycleNumber || cycleNumber}) failed to write back. The raw LLM response has been preserved.
+
+To retry, call \`strategy_review\` with:
+- \`mode\`: "apply"
+- \`llm_response\`: (the response below)
+- \`cycle_number\`: ${pending.cycleNumber || cycleNumber}
+
+---
+
+${pending.rawResponse}`
+      };
+    }
+  } catch {
+  }
   let context;
   try {
     context = await assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, projectRoot);
@@ -12740,7 +13015,7 @@ var boardViewTool = {
 };
 var boardDeprioritiseTool = {
   name: "board_deprioritise",
-  description: `Remove a task from the current cycle. Three actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
+  description: `Remove a task from the current cycle. Four actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "block" (waiting on external dependency \u2014 visible on board but skipped by planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -12750,8 +13025,8 @@ var boardDeprioritiseTool = {
       },
       action: {
         type: "string",
-        enum: ["backlog", "defer", "cancel"],
-        description: `"backlog" = not now, maybe later (preserves handoff). "defer" = valid but premature (hidden from planner). "cancel" = don't want this at all (permanently closed). If omitted, defaults to "backlog" for backwards compatibility.`
+        enum: ["backlog", "defer", "block", "cancel"],
+        description: `"backlog" = not now, maybe later (preserves handoff). "defer" = valid but premature (hidden from planner). "block" = waiting on external dependency (visible but skipped by planner \u2014 reason required). "cancel" = don't want this at all (permanently closed). If omitted, defaults to "backlog" for backwards compatibility.`
       },
       reason: {
         type: "string",
@@ -12872,6 +13147,29 @@ async function handleBoardDeprioritise(adapter2, args) {
   const reason = args.reason;
   const newPriority = args.priority;
   const newPhase = args.phase;
+  if (action === "block") {
+    if (!reason) {
+      return errorResponse("reason is required when blocking a task \u2014 explain what external dependency or gate is blocking it.");
+    }
+    try {
+      const task = await adapter2.getTask(taskId);
+      if (!task) return errorResponse(`Task ${taskId} not found.`);
+      const existingNotes = task.notes ? `${task.notes}
+
+` : "";
+      await adapter2.updateTask(taskId, {
+        status: "Blocked",
+        notes: `${existingNotes}BLOCKED: ${reason}`
+      });
+      return textResponse(`Blocked **${taskId}** (${task.title}).
+
+Reason: ${reason}
+
+Task remains visible on the board but will be skipped by the planner and build_list.`);
+    } catch (err) {
+      return errorResponse(err instanceof Error ? err.message : String(err));
+    }
+  }
   if (action === "cancel") {
     if (!reason) {
       return errorResponse("reason is required when cancelling a task.");
@@ -14008,6 +14306,8 @@ init_dist2();
 
 // src/services/build.ts
 import { randomUUID as randomUUID9 } from "crypto";
+import { readdirSync, existsSync } from "fs";
+import { join as join3 } from "path";
 function capitalizeCompleted(value) {
   const map = {
     yes: "Yes",
@@ -14247,6 +14547,13 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     cycleNumber = 0;
   }
   const now = /* @__PURE__ */ new Date();
+  let iterationCount = 1;
+  try {
+    const priorReports = await adapter2.getRecentBuildReports(200);
+    const priorForTask = priorReports.filter((r) => r.taskId === taskId);
+    iterationCount = priorForTask.length + 1;
+  } catch {
+  }
   const report = {
     uuid: randomUUID9(),
     createdAt: now.toISOString(),
@@ -14264,7 +14571,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     handoffAccuracy: input.handoffAccuracy,
     correctionsCount: input.correctionsCount,
     briefImplications: input.briefImplications,
-    deadEnds: input.deadEnds
+    deadEnds: input.deadEnds,
+    iterationCount
   };
   if (input.relatedDecisions) {
     const adIds = input.relatedDecisions.split(",").map((s) => s.trim()).filter(Boolean);
@@ -14291,7 +14599,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
   }
   const surpriseNote = input.surprises === "None" ? "" : ` Surprises: ${input.surprises}.`;
   const issueNote = input.discoveredIssues === "None" ? "" : ` Issues: ${input.discoveredIssues}.`;
-  const buildReportSummary = `${capitalizeCompleted(input.completed)}. Effort ${input.effort} vs estimated ${input.estimatedEffort}.${surpriseNote}${issueNote}`;
+  const iterNote = iterationCount > 1 ? ` Iterations: ${iterationCount} (${iterationCount - 1} pushback${iterationCount > 2 ? "s" : ""}).` : "";
+  const buildReportSummary = `${capitalizeCompleted(input.completed)}. Effort ${input.effort} vs estimated ${input.estimatedEffort}.${iterNote}${surpriseNote}${issueNote}`;
   await adapter2.updateTask(taskId, { buildReport: buildReportSummary });
   if (input.completed === "yes") {
     if (options.light) {
@@ -14332,6 +14641,32 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     phaseChanges = await propagatePhaseStatus(adapter2);
   } catch {
   }
+  let docWarning;
+  try {
+    if (adapter2.searchDocs) {
+      const docsDir = join3(config2.projectRoot, "docs");
+      if (existsSync(docsDir)) {
+        const scanDir = (dir) => {
+          const entries = readdirSync(dir, { withFileTypes: true });
+          const files = [];
+          for (const e of entries) {
+            const full = join3(dir, e.name);
+            if (e.isDirectory()) files.push(...scanDir(full));
+            else if (e.name.endsWith(".md")) files.push(full.replace(config2.projectRoot + "/", ""));
+          }
+          return files;
+        };
+        const mdFiles = scanDir(docsDir);
+        const registered = await adapter2.searchDocs({ status: "active", limit: 500 });
+        const registeredPaths = new Set(registered.map((d) => d.path));
+        const unregistered = mdFiles.filter((f) => !registeredPaths.has(f));
+        if (unregistered.length > 0) {
+          docWarning = `${unregistered.length} unregistered doc(s) in docs/ \u2014 consider running \`doc_register\` for: ${unregistered.slice(0, 5).join(", ")}${unregistered.length > 5 ? ` (+${unregistered.length - 5} more)` : ""}`;
+        }
+      }
+    }
+  } catch {
+  }
   return {
     task,
     report,
@@ -14343,7 +14678,8 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
     discoveredIssues: input.discoveredIssues,
     completed: input.completed,
     scopeAccuracy: input.scopeAccuracy,
-    phaseChanges
+    phaseChanges,
+    docWarning
   };
 }
 async function cancelBuild(adapter2, taskId, reason) {
@@ -14384,7 +14720,7 @@ var buildDescribeTool = {
 };
 var buildExecuteTool = {
   name: "build_execute",
-  description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Does not call the Anthropic API.",
+  description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
   inputSchema: {
     type: "object",
     properties: {
@@ -14550,7 +14886,7 @@ async function handleBuildExecute(adapter2, config2, args) {
   if (!taskId) {
     return errorResponse("task_id is required.");
   }
-  const light = args.light === true;
+  const light = args.light === true || config2.lightMode;
   if (hasReportFields(args)) {
     return handleExecuteComplete(adapter2, config2, taskId, args, light);
   }
@@ -14563,8 +14899,16 @@ async function handleBuildExecute(adapter2, config2, args) {
 ---
 
 `;
+    const verificationFiles = result.task.buildHandoff.verificationFiles ?? [];
+    const verificationNote = verificationFiles.length > 0 ? `
+
+---
+
+**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.";
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + chainInstruction + phaseNote);
+    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + verificationNote + chainInstruction + phaseNote);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -14671,6 +15015,9 @@ function formatCompleteResult(result) {
       lines.push(`Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`);
     }
   }
+  if (result.docWarning) {
+    lines.push("", `\u{1F4C4} ${result.docWarning}`);
+  }
   const hasDiscoveredIssues = result.discoveredIssues !== "None" && result.discoveredIssues.trim() !== "";
   const remaining = result.cycleProgress.total - result.cycleProgress.completed;
   if (result.completed !== "yes") {
@@ -15818,6 +16165,25 @@ async function getHealthSummary(adapter2) {
   } catch (_err) {
     metricsSection = "Could not read methodology metrics.";
   }
+  try {
+    const recentReports = await adapter2.getRecentBuildReports(50);
+    if (recentReports.length > 0) {
+      const taskCounts = /* @__PURE__ */ new Map();
+      for (const r of recentReports) {
+        taskCounts.set(r.taskId, (taskCounts.get(r.taskId) ?? 0) + 1);
+      }
+      const iterCounts = [...taskCounts.values()];
+      const avgIter = iterCounts.reduce((s, c) => s + c, 0) / iterCounts.length;
+      const multiIterTasks = iterCounts.filter((c) => c > 1).length;
+      if (avgIter > 1 || multiIterTasks > 0) {
+        derivedMetricsSection += `
+
+**Rework**
+- Average iterations: ${avgIter.toFixed(1)} (${multiIterTasks} task${multiIterTasks !== 1 ? "s" : ""} with pushbacks)`;
+      }
+    }
+  } catch {
+  }
   const costSection = "Disabled \u2014 local MCP, no API costs.";
   let decisionUsageSection = "";
   try {
@@ -15991,7 +16357,7 @@ async function handleHealth(adapter2) {
 
 // src/services/release.ts
 import { writeFile as writeFile3 } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 var INITIAL_RELEASE_NOTES = `# Changelog
 
 ## v0.1.0-alpha \u2014 Initial Release
@@ -16082,7 +16448,7 @@ async function createRelease(config2, branch, version, adapter2) {
     const commits = getCommitsSinceTag(config2.projectRoot, latestTag);
     changelogContent = generateChangelog(version, commits);
   }
-  const changelogPath = join3(config2.projectRoot, "CHANGELOG.md");
+  const changelogPath = join4(config2.projectRoot, "CHANGELOG.md");
   await writeFile3(changelogPath, changelogContent, "utf-8");
   const commitResult = stageAllAndCommit(config2.projectRoot, `release: ${version}`);
   const commitNote = commitResult.committed ? `Committed CHANGELOG.md.` : `CHANGELOG.md: ${commitResult.message}`;
@@ -16163,8 +16529,8 @@ async function handleRelease(adapter2, config2, args) {
 }
 
 // src/tools/review.ts
-import { existsSync } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { join as join5 } from "path";
 
 // src/services/review.ts
 init_dist2();
@@ -16402,8 +16768,8 @@ function mergeAfterAccept(config2, taskId) {
   }
   const featureBranch = taskBranchName(taskId);
   const baseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
-  const papiDir = join4(config2.projectRoot, ".papi");
-  if (existsSync(papiDir)) {
+  const papiDir = join5(config2.projectRoot, ".papi");
+  if (existsSync2(papiDir)) {
     try {
       const commitResult = stageDirAndCommit(
         config2.projectRoot,
@@ -16692,6 +17058,9 @@ Path: ${mcpJsonPath}`
 }
 
 // src/tools/orient.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { readFileSync } from "fs";
+import { join as join6 } from "path";
 var orientTool = {
   name: "orient",
   description: "Session orientation \u2014 single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, and recommended next action. Read-only, does not modify any files.",
@@ -16836,6 +17205,25 @@ async function getHierarchyPosition(adapter2) {
     return void 0;
   }
 }
+function checkNpmVersionDrift() {
+  try {
+    const pkgPath = join6(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const localVersion = pkg.version;
+    const packageName = pkg.name;
+    const published = execFileSync3("npm", ["view", packageName, "version"], {
+      encoding: "utf-8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (published && published !== localVersion) {
+      return `\u26A0\uFE0F npm version drift: local v${localVersion} vs published v${published}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function handleOrient(adapter2, config2) {
   try {
     const [buildResult, healthResult, hierarchy] = await Promise.all([
@@ -16884,7 +17272,28 @@ async function handleOrient(adapter2, config2) {
       } catch {
       }
     }
-    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy) + ttfvNote);
+    const versionDrift = checkNpmVersionDrift();
+    const versionNote = versionDrift ? `
+${versionDrift}` : "";
+    let recsNote = "";
+    try {
+      const pendingRecs = await adapter2.getPendingRecommendations();
+      if (pendingRecs.length > 0) {
+        recsNote = `
+**Strategy Recommendations:** ${pendingRecs.length} pending action`;
+      }
+    } catch {
+    }
+    let pendingReviewNote = "";
+    try {
+      const pending = await adapter2.getPendingReviewResponse?.();
+      if (pending) {
+        pendingReviewNote = `
+\u26A0\uFE0F **Pending Strategy Review:** 1 review failed write-back (Cycle ${pending.cycleNumber}) \u2014 run \`strategy_review\` to retry.`;
+      }
+    } catch {
+    }
+    return textResponse(formatOrientSummary(healthResult, buildInfo, hierarchy) + ttfvNote + recsNote + pendingReviewNote + versionNote);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(`Orient failed: ${message}`);
@@ -17311,6 +17720,132 @@ ${result.userMessage}
   }
 }
 
+// src/tools/doc-registry.ts
+var docRegisterTool = {
+  name: "doc_register",
+  description: "Register a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: 'Relative path from project root (e.g. "docs/research/funding-landscape.md").' },
+      title: { type: "string", description: "Document title." },
+      type: { type: "string", enum: ["research", "audit", "spec", "guide", "architecture", "positioning", "framework", "reference"], description: "Document type." },
+      status: { type: "string", enum: ["active", "draft", "superseded", "actioned", "legacy", "archived"], description: 'Document status. Defaults to "active".' },
+      summary: { type: "string", description: 'Structured 2-4 sentence summary. Format: "Conclusions: ... Open questions: ... Unactioned: ..."' },
+      tags: { type: "array", items: { type: "string" }, description: "Tags from project vocabulary." },
+      cycle: { type: "number", description: "Current cycle number." },
+      actions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            description: { type: "string" },
+            status: { type: "string", enum: ["pending", "resolved"] },
+            linkedTaskId: { type: "string" }
+          },
+          required: ["description", "status"]
+        },
+        description: "Actionable findings from the document."
+      },
+      superseded_by_path: { type: "string", description: "Path of the doc that supersedes this one (sets status to superseded)." }
+    },
+    required: ["path", "title", "type", "summary", "cycle"]
+  }
+};
+var docSearchTool = {
+  name: "doc_search",
+  description: "Search the doc registry for documents by type, tags, keyword, or pending actions. Returns summaries, not full content. Use for context gathering in plan, strategy review, and idea dedup.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      type: { type: "string", description: 'Filter by doc type (e.g. "research", "architecture").' },
+      status: { type: "string", description: 'Filter by status. Defaults to "active".' },
+      tags: { type: "array", items: { type: "string" }, description: "Filter by tags (OR match)." },
+      keyword: { type: "string", description: "Search title and summary text." },
+      has_pending_actions: { type: "boolean", description: "Only docs with unresolved action items." },
+      since_cycle: { type: "number", description: "Docs updated since this cycle." },
+      limit: { type: "number", description: "Max results (default: 10)." }
+    },
+    required: []
+  }
+};
+async function handleDocRegister(adapter2, args) {
+  if (!adapter2.registerDoc) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const path5 = args.path;
+  const title = args.title;
+  const type = args.type;
+  const status = args.status ?? "active";
+  const summary = args.summary;
+  const tags = args.tags ?? [];
+  const cycle = args.cycle;
+  const actions = args.actions;
+  const supersededByPath = args.superseded_by_path;
+  if (!path5 || !title || !type || !summary || !cycle) {
+    return errorResponse("Required fields: path, title, type, summary, cycle.");
+  }
+  let supersededBy;
+  if (supersededByPath) {
+    const existing = await adapter2.getDoc?.(supersededByPath);
+    if (existing) {
+      supersededBy = existing.id;
+      await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
+    }
+  }
+  const entry = await adapter2.registerDoc({
+    title,
+    type,
+    path: path5,
+    status: supersededByPath ? "superseded" : status,
+    summary,
+    tags,
+    cycleCreated: cycle,
+    cycleUpdated: cycle,
+    supersededBy,
+    actions
+  });
+  return textResponse(
+    `**Registered:** ${entry.title}
+- **Path:** ${entry.path}
+- **Type:** ${entry.type} | **Status:** ${entry.status}
+- **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
+- **Actions:** ${actions?.length ?? 0} items
+- **ID:** ${entry.id}`
+  );
+}
+async function handleDocSearch(adapter2, args) {
+  if (!adapter2.searchDocs) {
+    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+  }
+  const input = {
+    type: args.type,
+    status: args.status,
+    tags: args.tags,
+    keyword: args.keyword,
+    hasPendingActions: args.has_pending_actions,
+    sinceCycle: args.since_cycle,
+    limit: args.limit
+  };
+  const docs = await adapter2.searchDocs(input);
+  if (docs.length === 0) {
+    return textResponse("No documents found matching the search criteria.");
+  }
+  const lines = docs.map((d) => {
+    const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
+    const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
+    return `### ${d.title}
+**Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
+**Path:** ${d.path}
+**Tags:** ${d.tags.length > 0 ? d.tags.join(", ") : "none"}
+${d.summary}
+`;
+  });
+  return textResponse(`**${docs.length} document(s) found:**
+
+${lines.join("\n---\n\n")}`);
+}
+
 // src/lib/telemetry.ts
 var TELEMETRY_SUPABASE_URL = "https://guewgygcpcmrcoppihzx.supabase.co";
 var TELEMETRY_API_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imd1ZXdneWdjcGNtcmNvcHBpaHp4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI2Njk2NTMsImV4cCI6MjA4ODI0NTY1M30.V5Jw7wJgiMpSQPa2mt0ftjyye5ynG1qLlam00yPVNJY";
@@ -17407,7 +17942,9 @@ function createServer(adapter2, config2) {
       initTool,
       orientTool,
       hierarchyUpdateTool,
-      zoomOutTool
+      zoomOutTool,
+      docRegisterTool,
+      docSearchTool
     ]
   }));
   server2.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -17508,6 +18045,12 @@ function createServer(adapter2, config2) {
       case "zoom_out":
         result = await handleZoomOut(adapter2, config2, safeArgs);
         break;
+      case "doc_register":
+        result = await handleDocRegister(adapter2, safeArgs);
+        break;
+      case "doc_search":
+        result = await handleDocSearch(adapter2, safeArgs);
+        break;
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
     }

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
-    ".": "./dist/index.js",
-    "./prompts": "./src/prompts.ts"
+    ".": "./dist/index.js"
   },
   "bin": {
     "papi-server": "./dist/index.js"