@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/token-lint.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge token lint`: themed-block lockstep and undeclared token
+ * references (see `core/token-lint.ts` for the rules).
+ *
+ * Helper module: no registrar, called from `token.ts`.
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
+import { buildPatchQueueContext } from '../core/patch-lint.js';
+import { buildJarTargetIndex } from '../core/patch-lint-forward-registration-extended.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { collectDeclaredTokenNames, lintTokenLockstep, lintUndeclaredTokenReferences, } from '../core/token-lint.js';
+import { getTokensCssPath } from '../core/token-manager.js';
+import { buildSiblingSheetMap } from '../core/token-sibling-sheets.js';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, intro, outro, setMachineOutputMode, setStdoutSealed, success, warn, } from '../utils/logger.js';
+import { emitMachineError, MACHINE_OUTPUT_SCHEMA_VERSION } from '../utils/machine-output.js';
+/** Token prefix, exempt names and sibling sheets from furnace.json, with the init default. */
+async function loadTokenSettings(projectRoot, binaryName) {
+    const fallback = { tokenPrefix: `--${binaryName}-`, exempt: new Set() };
+    if (!(await furnaceConfigExists(projectRoot)))
+        return fallback;
+    try {
+        const furnace = await loadFurnaceConfig(projectRoot);
+        return {
+            tokenPrefix: furnace.tokenPrefix ?? fallback.tokenPrefix,
+            exempt: new Set([...(furnace.tokenAllowlist ?? []), ...(furnace.runtimeVariables ?? [])]),
+            siblingSheets: furnace.tokenSiblingSheets,
+        };
+    }
+    catch (error) {
+        warn(`Could not load furnace.json; using the default token prefix (${toError(error).message})`);
+        return fallback;
+    }
+}
+async function collectTokenLint(projectRoot) {
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const tokensCssPath = getTokensCssPath(config.binaryName);
+    const tokensFile = join(paths.engine, tokensCssPath);
+    if (!(await pathExists(tokensFile))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}. Run "fireforge furnace init" to seed it.`);
+    }
+    const { tokenPrefix, exempt, siblingSheets } = await loadTokenSettings(projectRoot, config.binaryName);
+    const tokensCss = await readText(tokensFile);
+    const lines = tokensCss.split('\n');
+    const declared = collectDeclaredTokenNames(lines);
+    const findings = [
+        ...lintTokenLockstep(lines, tokensCssPath, tokenPrefix),
+        ...lintUndeclaredTokenReferences(tokensCssPath, tokensCss, tokenPrefix, declared, exempt),
+    ];
+    // Every CSS file the patch queue touches: the fork's own stylesheets and
+    // the upstream ones it edits.
+    const manifest = await loadPatchesManifest(paths.patches);
+    const touched = [...new Set((manifest?.patches ?? []).flatMap((patch) => patch.filesAffected))];
+    const cssFiles = touched.filter((file) => file.endsWith('.css') && file !== tokensCssPath).sort();
+    const contents = await readEngineFiles(paths.engine, touched.filter((file) => LINKING_FILE.test(file)));
+    const siblings = buildSiblingSheetMap({
+        documents: contents,
+        jarTargets: buildJarTargetIndex((await buildPatchQueueContext(paths.patches)).entries),
+        sheets: cssFiles,
+        explicit: siblingSheets,
+    });
+    let filesScanned = 1;
+    for (const file of cssFiles) {
+        const css = contents.get(file);
+        if (css === undefined)
+            continue;
+        filesScanned++;
+        findings.push(...lintUndeclaredTokenReferences(file, css, tokenPrefix, await withSiblingDeclarations(paths.engine, declared, siblings.get(file), contents), exempt));
+    }
+    return { tokensCssPath, tokenPrefix, filesScanned, findings };
+}
+/** Files whose content can link a stylesheet: markup, scripts, and sheets (`@import`). */
+const LINKING_FILE = /\.(?:css|xhtml|html|xml|mjs|js)$/;
+/** Reads the engine files that exist, keyed by engine-relative path. */
+async function readEngineFiles(engineDir, files) {
+    const contents = new Map();
+    for (const file of files) {
+        const absolute = join(engineDir, file);
+        if (await pathExists(absolute))
+            contents.set(file, await readText(absolute));
+    }
+    return contents;
+}
+/** The tokens CSS declarations plus every declaration of a sheet's siblings. */
+async function withSiblingDeclarations(engineDir, declared, siblings, contents) {
+    if (siblings === undefined || siblings.size === 0)
+        return declared;
+    const merged = new Set(declared);
+    for (const sibling of siblings) {
+        if (!contents.has(sibling)) {
+            const absolute = join(engineDir, sibling);
+            if (!(await pathExists(absolute)))
+                continue;
+            contents.set(sibling, await readText(absolute));
+        }
+        const css = contents.get(sibling) ?? '';
+        for (const name of collectDeclaredTokenNames(css.split('\n')))
+            merged.add(name);
+    }
+    return merged;
+}
+function failureMessage(count) {
+    return `token lint found ${String(count)} finding(s).`;
+}
+/**
+ * Runs `token lint`. Exits non-zero (GeneralError) when any finding is
+ * reported; with `--json` the report is written first, as `status --check
+ * --json` does.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Output-mode options
+ */
+export async function tokenLintCommand(projectRoot, options = {}) {
+    if (options.json === true) {
+        setMachineOutputMode(true);
+        let findings = 0;
+        try {
+            const report = await collectTokenLint(projectRoot);
+            findings = report.findings.length;
+            process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, ...report }, null, 2)}\n`);
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            emitMachineError('token-lint-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
+        if (findings > 0)
+            throw new GeneralError(failureMessage(findings));
+        return;
+    }
+    intro('Token Lint');
+    const report = await collectTokenLint(projectRoot);
+    for (const finding of report.findings) {
+        warn(`${finding.file}:${String(finding.line)} [${finding.check}] ${finding.message}`);
+    }
+    info(`${String(report.filesScanned)} CSS file(s) scanned for ${report.tokenPrefix}* tokens`);
+    if (report.findings.length > 0) {
+        outro('Token lint failed');
+        throw new GeneralError(failureMessage(report.findings.length));
+    }
+    success('Themed blocks are in lockstep with the base block; every token reference resolves');
+    outro('Token lint passed');
+}

package/dist/src/commands/token.js

@@ -10,6 +10,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { normalizeTokenName } from '../utils/validation.js';
 import { tokenCoverageCommand } from './token-coverage.js';
+import { tokenLintCommand } from './token-lint.js';
 import { tokenListCommand, tokenShowCommand } from './token-list.js';
 async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     if (rawTokenName.startsWith('--')) {
@@ -217,6 +218,15 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .action(withErrorHandling(async (tokenName, options) => {
         await tokenShowCommand(getProjectRoot(), tokenName, pickDefined({ json: options.json }));
     }));
+    token
+        .command('lint')
+        .description('Check the token system: themed override blocks declare only tokens the base :root ' +
+        'declares, and every var(--<prefix>…) in the tokens CSS or a patch-touched CSS file ' +
+        'names a declared token. Exits non-zero on any finding')
+        .option('--json', 'Emit the machine-readable envelope on stdout (see docs/machine-output.md)')
+        .action(withErrorHandling(async (options) => {
+        await tokenLintCommand(getProjectRoot(), pickDefined({ json: options.json }));
+    }));
     token
         .command('coverage')
         .description('Measure design token usage across modified CSS files')

package/dist/src/commands/verify-scope.d.ts

@@ -0,0 +1,28 @@
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+/** The resolved scope: manifest filenames, and every path they claim. */
+export interface VerifyScope {
+    patches: ReadonlySet<string>;
+    files: ReadonlySet<string>;
+}
+/**
+ * Resolves raw `--patches` values against the manifest. Returns undefined
+ * when the flag was not given and refuses a name that matches no patch.
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ */
+export declare function resolveVerifyScope(patchesDir: string, requested: readonly string[] | undefined): Promise<VerifyScope | undefined>;
+/**
+ * True when a filename-keyed finding (manifest consistency, policy) is in
+ * scope: it names a scoped patch, or it names no patch at all.
+ */
+export declare function isFilenameInScope(scope: VerifyScope | undefined, filename: string): boolean;
+/** True when any of the implicated patches is in scope. */
+export declare function anyPatchInScope(scope: VerifyScope | undefined, filenames: readonly string[]): boolean;
+/**
+ * Keeps the lint issues that implicate a scoped patch. An issue without a
+ * `patches` list is attributed through its file instead.
+ */
+export declare function scopeLintIssues(issues: PatchLintIssue[], scope: VerifyScope | undefined): PatchLintIssue[];
+/** Keeps the manifest rows in scope. No scope keeps all. */
+export declare function scopePatches<T extends Pick<PatchMetadata, 'filename'>>(patches: readonly T[], scope: VerifyScope | undefined): T[];

package/dist/src/commands/verify-scope.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `verify --patches <list>`: judges only the named patches' findings. Split
+ * out of verify.ts so the per-group attribution rules sit in one place.
+ *
+ * A finding is in scope when it names a scoped patch: a manifest or policy
+ * issue by its filename, a cross-patch claim or lint issue by any patch it
+ * implicates, a drifted file by its owning patch, a dangling registration
+ * by the patch that registers it. Findings about the queue as a whole (a
+ * manifest that does not parse) are kept, because no patch can be judged
+ * past them. Unowned worktree changes belong to no patch and drop out.
+ */
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { selectPatchSubset } from '../core/patch-subset.js';
+import { GeneralError } from '../errors/base.js';
+/**
+ * Resolves raw `--patches` values against the manifest. Returns undefined
+ * when the flag was not given and refuses a name that matches no patch.
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ */
+export async function resolveVerifyScope(patchesDir, requested) {
+    if (requested === undefined || requested.length === 0)
+        return undefined;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('--patches needs a patch queue, but patches.json lists no patches.');
+    }
+    const subset = selectPatchSubset(manifest, requested, '--patches selects patches (filename, stem, order number, manifest name, or slug).');
+    return {
+        patches: new Set(subset.map((patch) => patch.filename)),
+        files: new Set(subset.flatMap((patch) => patch.filesAffected)),
+    };
+}
+/**
+ * True when a filename-keyed finding (manifest consistency, policy) is in
+ * scope: it names a scoped patch, or it names no patch at all.
+ */
+export function isFilenameInScope(scope, filename) {
+    if (scope === undefined)
+        return true;
+    return scope.patches.has(filename) || !filename.endsWith('.patch');
+}
+/** True when any of the implicated patches is in scope. */
+export function anyPatchInScope(scope, filenames) {
+    if (scope === undefined)
+        return true;
+    return filenames.some((filename) => scope.patches.has(filename));
+}
+/**
+ * Keeps the lint issues that implicate a scoped patch. An issue without a
+ * `patches` list is attributed through its file instead.
+ */
+export function scopeLintIssues(issues, scope) {
+    if (scope === undefined)
+        return issues;
+    return issues.filter((issue) => issue.patches !== undefined && issue.patches.length > 0
+        ? anyPatchInScope(scope, issue.patches)
+        : scope.files.has(issue.file));
+}
+/** Keeps the manifest rows in scope. No scope keeps all. */
+export function scopePatches(patches, scope) {
+    if (scope === undefined)
+        return [...patches];
+    return patches.filter((patch) => scope.patches.has(patch.filename));
+}

package/dist/src/commands/verify.d.ts

@@ -15,6 +15,7 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+import { type VerifyScope } from './verify-scope.js';
 interface VerifyIssueGroup {
     title: string;
     issues: string[];
@@ -31,15 +32,22 @@ export interface PatchQueueHealth {
  * Collects the same queue-health findings reported by `fireforge verify`
  * without printing. Used by doctor recovery paths that need a read-only
  * "is this queue healthy?" decision before clearing stale state.
+ *
+ * @param projectRoot - Project root directory
+ * @param scope - `verify --patches`: keep only the findings that name these
+ *   patches (see verify-scope.ts). Omitted, every finding counts.
  */
-export declare function collectPatchQueueHealth(projectRoot: string): Promise<PatchQueueHealth>;
+export declare function collectPatchQueueHealth(projectRoot: string, scope?: VerifyScope): Promise<PatchQueueHealth>;
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
  * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
+ * @param options - `patches`: the raw `--patches` values
  */
-export declare function verifyCommand(projectRoot: string): Promise<void>;
+export declare function verifyCommand(projectRoot: string, options?: {
+    patches?: string[];
+}): Promise<void>;
 /**
  * Registers the `verify` command on the CLI program.
  *

package/dist/src/commands/verify.js

@@ -21,16 +21,18 @@ import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { isGitRepository } from '../core/git.js';
 import { withPrivateGitIndex } from '../core/git-readonly-index.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
-import { findUnresolvedSystemModuleImports, formatUnresolvedSystemModuleImports, } from '../core/module-resolution-preflight.js';
+import { collectWorktreeModuleFiles, findUnresolvedSystemModuleImports, formatUnresolvedSystemModuleImports, } from '../core/module-resolution-preflight.js';
 import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
 import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
+import { evaluatePatchPolicyContentForQueue } from '../core/patch-policy-content.js';
 import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
 import { buildPatchClaims } from '../core/status-classify.js';
 import { classifyFiles } from '../core/status-classify.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { anyPatchInScope, isFilenameInScope, resolveVerifyScope, scopeLintIssues, scopePatches, } from './verify-scope.js';
 /**
  * Walks each patch body in the manifest, extracts the set of
  * component-shaped registration references it adds (widget paths
@@ -41,7 +43,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
  * registers a file that nothing in the world supplies, which fails at
  * install time.
  */
-async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
+async function detectDanglingRegistrations(patchesDir, engineDir, patches, scope) {
     // Aggregate the set of all paths any patch in the queue is responsible for
     // (per `filesAffected`). Individual patch bodies are deliberately not
     // parsed for new-file creations here: `filesAffected` is already the
@@ -54,8 +56,9 @@ async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
             coveredByPatches.add(file);
         }
     }
+    // Every patch supplies targets; only the scoped ones are judged.
     const issues = [];
-    for (const patch of patches) {
+    for (const patch of scopePatches(patches, scope)) {
         const patchPath = join(patchesDir, patch.filename);
         if (!(await pathExists(patchPath)))
             continue;
@@ -100,7 +103,7 @@ function detectCrossPatchFileClaims(manifestPatches) {
     }
     return results;
 }
-async function detectWorktreeOwnershipDrift(projectRoot, engineDir, patchesDir, binaryName) {
+async function detectWorktreeOwnershipDrift(projectRoot, engineDir, patchesDir, binaryName, scope) {
     if (!(await pathExists(engineDir)) || !(await isGitRepository(engineDir))) {
         return { unowned: [], patchOwnedDrift: [] };
     }
@@ -108,24 +111,51 @@ async function detectWorktreeOwnershipDrift(projectRoot, engineDir, patchesDir,
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
     const classified = await classifyFiles(entries, engineDir, patchesDir, binaryName, furnacePrefixes);
     return {
+        // An unowned change belongs to no patch, so no --patches scope covers it.
         unowned: [
             ...new Set(classified
-                .filter((entry) => entry.classification === 'unmanaged')
+                .filter((entry) => scope === undefined && entry.classification === 'unmanaged')
                 .map((entry) => entry.file)),
         ].sort(),
         patchOwnedDrift: [
             ...new Set(classified
-                .filter((entry) => entry.classification === 'patch-owned-drift')
+                .filter((entry) => entry.classification === 'patch-owned-drift' &&
+                anyPatchInScope(scope, entry.owner === undefined ? [] : [entry.owner]))
                 .map((entry) => entry.file)),
         ].sort(),
     };
 }
+/** The warning groups for unowned changes and patch-owned drift. */
+function buildWorktreeDriftGroups(drift) {
+    const groups = [];
+    if (drift.unowned.length > 0) {
+        groups.push({
+            title: `Unowned worktree changes (${drift.unowned.length})`,
+            issues: drift.unowned.map((file) => `${file} is changed in engine/ but is not listed in any patch filesAffected entry`),
+            errorCount: 0,
+            warningCount: drift.unowned.length,
+        });
+    }
+    if (drift.patchOwnedDrift.length > 0) {
+        groups.push({
+            title: `Patch-owned worktree drift (${drift.patchOwnedDrift.length})`,
+            issues: drift.patchOwnedDrift.map((file) => `${file} is claimed by exactly one patch, but engine/ no longer matches that patch output`),
+            errorCount: 0,
+            warningCount: drift.patchOwnedDrift.length,
+        });
+    }
+    return groups;
+}
 /**
  * Collects the same queue-health findings reported by `fireforge verify`
  * without printing. Used by doctor recovery paths that need a read-only
  * "is this queue healthy?" decision before clearing stale state.
+ *
+ * @param projectRoot - Project root directory
+ * @param scope - `verify --patches`: keep only the findings that name these
+ *   patches (see verify-scope.ts). Omitted, every finding counts.
  */
-export async function collectPatchQueueHealth(projectRoot) {
+export async function collectPatchQueueHealth(projectRoot, scope) {
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
@@ -139,7 +169,7 @@ export async function collectPatchQueueHealth(projectRoot) {
     const groups = [];
     let errorCount = 0;
     let warningCount = 0;
-    const consistencyIssues = await validatePatchesManifestConsistency(paths.patches);
+    const consistencyIssues = (await validatePatchesManifestConsistency(paths.patches)).filter((issue) => isFilenameInScope(scope, issue.filename));
     if (consistencyIssues.length > 0) {
         const issues = consistencyIssues.map((issue) => `[${issue.code}] ${issue.message}`);
         groups.push({
@@ -152,7 +182,10 @@ export async function collectPatchQueueHealth(projectRoot) {
     }
     const manifest = await loadPatchesManifest(paths.patches);
     if (manifest) {
-        const policyIssues = evaluatePatchPolicy(config, manifest);
+        const policyIssues = [
+            ...evaluatePatchPolicy(config, manifest),
+            ...(await evaluatePatchPolicyContentForQueue(config, projectRoot, paths.patches, manifest)),
+        ].filter((issue) => isFilenameInScope(scope, issue.filename));
         if (policyIssues.length > 0) {
             const policyErrors = policyIssues.filter((issue) => issue.severity === 'error').length;
             const policyWarnings = policyIssues.length - policyErrors;
@@ -173,8 +206,15 @@ export async function collectPatchQueueHealth(projectRoot) {
         // CREATES. This asks the same question of the engine, so an import ADDED
         // to an existing module is named as text instead of surfacing later as a
         // bare `xpcshell return code: -11` with zero output.
+        // Unscoped, the engine worktree joins in: an unexported chrome script
+        // importing an unexported, unregistered module crashes every objdir
+        // start before either file is in the queue. A scoped run never judges
+        // unmanaged files.
         if (await pathExists(paths.engine)) {
-            const unresolved = await findUnresolvedSystemModuleImports(paths.engine, manifest.patches.flatMap((patch) => patch.filesAffected));
+            const worktree = scope === undefined && (await isGitRepository(paths.engine))
+                ? await collectWorktreeModuleFiles(paths.engine)
+                : undefined;
+            const unresolved = await findUnresolvedSystemModuleImports(paths.engine, scopePatches(manifest.patches, scope).flatMap((patch) => patch.filesAffected), worktree);
             if (unresolved.length > 0) {
                 groups.push({
                     title: `Unresolvable system-module imports (${unresolved.length})`,
@@ -185,7 +225,7 @@ export async function collectPatchQueueHealth(projectRoot) {
                 errorCount += unresolved.length;
             }
         }
-        const crossClaims = detectCrossPatchFileClaims(manifest.patches);
+        const crossClaims = detectCrossPatchFileClaims(manifest.patches).filter((claim) => anyPatchInScope(scope, claim.filenames));
         if (crossClaims.length > 0) {
             groups.push({
                 title: `Cross-patch filesAffected conflicts (${crossClaims.length})`,
@@ -197,7 +237,7 @@ export async function collectPatchQueueHealth(projectRoot) {
         }
     }
     const ctx = await buildPatchQueueContext(paths.patches);
-    const lintIssues = lintPatchQueue(ctx);
+    const lintIssues = scopeLintIssues(lintPatchQueue(ctx), scope);
     if (lintIssues.length > 0) {
         const lintErrors = lintIssues.filter((issue) => issue.severity === 'error').length;
         const lintWarnings = lintIssues.filter((issue) => issue.severity === 'warning').length;
@@ -214,26 +254,11 @@ export async function collectPatchQueueHealth(projectRoot) {
         warningCount += lintWarnings;
     }
     if (manifest) {
-        const worktreeDrift = await detectWorktreeOwnershipDrift(projectRoot, paths.engine, paths.patches, config.binaryName);
-        if (worktreeDrift.unowned.length > 0) {
-            groups.push({
-                title: `Unowned worktree changes (${worktreeDrift.unowned.length})`,
-                issues: worktreeDrift.unowned.map((file) => `${file} is changed in engine/ but is not listed in any patch filesAffected entry`),
-                errorCount: 0,
-                warningCount: worktreeDrift.unowned.length,
-            });
-            warningCount += worktreeDrift.unowned.length;
-        }
-        if (worktreeDrift.patchOwnedDrift.length > 0) {
-            groups.push({
-                title: `Patch-owned worktree drift (${worktreeDrift.patchOwnedDrift.length})`,
-                issues: worktreeDrift.patchOwnedDrift.map((file) => `${file} is claimed by exactly one patch, but engine/ no longer matches that patch output`),
-                errorCount: 0,
-                warningCount: worktreeDrift.patchOwnedDrift.length,
-            });
-            warningCount += worktreeDrift.patchOwnedDrift.length;
-        }
-        const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches);
+        const worktreeDrift = await detectWorktreeOwnershipDrift(projectRoot, paths.engine, paths.patches, config.binaryName, scope);
+        const driftGroups = buildWorktreeDriftGroups(worktreeDrift);
+        groups.push(...driftGroups);
+        warningCount += driftGroups.reduce((sum, group) => sum + group.warningCount, 0);
+        const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches, scope);
         if (registrationIssues.length > 0) {
             groups.push({
                 title: `Dangling registration references (${registrationIssues.length})`,
@@ -256,15 +281,20 @@ export async function collectPatchQueueHealth(projectRoot) {
  * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
+ * @param options - `patches`: the raw `--patches` values
  */
-export async function verifyCommand(projectRoot) {
+export async function verifyCommand(projectRoot, options = {}) {
     intro('FireForge Verify');
+    const scope = await resolveVerifyScope(getProjectPaths(projectRoot).patches, options.patches);
+    if (scope !== undefined) {
+        info(`Judging only: ${[...scope.patches].join(', ')}`);
+    }
     // `verify` is read-only to the OPERATOR but not to git: the working-tree
     // status probe refreshes (and rewrites) `engine/.git/index`, making this
     // command a second writer of the primary checkout and invalidating a
     // concurrent `fireforge test`'s engine fingerprint. A private index keeps
     // every refresh off the primary checkout.
-    const health = await withPrivateGitIndex(getProjectPaths(projectRoot).engine, () => collectPatchQueueHealth(projectRoot));
+    const health = await withPrivateGitIndex(getProjectPaths(projectRoot).engine, () => collectPatchQueueHealth(projectRoot, scope));
     if (!health.hasPatchesDirectory) {
         info('No patches directory. Nothing to verify.');
         outro('Verify clean');
@@ -298,7 +328,8 @@ export function registerVerify(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('verify')
         .description('Read-only fsck for the patch queue (manifest + cross-patch lint)')
-        .action(withErrorHandling(async () => {
-        await verifyCommand(getProjectRoot());
+        .option('--patches <names...>', 'Judge only findings that name these patches (filename, stem, order number, manifest name, or slug; repeat or comma-separate). Queue-wide findings stay; unowned worktree changes drop out')
+        .action(withErrorHandling(async (options) => {
+        await verifyCommand(getProjectRoot(), options);
     }));
 }

package/dist/src/core/build-baseline-types.d.ts

@@ -95,8 +95,28 @@ export interface BuildBaseline {
      * replaces coverage with a dropped-path notice, or refuses when the caller
      * required --extend-coverage. Legacy packageable-only anchors cannot retain
      * coverage because they cannot prove test scripts and fixtures unchanged.
+     *
+     * Since 0.50.0 retention is decided per staged path: see
+     * {@link BuildBaseline.testCoverageRecords} and
+     * {@link BuildBaseline.fullCoverageAnchor}.
      */
     testPackagingCoverage?: TestPackagingCoverage;
+    /**
+     * Per-path anchors of a scoped claim, keyed by the request path in
+     * {@link BuildBaseline.testPackagingCoverage}. Each record holds that
+     * path's own staging inputs and their content at the build that staged
+     * it, so a later scoped build keeps the path while those inputs are
+     * unchanged, whatever moved elsewhere in the engine. A listed path without
+     * a record falls back to the baseline-wide anchor. Absent on full claims.
+     */
+    testCoverageRecords?: Record<string, CoverageRecord>;
+    /**
+     * The anchor of the last full-coverage build, carried forward by scoped
+     * builds once something outside their scope moved. A request path outside
+     * the scoped list stays covered while its own staging inputs are unchanged
+     * against this anchor. The check runs at dispatch, per requested path.
+     */
+    fullCoverageAnchor?: CoverageAnchor;
     /**
      * Hex-encoded SHA-256 of `engine/mozconfig` as it stood for this build.
      * Recorded because the mozconfig is regenerated from project-side
@@ -141,5 +161,31 @@ export interface StaticComponentsBaseline {
      */
     fingerprints: Record<string, string>;
 }
+/**
+ * Content anchor of one packaging claim. A path's staged content is
+ * `fingerprints[path]` when recorded, otherwise its content at
+ * `engineHeadSha`.
+ */
+export interface CoverageAnchor {
+    /** Engine HEAD the staged content is relative to. */
+    engineHeadSha: string;
+    /** Hex SHA-256 of `engine/mozconfig` the claim was configured with. */
+    mozconfigHash: string;
+    /**
+     * Hex SHA-256 (or {@link DELETED_FILE_FINGERPRINT}) per engine-relative
+     * path whose staged content differs from `engineHeadSha`.
+     */
+    fingerprints: Record<string, string>;
+}
+/** Anchor of one staged request path. See {@link BuildBaseline.testCoverageRecords}. */
+export interface CoverageRecord extends CoverageAnchor {
+    /**
+     * Engine-relative paths (files or directories) whose content decides what
+     * the harness stages for the request path: its manifest directory plus
+     * whatever a manifest there names outside it. `fingerprints` is
+     * restricted to these.
+     */
+    inputs: string[];
+}
 /** Coverage claim of the packaged test runtime. See {@link BuildBaseline.testPackagingCoverage}. */
 export type TestPackagingCoverage = 'full' | string[];

package/dist/src/core/build-baseline-validate.js

@@ -18,6 +18,20 @@ function isFingerprintMap(value) {
     return (isObject(value) &&
         Object.entries(value).every(([path, fingerprint]) => isBaselinePath(path) && isFingerprint(fingerprint)));
 }
+function isCoverageAnchor(value) {
+    return (isObject(value) &&
+        typeof value['engineHeadSha'] === 'string' &&
+        isFingerprint(value['mozconfigHash']) &&
+        isFingerprintMap(value['fingerprints']));
+}
+function isCoverageRecordMap(value) {
+    return (isObject(value) &&
+        Object.entries(value).every(([path, record]) => isBaselinePath(path) &&
+            isCoverageAnchor(record) &&
+            isObject(record) &&
+            Array.isArray(record['inputs']) &&
+            record['inputs'].every(isBaselinePath)));
+}
 /** Validates persisted fields without converting malformed coverage into a full claim. */
 export function isBuildBaseline(value) {
     if (!isObject(value))
@@ -45,6 +59,11 @@ export function isBuildBaseline(value) {
         return false;
     if (value['recordedBy'] !== undefined && typeof value['recordedBy'] !== 'string')
         return false;
+    if (value['testCoverageRecords'] !== undefined &&
+        !isCoverageRecordMap(value['testCoverageRecords']))
+        return false;
+    if (value['fullCoverageAnchor'] !== undefined && !isCoverageAnchor(value['fullCoverageAnchor']))
+        return false;
     const components = value['staticComponentsBaseline'];
     return (components === undefined ||
         (isObject(components) &&

package/dist/src/core/build-baseline.d.ts

@@ -15,7 +15,7 @@
  * on successful build completion. A failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
+import { type BuildBaseline, type CoverageAnchor, type CoverageRecord, type TestPackagingCoverage } from './build-baseline-types.js';
 /**
  * Which mach build produced the baseline being written. Decides whether
  * the `jar.mn` half of {@link BuildBaseline.buildInputFingerprints} is
@@ -52,6 +52,10 @@ export interface WriteBuildBaselineOptions {
      * Omitted → field left off the marker.
      */
     testPackagingCoverage?: TestPackagingCoverage | undefined;
+    /** Per-path anchors of a scoped claim. Omitted → field left off the marker. */
+    testCoverageRecords?: Record<string, CoverageRecord> | undefined;
+    /** Carried full-build anchor of a narrowed claim. Omitted → field left off. */
+    fullCoverageAnchor?: CoverageAnchor | undefined;
     /**
      * The baseline this write replaces, when the caller has it. A scoped
      * (non-`'full'`) write carries its `staticComponentsBaseline` forward