@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/status-check.js

@@ -1,5 +1,5 @@
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-const ALL_CLASSIFICATIONS = [
+const ALL_CHECK_CLASSES = [
     'patch-backed',
     'patch-owned-drift',
     'unmanaged',
@@ -7,12 +7,15 @@ const ALL_CLASSIFICATIONS = [
     'furnace',
     'conflict',
     'binary-unsupported',
+    'ownership-conflict',
 ];
 /**
  * Default `--check` policy: everything outside {patch-backed, branding,
  * furnace, binary-unsupported} fails. `binary-unsupported` is excluded so
  * an honest "cannot compare" does not keep the gate permanently red.
  * Strict CI can opt in via `--fail-on binary-unsupported`.
+ * `ownership-conflict` is opt-in too: the human `--ownership` mode already
+ * fails on it, and adding it here would change the default gate.
  */
 const DEFAULT_FAIL_CLASSIFICATIONS = [
     'unmanaged',
@@ -20,13 +23,19 @@ const DEFAULT_FAIL_CLASSIFICATIONS = [
     'conflict',
 ];
 /**
- * Resolves the enforcement policy from the raw flags: `--fail-on` implies
- * `--check` and replaces the default set. Both are refused alongside the
- * modes that skip (or elide) classification.
+ * Resolves the enforcement policy from the raw flags. `--fail-on`,
+ * `--allow` and `--fail-on-unknown` each imply `--check`. `--fail-on`
+ * replaces the default set and `--allow` subtracts from it (naming one
+ * class in both is refused). `--fail-on-unknown` needs `--allow`: without
+ * an allow list every class the caller did not name, `patch-backed`
+ * included, would fail. All of them are refused alongside the modes that
+ * skip (or elide) classification.
  */
 export function resolveStatusCheckPolicy(options) {
-    const failOnList = parseFailOnClassifications(options.failOn);
-    const checkEnabled = options.check === true || failOnList !== undefined;
+    const failOnList = parseCheckClassList(options.failOn, '--fail-on');
+    const allowList = parseCheckClassList(options.allow, '--allow');
+    const failOnUnknown = options.failOnUnknown === true;
+    const checkEnabled = options.check === true || failOnList !== undefined || allowList !== undefined || failOnUnknown;
     if (checkEnabled &&
         (options.raw === true ||
             options.unmanaged === true ||
@@ -34,17 +43,32 @@ export function resolveStatusCheckPolicy(options) {
             options.testCoverage === true)) {
         throw new InvalidArgumentError('--check cannot be combined with --raw, --unmanaged, --ownership, or --test-coverage. Use the default view or --json.', '--check');
     }
-    return { checkEnabled, failOn: failOnList ?? DEFAULT_FAIL_CLASSIFICATIONS };
+    if (failOnUnknown && allowList === undefined) {
+        throw new InvalidArgumentError('--fail-on-unknown requires --allow naming the classes that may pass. Without it every class you did not name, patch-backed included, would fail.', '--fail-on-unknown');
+    }
+    const overlap = (failOnList ?? []).filter((entry) => allowList?.includes(entry) === true);
+    if (overlap.length > 0) {
+        throw new InvalidArgumentError(`--fail-on and --allow both name ${overlap.join(', ')}. A class either fails or is allowed.`, '--allow');
+    }
+    const base = failOnList ?? DEFAULT_FAIL_CLASSIFICATIONS;
+    const policy = {
+        checkEnabled,
+        failOn: allowList ? base.filter((entry) => !allowList.includes(entry)) : base,
+    };
+    if (allowList !== undefined)
+        policy.allow = allowList;
+    if (failOnUnknown)
+        policy.failOnUnknown = true;
+    return policy;
 }
-function isClassification(value) {
-    return ALL_CLASSIFICATIONS.includes(value);
+function isCheckClass(value) {
+    return ALL_CHECK_CLASSES.includes(value);
 }
 /**
- * Parses a comma-separated `--fail-on` value into a classification list.
- * Returns undefined when the flag was not given (the caller then applies
- * the default policy only under `--check`).
+ * Parses a comma-separated `--fail-on`/`--allow` value into a class list.
+ * Returns undefined when the flag was not given.
  */
-function parseFailOnClassifications(raw) {
+function parseCheckClassList(raw, flag) {
     if (raw === undefined)
         return undefined;
     const parts = raw
@@ -52,52 +76,83 @@ function parseFailOnClassifications(raw) {
         .map((part) => part.trim())
         .filter((part) => part.length > 0);
     if (parts.length === 0) {
-        throw new InvalidArgumentError(`--fail-on requires at least one classification. Valid: ${ALL_CLASSIFICATIONS.join(', ')}.`, '--fail-on');
+        throw new InvalidArgumentError(`${flag} requires at least one classification. Valid: ${ALL_CHECK_CLASSES.join(', ')}.`, flag);
     }
-    const classifications = [];
+    const classes = [];
     for (const part of parts) {
-        if (!isClassification(part)) {
-            throw new InvalidArgumentError(`Unknown --fail-on classification "${part}". Valid: ${ALL_CLASSIFICATIONS.join(', ')}.`, '--fail-on');
+        if (!isCheckClass(part)) {
+            throw new InvalidArgumentError(`Unknown ${flag} classification "${part}". Valid: ${ALL_CHECK_CLASSES.join(', ')}.`, flag);
         }
-        if (!classifications.includes(part))
-            classifications.push(part);
+        if (!classes.includes(part))
+            classes.push(part);
     }
-    return classifications;
+    return classes;
+}
+/**
+ * True when the policy can fail on `ownership-conflict`, so the caller has
+ * to build the ownership rows even without `--include-ownership`.
+ */
+export function policyNeedsOwnership(policy) {
+    if (!policy.checkEnabled)
+        return false;
+    if (policy.failOn.includes('ownership-conflict'))
+        return true;
+    return policy.failOnUnknown === true && policy.allow?.includes('ownership-conflict') !== true;
 }
 const CHECK_FILE_PREVIEW_MAX = 3;
 /**
- * Collects the fail-set classifications that have offending files, in
- * policy order with full file lists. Shared by the human `--check`
- * verdict and the `--json --summary` payload so the two views can never
- * disagree about what failed.
+ * Collects the failing classes that have offending files, with full file
+ * lists: the fail set in policy order, then (under `--fail-on-unknown`)
+ * every other present class neither list names, in first-seen order.
+ * Shared by the human `--check` verdict and the JSON `check` block so the
+ * two views can never disagree about what failed.
+ *
+ * @param classified - Classified worktree entries
+ * @param policy - Resolved policy
+ * @param ownershipConflicts - Paths claimed by more than one patch. Only
+ *   read for the `ownership-conflict` class
  */
-export function collectStatusCheckOffenders(classified, policy) {
+export function collectStatusCheckOffenders(classified, policy, ownershipConflicts = []) {
+    const filesOf = (checkClass) => checkClass === 'ownership-conflict'
+        ? [...ownershipConflicts]
+        : classified.filter((entry) => entry.classification === checkClass).map((e) => e.file);
     const offenders = [];
-    for (const classification of policy.failOn) {
-        const files = classified
-            .filter((entry) => entry.classification === classification)
-            .map((entry) => entry.file);
+    for (const checkClass of policy.failOn) {
+        const files = filesOf(checkClass);
         if (files.length === 0)
             continue;
-        offenders.push({ classification, count: files.length, files });
+        offenders.push({ classification: checkClass, count: files.length, files });
+    }
+    if (policy.failOnUnknown !== true)
+        return offenders;
+    const named = new Set([...policy.failOn, ...(policy.allow ?? [])]);
+    const present = [...new Set(classified.map((e) => e.classification))];
+    if (ownershipConflicts.length > 0)
+        present.push('ownership-conflict');
+    for (const checkClass of present) {
+        if (named.has(checkClass))
+            continue;
+        const files = filesOf(checkClass);
+        offenders.push({ classification: checkClass, count: files.length, files, unnamed: true });
     }
     return offenders;
 }
 /**
- * Throws a GeneralError (exit 1) when the policy is enabled and any of
- * its classifications is non-empty, naming each offending classification
- * with its first few files. A disabled policy or a fully tool-covered
- * tree passes silently.
+ * Throws a GeneralError (exit 1) when the policy is enabled and any
+ * failing class is non-empty, naming each offending class with its first
+ * few files. A disabled policy or a fully tool-covered tree passes
+ * silently.
  */
-export function runStatusCheck(classified, policy) {
+export function runStatusCheck(classified, policy, ownershipConflicts = []) {
     if (!policy.checkEnabled)
         return;
-    const offending = collectStatusCheckOffenders(classified, policy).map((offender) => {
+    const offending = collectStatusCheckOffenders(classified, policy, ownershipConflicts).map((offender) => {
         const preview = offender.files.slice(0, CHECK_FILE_PREVIEW_MAX).join(', ');
         const more = offender.count > CHECK_FILE_PREVIEW_MAX
             ? `, +${offender.count - CHECK_FILE_PREVIEW_MAX} more`
             : '';
-        return `${offender.count} ${offender.classification} (${preview}${more})`;
+        const unnamed = offender.unnamed === true ? ' [named by neither --fail-on nor --allow]' : '';
+        return `${offender.count} ${offender.classification}${unnamed} (${preview}${more})`;
     });
     if (offending.length === 0)
         return;

package/dist/src/commands/status-json.d.ts

@@ -9,24 +9,37 @@
  *   `files[]` entirely, because engine-clean gates need the verdict,
  *   per-class counts, and offender names, not a payload that grows with
  *   the queue (175 KB+ on a large one).
+ *
+ * Both carry the `check` block when the `--check` policy is active, and the
+ * `scope` block under `--patches`.
  */
 import type { ClassifiedFile } from '../core/status-classify.js';
 import { type StatusCheckPolicy } from './status-check.js';
 import type { OwnershipJsonBlock } from './status-ownership.js';
+import type { StatusScope } from './status-scope.js';
+/** What a JSON payload adds beside the classification counts. */
+export interface StatusJsonContext {
+    policy: StatusCheckPolicy;
+    /** Paths claimed by more than one patch, for the `ownership-conflict` class. */
+    ownershipConflicts: readonly string[];
+    /** The `--include-ownership` block, when asked for. */
+    ownership?: OwnershipJsonBlock | undefined;
+    /** The `--patches` scope, when given. */
+    scope?: StatusScope | undefined;
+}
 /**
- * Full `--json` payload: summary plus the per-file `files[]` list, and,
- * under `--include-ownership`, the additive `ownership` block.
- * Additive within schemaVersion 1: a consumer that does not ask for the
+ * Full `--json` payload: summary plus the per-file `files[]` list, and the
+ * additive `check`, `scope` and `ownership` blocks when their flags are
+ * set. Additive within schemaVersion 1: a consumer that does not ask for a
  * block never sees the key.
  */
-export declare function renderJsonStatus(classified: readonly ClassifiedFile[], ownership?: OwnershipJsonBlock): void;
+export declare function renderJsonStatus(classified: readonly ClassifiedFile[], context: StatusJsonContext): void;
 /**
  * Summary-only `--json --summary` payload. Counts are always present. When
  * the `--check`/`--fail-on` policy is active, the payload adds a `check`
  * block with the active fail set, the verdict, and the offending files per
- * fail-set classification (sourced from the same collector as the human
- * `--check` message, so the two views can never disagree). The absent
- * `files[]` is the mode signal within schemaVersion 1. Consumers opt in via
- * the flag.
+ * failing class (sourced from the same collector as the human `--check`
+ * message, so the two views can never disagree). The absent `files[]` is
+ * the mode signal within schemaVersion 1. Consumers opt in via the flag.
  */
-export declare function renderJsonSummaryStatus(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy, ownership?: OwnershipJsonBlock): void;
+export declare function renderJsonSummaryStatus(classified: readonly ClassifiedFile[], context: StatusJsonContext): void;

package/dist/src/commands/status-json.js

@@ -16,12 +16,45 @@ function countByClassification(classified) {
     return byClassification;
 }
 /**
- * Full `--json` payload: summary plus the per-file `files[]` list, and,
- * under `--include-ownership`, the additive `ownership` block.
- * Additive within schemaVersion 1: a consumer that does not ask for the
+ * Builds the `check` block, or undefined when no policy is active.
+ * `allow` and `failOnUnknown` appear only when the caller set them, so a
+ * consumer that never passes those flags sees the block it always did.
+ */
+function buildCheckBlock(classified, context) {
+    const { policy } = context;
+    if (!policy.checkEnabled)
+        return undefined;
+    const offenders = collectStatusCheckOffenders(classified, policy, context.ownershipConflicts);
+    return {
+        enabled: true,
+        failOn: policy.failOn,
+        ...(policy.allow !== undefined ? { allow: policy.allow } : {}),
+        ...(policy.failOnUnknown === true ? { failOnUnknown: true } : {}),
+        failed: offenders.length > 0,
+        offenders,
+    };
+}
+/** The additive tail both payloads share: check, scope, ownership. */
+function buildTrailingBlocks(classified, context) {
+    const check = buildCheckBlock(classified, context);
+    return {
+        ...(check !== undefined ? { check } : {}),
+        ...(context.scope !== undefined ? { scope: context.scope } : {}),
+        ...(context.ownership !== undefined ? { ownership: context.ownership } : {}),
+    };
+}
+function writePayload(output) {
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    // Payload written: stdout is now spoken for. See docs/machine-output.md.
+    setStdoutSealed(true);
+}
+/**
+ * Full `--json` payload: summary plus the per-file `files[]` list, and the
+ * additive `check`, `scope` and `ownership` blocks when their flags are
+ * set. Additive within schemaVersion 1: a consumer that does not ask for a
  * block never sees the key.
  */
-export function renderJsonStatus(classified, ownership) {
+export function renderJsonStatus(classified, context) {
     const outputFiles = classified.map((f) => {
         const entry = {
             file: f.file,
@@ -34,49 +67,31 @@ export function renderJsonStatus(classified, ownership) {
         }
         return entry;
     });
-    const output = {
+    writePayload({
         schemaVersion: 1,
         summary: {
             total: outputFiles.length,
             byClassification: countByClassification(classified),
         },
         files: outputFiles,
-        ...(ownership !== undefined ? { ownership } : {}),
-    };
-    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
-    // Payload written: stdout is now spoken for. See docs/machine-output.md.
-    setStdoutSealed(true);
+        ...buildTrailingBlocks(classified, context),
+    });
 }
 /**
  * Summary-only `--json --summary` payload. Counts are always present. When
  * the `--check`/`--fail-on` policy is active, the payload adds a `check`
  * block with the active fail set, the verdict, and the offending files per
- * fail-set classification (sourced from the same collector as the human
- * `--check` message, so the two views can never disagree). The absent
- * `files[]` is the mode signal within schemaVersion 1. Consumers opt in via
- * the flag.
+ * failing class (sourced from the same collector as the human `--check`
+ * message, so the two views can never disagree). The absent `files[]` is
+ * the mode signal within schemaVersion 1. Consumers opt in via the flag.
  */
-export function renderJsonSummaryStatus(classified, policy, ownership) {
-    const output = {
+export function renderJsonSummaryStatus(classified, context) {
+    writePayload({
         schemaVersion: 1,
         summary: {
             total: classified.length,
             byClassification: countByClassification(classified),
         },
-    };
-    if (policy.checkEnabled) {
-        const offenders = collectStatusCheckOffenders(classified, policy);
-        output.check = {
-            enabled: true,
-            failOn: policy.failOn,
-            failed: offenders.length > 0,
-            offenders,
-        };
-    }
-    if (ownership !== undefined) {
-        output.ownership = ownership;
-    }
-    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
-    // Payload written: stdout is now spoken for. See docs/machine-output.md.
-    setStdoutSealed(true);
+        ...buildTrailingBlocks(classified, context),
+    });
 }

package/dist/src/commands/status-output.js

@@ -220,6 +220,8 @@ export function renderTestCoverageStatus(baseline) {
     }
     const list = coverage.map((path) => `  - ${path}`).join('\n');
     info(`Test packaging coverage: scoped to ${coverage.length} path(s):\n${list}\n` +
-        'A "fireforge test" over paths outside this list will be refused as uncovered.');
+        (baseline.fullCoverageAnchor === undefined
+            ? 'A "fireforge test" over paths outside this list will be refused as uncovered.'
+            : 'A "fireforge test" over paths outside this list stays covered by the earlier full build while their own staging inputs are unchanged, and is refused otherwise.'));
     outro(`Coverage: scoped (${coverage.length} paths)`);
 }

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

@@ -0,0 +1,37 @@
+/**
+ * `status --patches <list>`: judges only the named patches' files. Split
+ * out of status.ts, which sits at the max-lines budget.
+ *
+ * On a shared engine a peer's unexported work keeps a tree-wide gate red
+ * for everyone. The scope keeps a file when the patch that owns it (or,
+ * for a conflict, any patch that claims it) is named, and an ownership
+ * row when any of its owners is named. An unmanaged file has no owning
+ * patch, so no scope covers it: scoped runs never judge unexported files.
+ * That is the point of the scope, and also its limit, which the docs say.
+ */
+import type { OwnershipRow } from '../core/ownership-table.js';
+import type { ClassifiedFile, StatusFile } from '../core/status-classify.js';
+/** The resolved `--patches` scope: manifest filenames, in request order. */
+export interface StatusScope {
+    patches: string[];
+}
+/**
+ * Resolves raw `--patches` values against the manifest. Returns undefined
+ * when the flag was not given, and refuses a name that matches no patch
+ * (so a typo fails loud instead of judging nothing).
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ */
+export declare function resolveStatusScope(patchesDir: string, requested: readonly string[] | undefined): Promise<StatusScope | undefined>;
+/** Keeps only the classified entries the scope covers. No scope keeps all. */
+export declare function scopeClassified(classified: ClassifiedFile[], scope: StatusScope | undefined): ClassifiedFile[];
+/** Keeps only the ownership rows with an owner in scope. No scope keeps all. */
+export declare function scopeOwnershipRows(rows: OwnershipRow[], scope: StatusScope | undefined): OwnershipRow[];
+/**
+ * Builds the ownership rows from the full scan (classification needs every
+ * file to find claims), then narrows them to the scope.
+ */
+export declare function collectScopedOwnershipRows(patchesDir: string, files: StatusFile[], classified: readonly ClassifiedFile[], scope: StatusScope | undefined): Promise<OwnershipRow[]>;
+/** The paths the `ownership-conflict` check class judges. */
+export declare function ownershipConflictPaths(rows: readonly OwnershipRow[]): string[];

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

@@ -0,0 +1,54 @@
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { selectPatchSubset } from '../core/patch-subset.js';
+import { GeneralError } from '../errors/base.js';
+import { collectOwnershipRows } from './status-ownership.js';
+/**
+ * Resolves raw `--patches` values against the manifest. Returns undefined
+ * when the flag was not given, and refuses a name that matches no patch
+ * (so a typo fails loud instead of judging nothing).
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ */
+export async function resolveStatusScope(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), not engine files.');
+    return { patches: subset.map((patch) => patch.filename) };
+}
+/** True when the entry's owner, or any patch claiming it, is in scope. */
+function isInScope(entry, names) {
+    if (entry.owner !== undefined && names.has(entry.owner))
+        return true;
+    return entry.claimedBy?.some((patch) => names.has(patch)) === true;
+}
+/** Keeps only the classified entries the scope covers. No scope keeps all. */
+export function scopeClassified(classified, scope) {
+    if (scope === undefined)
+        return classified;
+    const names = new Set(scope.patches);
+    return classified.filter((entry) => isInScope(entry, names));
+}
+/** Keeps only the ownership rows with an owner in scope. No scope keeps all. */
+export function scopeOwnershipRows(rows, scope) {
+    if (scope === undefined)
+        return rows;
+    const names = new Set(scope.patches);
+    return rows.filter((row) => row.owners.some((owner) => names.has(owner)));
+}
+/**
+ * Builds the ownership rows from the full scan (classification needs every
+ * file to find claims), then narrows them to the scope.
+ */
+export async function collectScopedOwnershipRows(patchesDir, files, classified, scope) {
+    const rows = await collectOwnershipRows(patchesDir, (await loadPatchesManifest(patchesDir))?.patches ?? [], files, classified);
+    return scopeOwnershipRows(rows, scope);
+}
+/** The paths the `ownership-conflict` check class judges. */
+export function ownershipConflictPaths(rows) {
+    return rows.filter((row) => row.conflict).map((row) => row.path);
+}

package/dist/src/commands/status.js

@@ -8,17 +8,17 @@ import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { listUntrackedFilesInDirs, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
 import { renderOwnershipTable } from '../core/ownership-table.js';
-import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { readProcessCpuSeconds } from '../core/process-cpu-time.js';
 import { classifyFiles } from '../core/status-classify.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
 import { emitMachineError } from '../utils/machine-output.js';
-import { resolveStatusCheckPolicy, runStatusCheck, } from './status-check.js';
+import { policyNeedsOwnership, resolveStatusCheckPolicy, runStatusCheck, } from './status-check.js';
 import { renderJsonStatus, renderJsonSummaryStatus } from './status-json.js';
 import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
-import { buildOwnershipJsonBlock, collectOwnershipRows, summarizeOwnership, } from './status-ownership.js';
+import { buildOwnershipJsonBlock, summarizeOwnership } from './status-ownership.js';
+import { collectScopedOwnershipRows, ownershipConflictPaths, resolveStatusScope, scopeClassified, } from './status-scope.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
  * Each line is: STATUS<tab>FILE
@@ -121,26 +121,47 @@ async function scanEngineStatusFiles(engineDir, requireGitRepository) {
  * policy, which stays the only exit driver on this path.
  *
  * `--include-ownership` is a modifier rather than a mode: it appends an
- * ownership block without touching exit semantics, so an ownership
- * conflict still fails only the human `--ownership` mode.
+ * ownership block without touching exit semantics. Ownership conflicts
+ * fail this path only when the policy names `ownership-conflict` (or
+ * leaves it unnamed under `--fail-on-unknown`).
  *
- * @param classified - Classified worktree entries
+ * @param classified - Classified worktree entries, unscoped
  * @param files - The same entries pre-classification, for ownership rows
  * @param paths - Resolved project paths
  * @param options - Status display options
  * @param checkPolicy - Resolved `--check`/`--fail-on` policy
+ * @param scope - The `--patches` scope, when given
  */
-async function renderJsonMode(classified, files, paths, options, checkPolicy) {
-    const ownership = options.includeOwnership === true
-        ? buildOwnershipJsonBlock(await collectOwnershipRows(paths.patches, (await loadPatchesManifest(paths.patches))?.patches ?? [], files, classified))
-        : undefined;
+async function renderJsonMode(classified, files, paths, options, checkPolicy, scope) {
+    const rows = options.includeOwnership === true || policyNeedsOwnership(checkPolicy)
+        ? await collectScopedOwnershipRows(paths.patches, files, classified, scope)
+        : [];
+    const context = {
+        policy: checkPolicy,
+        ownershipConflicts: ownershipConflictPaths(rows),
+        ownership: options.includeOwnership === true ? buildOwnershipJsonBlock(rows) : undefined,
+        scope,
+    };
+    const scoped = scopeClassified(classified, scope);
     if (options.summary === true) {
-        renderJsonSummaryStatus(classified, checkPolicy, ownership);
+        renderJsonSummaryStatus(scoped, context);
     }
     else {
-        renderJsonStatus(classified, ownership);
+        renderJsonStatus(scoped, context);
     }
-    runStatusCheck(classified, checkPolicy);
+    runStatusCheck(scoped, checkPolicy, context.ownershipConflicts);
+}
+/**
+ * Applies the `--check` policy to the human default view. Builds the
+ * ownership rows only when the policy can fail on `ownership-conflict`,
+ * which it can on a clean tree too (two patches claiming one path need no
+ * worktree change).
+ */
+async function runHumanStatusCheck(classified, files, paths, checkPolicy, scope) {
+    const conflicts = policyNeedsOwnership(checkPolicy)
+        ? ownershipConflictPaths(await collectScopedOwnershipRows(paths.patches, files, classified, scope))
+        : [];
+    runStatusCheck(scopeClassified(classified, scope), checkPolicy, conflicts);
 }
 /**
  * Detects the "unborn HEAD" aftermath of an interrupted `fireforge download`:
@@ -200,8 +221,12 @@ export async function statusCommand(projectRoot, options = {}) {
         setMachineOutputMode(previousMachineOutputMode);
     }
 }
-/** The status body proper. The machine-mode lifecycle lives in {@link statusCommand}. */
-async function runStatusCommandBody(projectRoot, options) {
+/**
+ * Refuses flag combinations no view can honour, before any output: one
+ * mode at most, and the JSON-only and scope modifiers only where they mean
+ * something.
+ */
+function assertStatusFlagCombination(options) {
     const modeCount = [
         options.raw,
         options.unmanaged,
@@ -224,6 +249,18 @@ async function runStatusCommandBody(projectRoot, options) {
     if (options.includeOwnership === true && options.json !== true) {
         throw new InvalidArgumentError('--include-ownership requires --json. Use --ownership for the human table.', '--include-ownership');
     }
+    // --patches scopes the classifying views and the ownership table only.
+    if (options.patches !== undefined &&
+        (options.raw === true ||
+            options.unmanaged === true ||
+            options.testCoverage === true ||
+            options.lock === true)) {
+        throw new InvalidArgumentError('--patches cannot be combined with --raw, --unmanaged, --test-coverage, or --lock.', '--patches');
+    }
+}
+/** The status body proper. The machine-mode lifecycle lives in {@link statusCommand}. */
+async function runStatusCommandBody(projectRoot, options) {
+    assertStatusFlagCombination(options);
     // --check / --fail-on enforcement policy. Applies only
     // where classification runs (the default view and --json).
     const checkPolicy = resolveStatusCheckPolicy(options);
@@ -253,6 +290,7 @@ async function runStatusCommandBody(projectRoot, options) {
     }
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
+    const scope = await resolveStatusScope(paths.patches, options.patches);
     // Shared envelope: see src/utils/machine-output.ts and
     // docs/machine-output.md. `status` was the only command that had one.
     // Ownership mode is a flat file→patch table. Sources are the manifest's
@@ -265,13 +303,12 @@ async function runStatusCommandBody(projectRoot, options) {
         // Rung 1 only. See the note below on why this branch does not take the
         // full assertEngineGitReady ladder.
         await assertEngineExists(paths.engine);
-        const manifest = await loadPatchesManifest(paths.patches);
         // The same scan and the same classification pass as every other mode.
         // This branch keeps its historical guard shape on purpose:
         // no baseline-commit assertion, and a non-git engine degrades to an
         // empty table rather than the recovery banner.
         const rawFilesOwnership = await scanEngineStatusFiles(paths.engine, false);
-        const rows = await collectOwnershipRows(paths.patches, manifest?.patches ?? [], rawFilesOwnership, await classifyStatusFiles(rawFilesOwnership, paths, projectRoot, config.binaryName));
+        const rows = await collectScopedOwnershipRows(paths.patches, rawFilesOwnership, await classifyStatusFiles(rawFilesOwnership, paths, projectRoot, config.binaryName), scope);
         renderOwnershipTable(rows);
         const { managed, unmanaged, conflicts } = summarizeOwnership(rows);
         const parts = [`${managed} managed`];
@@ -313,7 +350,7 @@ async function runStatusCommandBody(projectRoot, options) {
     // `[]` here and return before the human fallback.
     if (options.json) {
         const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
-        await renderJsonMode(classified, files, paths, options, checkPolicy);
+        await renderJsonMode(classified, files, paths, options, checkPolicy, scope);
         return;
     }
     // `--raw` consumers parse the native `git status --porcelain` output
@@ -326,6 +363,7 @@ async function runStatusCommandBody(projectRoot, options) {
     if (files.length === 0) {
         info('No modified files');
         outro('Working tree clean');
+        await runHumanStatusCheck([], files, paths, checkPolicy, scope);
         return;
     }
     // Raw mode: existing behavior
@@ -333,8 +371,10 @@ async function runStatusCommandBody(projectRoot, options) {
         renderRawStatus(files);
         return;
     }
-    // Patch-aware classification
-    const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
+    // Patch-aware classification. The full scan is classified (claims need
+    // every file) and the buckets show only what the scope covers.
+    const allClassified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
+    const classified = scopeClassified(allClassified, scope);
     const buckets = {
         conflict: classified.filter((f) => f.classification === 'conflict'),
         unmanaged: classified.filter((f) => f.classification === 'unmanaged'),
@@ -349,8 +389,8 @@ async function runStatusCommandBody(projectRoot, options) {
         await renderUnmanagedOnly(buckets.unmanaged, files.length, projectRoot, config.binaryName);
         return;
     }
-    await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
-    runStatusCheck(classified, checkPolicy);
+    await renderDefaultStatus(scope ? classified.length : files.length, buckets, projectRoot, config.binaryName);
+    await runHumanStatusCheck(allClassified, files, paths, checkPolicy, scope);
 }
 /** Registers the status command on the CLI program. */
 export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
@@ -366,7 +406,10 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--summary', 'With --json: emit only summary counts (plus offending files when --check/--fail-on is active), omitting the per-file files[] payload')
         .option('--include-ownership', 'With --json (composes with --summary): append an ownership block (path->owning-patch rows plus managed/unmanaged/conflict counts) to the payload, so one scan serves the classification, ownership, and check views. Does not change exit semantics.')
         .option('--check', 'Exit non-zero when any unmanaged, patch-owned-drift, or conflict file exists (composes with --json; combine with --fail-on for finer policy)')
-        .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict, binary-unsupported')
+        .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict, binary-unsupported, ownership-conflict (a path claimed by more than one patch)')
+        .option('--allow <classifications>', 'Comma-separated classification list that never fails --check, removed from the fail set (implies --check; same values as --fail-on)')
+        .option('--fail-on-unknown', 'With --allow: also fail on every present classification that neither --fail-on nor --allow names, so a classification added in a later FireForge fails closed (implies --check)')
+        .option('--patches <names...>', 'Judge only the named patches: keeps the files each owns or claims and the ownership rows naming it (filename, stem, order number, manifest name, or slug; repeat or comma-separate). Unmanaged files belong to no patch and drop out. Default view, --json and --ownership only')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));