@oss-autopilot/core 3.12.0 → 3.13.0

package/dist/commands/list-mark-done.d.ts

@@ -1,6 +1,9 @@
 /**
  * list-mark-done command (#1299).
  *
+ * A URL that is not in the list at all is an error (#1406) — marking done
+ * requires an existing entry; only the already-marked re-run is a quiet no-op.
+ *
  * Mark an issue line in a curated list as done by wrapping it in
  * `~~strikethrough~~` and appending a `**Done** — PR [#N](url) ...` sub-bullet.
  * If every issue under the same `### repo/name` heading is now struck through,
@@ -19,7 +22,8 @@ export interface MarkDoneOptions {
     listPath: string;
 }
 export interface MarkDoneOutput {
-    /** True if the line was found and updated. False on already-marked or not-found. */
+    /** True if the line was found and updated. False only when already marked
+     * done — a URL missing from the list entirely throws instead (#1406). */
     marked: boolean;
     /** Fully-resolved file path that was inspected. */
     filePath: string;
@@ -32,6 +36,8 @@ export interface MarkDoneOutput {
     /** Human-readable explanation when `marked` is false. */
     reason?: string;
 }
+/** Discriminates the two `marked: false` outcomes of {@link markIssueAsDone}. */
+export type MarkDoneNoOpReason = 'not-found' | 'already-marked';
 /** Pure transform — exposed for unit testing. */
 export declare function markIssueAsDone(content: string, opts: {
     issueUrl: string;
@@ -43,6 +49,8 @@ export declare function markIssueAsDone(content: string, opts: {
     repoHeadingStruck: boolean;
     remainingUnderRepo: number;
     reason?: string;
+    /** Set only when `marked` is false — why nothing changed. */
+    reasonCode?: MarkDoneNoOpReason;
 };
 /** Read → transform → write atomically (tmp + rename) so a crash mid-write can't corrupt the file. */
 export declare function runMarkIssueListItemDone(options: MarkDoneOptions): Promise<MarkDoneOutput>;

package/dist/commands/list-mark-done.js

@@ -1,6 +1,9 @@
 /**
  * list-mark-done command (#1299).
  *
+ * A URL that is not in the list at all is an error (#1406) — marking done
+ * requires an existing entry; only the already-marked re-run is a quiet no-op.
+ *
  * Mark an issue line in a curated list as done by wrapping it in
  * `~~strikethrough~~` and appending a `**Done** — PR [#N](url) ...` sub-bullet.
  * If every issue under the same `### repo/name` heading is now struck through,
@@ -13,7 +16,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { errorMessage } from '../core/errors.js';
+import { errorMessage, ValidationError } from '../core/errors.js';
 const STRIKE = '~~';
 const DONE_PREFIX = '  - **Done**';
 const ISSUE_LINE_RE = /^[*+-]\s/;
@@ -113,6 +116,7 @@ export function markIssueAsDone(content, opts) {
             repoHeadingStruck: false,
             remainingUnderRepo: 0,
             reason: 'issue URL not found in the list',
+            reasonCode: 'not-found',
         };
     }
     const issueLine = lines[block.start];
@@ -126,6 +130,7 @@ export function markIssueAsDone(content, opts) {
             repoHeadingStruck: false,
             remainingUnderRepo: section ? countOpenIssues(lines, section) : 0,
             reason: 'already marked done',
+            reasonCode: 'already-marked',
         };
     }
     // 1. Strike the issue line.
@@ -186,6 +191,14 @@ export async function runMarkIssueListItemDone(options) {
         prUrl: options.prUrl,
         prStatus: options.prStatus,
     });
+    // #1406: a missing entry is a caller error, not a quiet success — the
+    // consumer branch in workflows/draft-first-workflow.md already documents
+    // this contract (STOP on success:false mentioning "Issue URL not found").
+    // Idempotent re-runs (already marked done) still resolve normally.
+    if (result.reasonCode === 'not-found') {
+        throw new ValidationError(`Issue URL not found in the list: ${options.issueUrl} (${filePath}). ` +
+            'Check the URL and --list-path; the entry must exist before it can be marked done.');
+    }
     if (result.marked) {
         const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
         try {

package/dist/commands/search.d.ts

@@ -10,6 +10,14 @@ export { type SearchOutput } from '../formatters/json.js';
  * lands in one place instead of three (#1002).
  */
 export declare const MAX_SEARCH_RESULTS = 100;
+/**
+ * Fraction of search slots reserved for candidates that matched neither
+ * strategy-preferred languages nor repos (#1244). Counterweight against
+ * echo-chamber bias: without it, strategy-boosted searches return more of
+ * what already merged, which merges more of the same, and the profile
+ * narrows over time. Scout clamps to [0, 1]; 0.2 is the issue's proposal.
+ */
+export declare const SEARCH_DIVERSITY_RATIO = 0.2;
 interface SearchOptions {
     maxResults: number;
 }

package/dist/commands/search.js

@@ -14,6 +14,14 @@ const MODULE = 'search';
  * lands in one place instead of three (#1002).
  */
 export const MAX_SEARCH_RESULTS = 100;
+/**
+ * Fraction of search slots reserved for candidates that matched neither
+ * strategy-preferred languages nor repos (#1244). Counterweight against
+ * echo-chamber bias: without it, strategy-boosted searches return more of
+ * what already merged, which merges more of the same, and the profile
+ * narrows over time. Scout clamps to [0, 1]; 0.2 is the issue's proposal.
+ */
+export const SEARCH_DIVERSITY_RATIO = 0.2;
 /**
  * Search GitHub for contributable issues using multi-phase discovery.
  *
@@ -63,6 +71,7 @@ export async function runSearch(options) {
         maxResults: options.maxResults,
         preferLanguages,
         preferRepos,
+        diversityRatio: SEARCH_DIVERSITY_RATIO,
     });
     // #1354: never surface issues the user already has an open PR for. Uses
     // scout's structured linked-PR metadata when present; candidates without it
@@ -128,6 +137,7 @@ export async function runSearch(options) {
                 ...(linkedPR ? { linkedPR } : {}),
                 ...(typeof c.boostScore === 'number' ? { boostScore: c.boostScore } : {}),
                 ...(c.boostReasons && c.boostReasons.length > 0 ? { boostReasons: c.boostReasons } : {}),
+                ...(c.diversitySlot === true ? { diversitySlot: true } : {}),
             };
         }),
         excludedRepos: result.excludedRepos,

package/dist/formatters/json.d.ts

@@ -648,6 +648,7 @@ export declare const SearchOutputSchema: z.ZodObject<{
         }, z.core.$strip>>;
         boostScore: z.ZodOptional<z.ZodNumber>;
         boostReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        diversitySlot: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     excludedRepos: z.ZodArray<z.ZodString>;
     aiPolicyBlocklist: z.ZodArray<z.ZodString>;
@@ -707,6 +708,7 @@ export declare const FeaturesOutputSchema: z.ZodObject<{
         }, z.core.$strip>>;
         boostScore: z.ZodOptional<z.ZodNumber>;
         boostReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        diversitySlot: z.ZodOptional<z.ZodBoolean>;
         horizon: z.ZodEnum<{
             "quick-win": "quick-win";
             "bigger-bet": "bigger-bet";
@@ -764,6 +766,7 @@ export declare const FeaturesOutputSchema: z.ZodObject<{
         }, z.core.$strip>>;
         boostScore: z.ZodOptional<z.ZodNumber>;
         boostReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        diversitySlot: z.ZodOptional<z.ZodBoolean>;
         horizon: z.ZodEnum<{
             "quick-win": "quick-win";
             "bigger-bet": "bigger-bet";
@@ -816,7 +819,7 @@ export declare const ListMarkDoneOutputSchema: z.ZodObject<{
     url: z.ZodString;
     repoHeadingStruck: z.ZodBoolean;
     remainingUnderRepo: z.ZodNumber;
-    reason: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodLiteral<"already marked done">>;
 }, z.core.$strip>;
 export declare const VerifyIssueOutputSchema: z.ZodObject<{
     url: z.ZodString;
@@ -1216,6 +1219,12 @@ export interface SearchCandidate {
      * opportunities (open PR + no updates for 30+ days, scout 0.9.0 #97).
      */
     linkedPR?: CandidateLinkedPR;
+    /** Strategy-bias sort boost from scout (#1244); absent when unboosted. */
+    boostScore?: number;
+    /** Human-readable boost explanations, e.g. "repo affinity: vercel/next.js". */
+    boostReasons?: string[];
+    /** True when this candidate filled a diversity slot (#1244). */
+    diversitySlot?: boolean;
 }
 export interface SearchOutput {
     candidates: SearchCandidate[];

package/dist/formatters/json.js

@@ -353,6 +353,9 @@ const SearchCandidateSchema = z.object({
      */
     boostScore: z.number().optional(),
     boostReasons: z.array(z.string()).optional(),
+    /** True when this candidate filled a diversity slot (#1244) — surfaced so
+     * the user can see the counterweight working, not just its absence. */
+    diversitySlot: z.boolean().optional(),
 });
 export const SearchOutputSchema = z.object({
     candidates: z.array(SearchCandidateSchema),
@@ -421,7 +424,10 @@ export const ListMarkDoneOutputSchema = z.object({
     url: z.string(),
     repoHeadingStruck: z.boolean(),
     remainingUnderRepo: z.number().int().nonnegative(),
-    reason: z.string().optional(),
+    // #1406: not-found now throws before the success envelope, so the only
+    // reachable no-op reason is the idempotent one. Pinned so a new quiet
+    // no-op path trips the #1105 runtime validator instead of shipping silently.
+    reason: z.literal('already marked done').optional(),
 });
 // verify-issue (#1353, #1354): mirrors {@link IssueVerification} from
 // core/issue-verification.ts. Strict shape — additional keys must be added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {