@deftai/directive-core 0.69.0 → 0.70.0

package/dist/triage/welcome/onboard.d.ts

@@ -0,0 +1,35 @@
+/** Default triage-scope preset applied when `--onboard` is run without `--preset`. */
+export declare const DEFAULT_ONBOARD_PRESET = "small";
+export interface OnboardOptions {
+    /** Triage-scope preset key; defaults to {@link DEFAULT_ONBOARD_PRESET}. */
+    readonly preset?: string | null;
+    /** Explicit WIP cap to persist; omitted keeps the current/default cap. */
+    readonly wipCap?: number | null;
+    readonly output?: (line: string) => void;
+    readonly writeHistory?: boolean;
+    readonly taskPrefix?: string | null;
+    readonly selfHealFn?: (projectRoot: string) => void;
+    readonly now?: Date;
+}
+export interface OnboardOutcome {
+    readonly exitCode: number;
+    readonly presetApplied: string | null;
+    readonly triageScopeChanged: boolean;
+    readonly wipCapApplied: number | null;
+    readonly wipCapChanged: boolean;
+    readonly reliefOffered: boolean;
+}
+/**
+ * Non-interactive onboarding for `deft triage:welcome --onboard` (#2295).
+ *
+ * The welcome nudges point every fresh consumer at `--onboard`; this wires that
+ * command to the already-tested core writers instead of the old "not
+ * implemented" stub. It writes the chosen triage-scope preset and (optionally)
+ * a WIP cap via {@link writeTriageScope} / {@link writeWipCap} -- which already
+ * target the canonical `x-directive/policy` key and migrate any legacy bare
+ * block -- previews WIP relief when at/over cap, then prints a completion
+ * summary and the next-step guidance. Flag-driven by design: agents/CI pass
+ * `--preset` / `--wip-cap`; sensible defaults apply otherwise.
+ */
+export declare function runOnboardMode(projectRoot: string, options?: OnboardOptions): OnboardOutcome;
+//# sourceMappingURL=onboard.d.ts.map

package/dist/triage/welcome/onboard.js

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { maybeSelfHealCache } from "../../cache/fetch.js";
+import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
+import { DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, TRIAGE_SKILL_PATH } from "./constants.js";
+import { formatWelcomeCommand } from "./default-mode.js";
+import { detectPriorState } from "./prior-state.js";
+import { emitOneliner } from "./summary.js";
+import { previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap } from "./writers.js";
+/** Default triage-scope preset applied when `--onboard` is run without `--preset`. */
+export const DEFAULT_ONBOARD_PRESET = "small";
+function failure(exitCode) {
+    return {
+        exitCode,
+        presetApplied: null,
+        triageScopeChanged: false,
+        wipCapApplied: null,
+        wipCapChanged: false,
+        reliefOffered: false,
+    };
+}
+/**
+ * Non-interactive onboarding for `deft triage:welcome --onboard` (#2295).
+ *
+ * The welcome nudges point every fresh consumer at `--onboard`; this wires that
+ * command to the already-tested core writers instead of the old "not
+ * implemented" stub. It writes the chosen triage-scope preset and (optionally)
+ * a WIP cap via {@link writeTriageScope} / {@link writeWipCap} -- which already
+ * target the canonical `x-directive/policy` key and migrate any legacy bare
+ * block -- previews WIP relief when at/over cap, then prints a completion
+ * summary and the next-step guidance. Flag-driven by design: agents/CI pass
+ * `--preset` / `--wip-cap`; sensible defaults apply otherwise.
+ */
+export function runOnboardMode(projectRoot, options = {}) {
+    const out = options.output ?? ((line) => process.stdout.write(`${line}\n`));
+    const preset = (options.preset ?? DEFAULT_ONBOARD_PRESET).trim() || DEFAULT_ONBOARD_PRESET;
+    if (!Object.hasOwn(SUBSCRIPTION_PRESETS, preset)) {
+        out(`[welcome] Unknown --preset '${preset}'. Choose one of: ${Object.keys(SUBSCRIPTION_PRESETS).join(", ")}.`);
+        return failure(2);
+    }
+    const wipCap = options.wipCap ?? null;
+    if (wipCap !== null && (!Number.isInteger(wipCap) || wipCap < 1)) {
+        out(`[welcome] --wip-cap must be a positive integer, got ${JSON.stringify(options.wipCap)}.`);
+        return failure(2);
+    }
+    const pdPath = resolveProjectDefinitionPath(projectRoot);
+    if (!existsSync(pdPath)) {
+        out(`[welcome] No project definition found at ${pdPath}. Run project setup first (deft-directive-setup) before onboarding triage.`);
+        return failure(2);
+    }
+    const heal = options.selfHealFn ??
+        ((root) => {
+            maybeSelfHealCache(resolve(root));
+        });
+    heal(projectRoot);
+    const rules = subscriptionPreset(preset);
+    const [triageScopeChanged] = writeTriageScope(projectRoot, rules, { presetLabel: preset });
+    let wipCapChanged = false;
+    if (wipCap !== null) {
+        [wipCapChanged] = writeWipCap(projectRoot, wipCap);
+    }
+    emitOneliner(projectRoot, {
+        writeHistory: options.writeHistory !== false,
+        now: options.now,
+        output: out,
+        applyD2Suppression: false,
+    });
+    const state = detectPriorState(projectRoot);
+    let reliefOffered = false;
+    if (state.wipCount >= state.wipCap) {
+        const relief = previewWipRelief(projectRoot);
+        if (relief.eligibleCount > 0) {
+            reliefOffered = true;
+            const demote = formatWelcomeCommand(["scope:demote", "--batch", "--older-than-days", String(relief.olderThanDays)], options.taskPrefix).replace(/\r?\n/g, " ");
+            const eligibleCount = String(relief.eligibleCount).replace(/\r?\n/g, " ");
+            out(`[welcome] WIP ${state.wipCount}/${state.wipCap} at/over cap -- ${eligibleCount} pending scope(s) ` +
+                `older than ${relief.olderThanDays}d are demote-eligible. Relieve with \`${demote}\`.`);
+        }
+    }
+    const capNote = wipCap !== null ? `, wipCap ${wipCap}` : ` (wipCap default ${DEFAULT_WIP_CAP})`;
+    out(`[welcome] Onboarding applied: triage scope preset '${preset}'${capNote}.`);
+    const bootstrap = formatWelcomeCommand(["triage:bootstrap"], options.taskPrefix);
+    const queue = formatWelcomeCommand(["triage:queue", "--limit=10"], options.taskPrefix);
+    out(`[welcome] Next: run \`${bootstrap}\` to populate the triage cache, then \`${queue}\` to pick work. See ${TRIAGE_SKILL_PATH}.`);
+    return {
+        exitCode: 0,
+        presetApplied: preset,
+        triageScopeChanged,
+        wipCapApplied: wipCap,
+        wipCapChanged,
+        reliefOffered,
+    };
+}
+//# sourceMappingURL=onboard.js.map

package/dist/umbrella-current-shape/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * #2307: only comments authored by a repo maintainer may be treated as the
+ * authoritative current-shape state. GitHub's `author_association` on an issue
+ * comment is the trust signal; anything outside this set (CONTRIBUTOR, NONE,
+ * FIRST_TIME_CONTRIBUTOR, ...) is an untrusted third party and cannot forge a
+ * higher-pass current-shape comment.
+ */
+export declare const MAINTAINER_ASSOCIATIONS: ReadonlySet<string>;
+/** True when a comment's author_association marks it as maintainer-authored (#2307). */
+export declare function isMaintainerAuthored(association: string): boolean;
 /** Matches `## Current shape (as of pass-N)` — same pattern as vbrief-reconcile/umbrellas.ts. */
 export declare const CURRENT_SHAPE_HEADER_RE: RegExp;
 export declare const SECTION_MARKERS: {
@@ -20,6 +30,8 @@ export interface IssueComment {
     readonly body: string;
     readonly htmlUrl: string;
     readonly updatedAt: string;
+    readonly authorLogin: string;
+    readonly authorAssociation: string;
 }
 export interface CurrentShapeComment extends IssueComment {
     readonly pass: number;
@@ -37,6 +49,8 @@ export interface CurrentShapeResult {
     readonly htmlUrl: string;
     readonly pass: number;
     readonly body: string;
+    readonly authorLogin: string;
+    readonly authorAssociation: string;
     readonly sections: SectionPresence;
 }
 export type ScmFetcher = (repo: string, issueNumber: number) => IssueComment[] | {
@@ -55,11 +69,20 @@ export interface RunCurrentShapeOptions {
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
 export declare function parseCommentsFromGhStdout(stdout: string): IssueComment[];
 export declare function extractPassFromBody(body: string): number | null;
-/** Pick the canonical comment — highest pass-N; tie-break by comment id (latest). */
+/**
+ * Pick the canonical comment — highest pass-N; tie-break by comment id (latest).
+ *
+ * #2307: only MAINTAINER-authored comments (author_association in
+ * {OWNER, MEMBER, COLLABORATOR}) are eligible. A non-maintainer higher-pass
+ * comment is ignored, which defeats the forged-higher-pass primitive: an
+ * attacker cannot inject authoritative state by simply commenting with a bigger
+ * pass number.
+ */
 export declare function selectCurrentShapeComment(comments: readonly IssueComment[]): CurrentShapeComment | null;
 export declare function detectSections(body: string): SectionPresence;
 export declare function sectionsRecord(presence: SectionPresence): Record<string, boolean>;
 export declare const NO_CURRENT_SHAPE_MESSAGE: string;
+export declare const NON_MAINTAINER_CURRENT_SHAPE_MESSAGE: string;
 export declare function fetchCurrentShape(options: {
     repo: string;
     issueNumber: number;
@@ -75,6 +98,7 @@ export declare function fetchCurrentShape(options: {
 export declare function emitCurrentShape(result: CurrentShapeResult, options: {
     jsonMode: boolean;
     writeOut: (text: string) => void;
+    writeErr?: (text: string) => void;
 }): number;
 export declare function runCurrentShape(options: RunCurrentShapeOptions): number;
 export declare function parseCurrentShapeArgv(argv: readonly string[]): {

package/dist/umbrella-current-shape/index.js

@@ -1,7 +1,24 @@
 import { spawnSync } from "node:child_process";
+import { scan } from "../cache/scanner.js";
 import { resolveBinary } from "../scm/binary.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { resolveRepo } from "../triage/queue/repo.js";
+/**
+ * #2307: only comments authored by a repo maintainer may be treated as the
+ * authoritative current-shape state. GitHub's `author_association` on an issue
+ * comment is the trust signal; anything outside this set (CONTRIBUTOR, NONE,
+ * FIRST_TIME_CONTRIBUTOR, ...) is an untrusted third party and cannot forge a
+ * higher-pass current-shape comment.
+ */
+export const MAINTAINER_ASSOCIATIONS = new Set([
+    "OWNER",
+    "MEMBER",
+    "COLLABORATOR",
+]);
+/** True when a comment's author_association marks it as maintainer-authored (#2307). */
+export function isMaintainerAuthored(association) {
+    return MAINTAINER_ASSOCIATIONS.has(association.toUpperCase());
+}
 /** Matches `## Current shape (as of pass-N)` — same pattern as vbrief-reconcile/umbrellas.ts. */
 export const CURRENT_SHAPE_HEADER_RE = /^## Current shape \(as of pass-(\d+)\)/m;
 export const SECTION_MARKERS = {
@@ -35,11 +52,16 @@ function mapCommentEntry(entry) {
     if (typeof rec.id !== "number" || typeof rec.body !== "string") {
         return null;
     }
+    const user = typeof rec.user === "object" && rec.user !== null
+        ? rec.user
+        : null;
     return {
         id: rec.id,
         body: rec.body,
         htmlUrl: typeof rec.html_url === "string" ? rec.html_url : "",
         updatedAt: typeof rec.updated_at === "string" ? rec.updated_at : "",
+        authorLogin: user !== null && typeof user.login === "string" ? user.login : "",
+        authorAssociation: typeof rec.author_association === "string" ? rec.author_association : "",
     };
 }
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
@@ -135,10 +157,21 @@ export function extractPassFromBody(body) {
     const pass = Number(match[1]);
     return Number.isFinite(pass) ? pass : null;
 }
-/** Pick the canonical comment — highest pass-N; tie-break by comment id (latest). */
+/**
+ * Pick the canonical comment — highest pass-N; tie-break by comment id (latest).
+ *
+ * #2307: only MAINTAINER-authored comments (author_association in
+ * {OWNER, MEMBER, COLLABORATOR}) are eligible. A non-maintainer higher-pass
+ * comment is ignored, which defeats the forged-higher-pass primitive: an
+ * attacker cannot inject authoritative state by simply commenting with a bigger
+ * pass number.
+ */
 export function selectCurrentShapeComment(comments) {
     let best = null;
     for (const comment of comments) {
+        if (!isMaintainerAuthored(comment.authorAssociation)) {
+            continue;
+        }
         const pass = extractPassFromBody(comment.body);
         if (pass === null) {
             continue;
@@ -188,6 +221,16 @@ export function sectionsRecord(presence) {
 export const NO_CURRENT_SHAPE_MESSAGE = "No ## Current shape (as of pass-N) comment found on this issue. " +
     "Create one per AGENTS.md ## Umbrella current-shape convention (#1152) — " +
     "do not fall back to the issue body (stale by design).";
+// #2307 (Greptile review): a structurally valid current-shape comment authored
+// by a non-maintainer is filtered out for provenance and would otherwise be
+// reported with the generic "not found" message above -- indistinguishable from
+// genuine absence, which makes --strict especially confusing to debug. This
+// message names the provenance filter explicitly so the caller knows the
+// comment exists but was ignored, not that it is missing.
+export const NON_MAINTAINER_CURRENT_SHAPE_MESSAGE = "A ## Current shape (as of pass-N) comment exists but was authored by a " +
+    "non-maintainer (author_association not in OWNER/MEMBER/COLLABORATOR) and is " +
+    "ignored per AGENTS.md ## Umbrella current-shape convention (#1152 / #2307). " +
+    "A maintainer must (re-)post the current-shape comment for it to be authoritative.";
 export function fetchCurrentShape(options) {
     const fetcher = options.fetchComments ?? defaultFetchComments;
     const fetched = fetcher(options.repo, options.issueNumber);
@@ -196,7 +239,15 @@ export function fetchCurrentShape(options) {
     }
     const selected = selectCurrentShapeComment(fetched);
     if (selected === null) {
-        return { ok: false, error: NO_CURRENT_SHAPE_MESSAGE, kind: "not-found" };
+        // Distinguish provenance-filtered absence from genuine absence (#2307).
+        const hadNonMaintainerShape = fetched.some((c) => extractPassFromBody(c.body) !== null && !isMaintainerAuthored(c.authorAssociation));
+        return {
+            ok: false,
+            error: hadNonMaintainerShape
+                ? NON_MAINTAINER_CURRENT_SHAPE_MESSAGE
+                : NO_CURRENT_SHAPE_MESSAGE,
+            kind: "not-found",
+        };
     }
     const sections = detectSections(selected.body);
     return {
@@ -208,11 +259,36 @@ export function fetchCurrentShape(options) {
             htmlUrl: selected.htmlUrl,
             pass: selected.pass,
             body: selected.body,
+            authorLogin: selected.authorLogin,
+            authorAssociation: selected.authorAssociation,
             sections,
         },
     };
 }
 export function emitCurrentShape(result, options) {
+    // #2307: the selected comment body is still attacker-influencable text (a
+    // maintainer can quote/paste untrusted content). Run it through the same
+    // quarantine scanner used for cache content and emit the fenced transform so
+    // injection-shaped sections are quarantined, never rendered as authoritative
+    // instructions.
+    const scanned = scan(result.body);
+    // #2307 fail-closed (Greptile review): a scanner hard-fail (e.g. a credential
+    // pattern) is only FLAGGED by scan() -- detectCredentials sets passed=false
+    // but does NOT redact the secret from transformed_content. Emitting the
+    // transform regardless would forward the raw credential to stdout / CI logs /
+    // JSON consumers. Mirror buildIssueVbrief (#2306, issue:ingest), which throws
+    // ScannerHardFailError and writes nothing: refuse to emit and return non-zero.
+    if (!scanned.passed) {
+        const details = scanned.flags
+            .filter((f) => f.severity === "hard-fail")
+            .map((f) => f.detail)
+            .join("; ");
+        const writeErr = options.writeErr ?? ((text) => process.stderr.write(text));
+        writeErr(`umbrella:current-shape: refused issue #${result.issueNumber}: quarantine scanner hard-fail` +
+            (details.length > 0 ? ` (${details})` : "") +
+            " -- nothing written.\n");
+        return 1;
+    }
     if (options.jsonMode) {
         const payload = {
             issueNumber: result.issueNumber,
@@ -220,7 +296,10 @@ export function emitCurrentShape(result, options) {
             commentId: result.commentId,
             htmlUrl: result.htmlUrl,
             pass: result.pass,
-            body: result.body,
+            body: scanned.transformed_content,
+            authorLogin: result.authorLogin,
+            authorAssociation: result.authorAssociation,
+            scannerPassed: scanned.passed,
             sections: sectionsRecord(result.sections),
             missingSections: result.sections.missing,
             missingOptionalSections: result.sections.optionalMissing,
@@ -228,7 +307,7 @@ export function emitCurrentShape(result, options) {
         options.writeOut(`${JSON.stringify(payload)}\n`);
     }
     else {
-        options.writeOut(`${result.body}\n`);
+        options.writeOut(`${scanned.transformed_content}\n`);
     }
     return 0;
 }
@@ -260,6 +339,7 @@ export function runCurrentShape(options) {
     return emitCurrentShape(fetched.result, {
         jsonMode: options.jsonMode ?? false,
         writeOut,
+        writeErr,
     });
 }
 export function parseCurrentShapeArgv(argv) {

package/dist/vbrief-build/project-definition-io.d.ts

@@ -1,4 +1,10 @@
 import type { JsonObject } from "./types.js";
+/**
+ * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
+ * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
+ * legacy `vbrief/PROJECT-DEFINITION.vbrief.json`, so loader not-found messages
+ * name the path that actually applies to the project's layout.
+ */
 export declare function projectDefinitionPath(projectRoot: string): string;
 export interface MutationLockDeps {
     readonly sleepMs?: (ms: number) => void;

package/dist/vbrief-build/project-definition-io.js

@@ -2,12 +2,17 @@ import { randomBytes } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { PROJECT_DEFINITION_REL_PATH } from "./constants.js";
 import { pythonJsonPretty } from "./json.js";
 import { ProjectDefinitionIOError } from "./types.js";
 const mutationThreadLock = { held: false };
+/**
+ * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
+ * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
+ * legacy `vbrief/PROJECT-DEFINITION.vbrief.json`, so loader not-found messages
+ * name the path that actually applies to the project's layout.
+ */
 export function projectDefinitionPath(projectRoot) {
-    return join(projectRoot, PROJECT_DEFINITION_REL_PATH);
+    return resolveProjectDefinitionPath(resolve(projectRoot));
 }
 function defaultSleep(ms) {
     const end = Date.now() + ms;

package/dist/vbrief-validate/precutover.js

@@ -103,9 +103,13 @@ export function detectPreCutover(projectRoot) {
 /** Last release that ships `scripts/migrate_vbrief.py` on the consumer deposit path (#2068). */
 export const FROZEN_PRECUTOVER_MIGRATION_TAG = "v0.59.0";
 export function frozenPreCutoverMigrationGuidance() {
-    return (`Current npm releases no longer ship in-product \`task migrate:vbrief\`. Pin framework ${FROZEN_PRECUTOVER_MIGRATION_TAG} ` +
-        `(frozen Go installer or git tag), install Python 3.11+ and uv, run \`task migrate:vbrief\` once from that payload, ` +
-        `then upgrade to current npm. See UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).`);
+    return (`Current npm releases no longer ship in-product \`task migrate:vbrief\`. Best-effort path (anchored on the ` +
+        `${FROZEN_PRECUTOVER_MIGRATION_TAG} git tag, from which GitHub serves a source tarball on demand): pin framework ` +
+        `${FROZEN_PRECUTOVER_MIGRATION_TAG}, install Python 3.11+ and uv, run \`task migrate:vbrief\` once from that payload, ` +
+        `then upgrade to current npm. This is a two-hop chain: pre-v0.20 flat model -> vBRIEF v0.6 (on ${FROZEN_PRECUTOVER_MIGRATION_TAG}) ` +
+        `-> xBRIEF via \`deft migrate:xbrief\` on current npm. If the ${FROZEN_PRECUTOVER_MIGRATION_TAG} payload is unavailable, ` +
+        `fall back to a manual fresh start: \`directive init\` a new project on current npm and hand-port your spec content. ` +
+        `See UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).`);
 }
 export function renderPrecutoverLine(projectRoot) {
     const { preCutover, reasons } = detectPreCutover(projectRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -249,8 +249,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.69.0",
-    "@deftai/directive-types": "^0.69.0",
+    "@deftai/directive-content": "^0.70.0",
+    "@deftai/directive-types": "^0.70.0",
     "archiver": "^8.0.0"
   },
   "scripts": {