phasegate 0.141.0 → 0.142.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.142.0] - 2026-05-10
+
+### Added
+
+- **WI-126 — work item status derivation** — `work-items:status --dry-run|--apply` を追加し、WI frontmatter `status` を inception / product reflection / implementation / test evidence から導出できるようにした。
+  - `--id WI-XXX` で単一 WI に絞り込み、`--fail-on-stale` で stale status を exit code 1 として検出できる。
+  - `--apply` は stale な `description.md` の YAML frontmatter `status:` 行だけを書き戻す。
+  - `fix` / `chore` の shortcut path は README / README.ja の説明と一致する。
+
+### Fixed
+
+- publish 前回帰として、標準 L2 validator set に `L2-013` を含む現行契約と `preCommit.implementationExtensions` default をテスト期待値に反映した。
+
 ## [0.141.0] - 2026-05-09
 
 ### Fixed

package/README.ja.md

@@ -293,6 +293,7 @@ npx phasegate <command> [options]
 | `baseline` | retrofit grandfather snapshot 生成（`--dry-run`, `--force`, `--paths <glob>`, `--json`） |
 | `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | 最小構成の設計文書を `templates/` から生成 |
 | `phasegate:status` | 全体の健全性サマリ |
+| `work-items:status --dry-run` / `--apply` | 成果物から WI status を導出し、必要に応じて `description.md` frontmatter を更新 |
 | `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
 | `phasegate:detect-drift` | 設計-コード乖離レポート |
 | `migrate work-items --dry-run` / `--apply` | 既存リポジトリの旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を WI 統一レイアウト（`_cross/{WI-XXX}/` / `{unit}/{WI-XXX}/`）へ移行。frontmatter（`type` / `severity` / `legacy_id` / `affects`）を自動注入。冪等。`--json` で CI/スクリプト連携可。詳細: [Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
@@ -406,6 +407,8 @@ TESTED (@work-item-id 付きテストあり / green)
 
 `type: chore` は DRAFTED で完結。`type: fix` は DRAFTED → REFLECTED → IMPLEMENTED の簡略パス。`status` は PhaseGate が自動更新します。
 
+`phasegate work-items:status --dry-run` で current status / derived status / reason / next action を確認できます。単一 WI に絞る場合は `--id WI-XXX`、CI 風に stale status を検出する場合は `--fail-on-stale`、`description.md` frontmatter の `status:` 行だけを書き戻す場合は `--apply` を指定します。
+
 詳細仕様: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
 
 ---
@@ -456,9 +459,9 @@ reports/
 
 | Work Item | 内容 |
 |---|---|
-| **[WI-033](docs/inception/_cross/WI-033/description.md)** | L4 運用ロールアウトの仕上げ。`doc-freshness` / `pointer-validation` は L4-004 / L4-005 として登録済みで、`p2:*` 互換コマンドも維持。残りは scheduling / default / 運用 docs の整理。@work-item-id WI-116 |
+| **[WI-128](docs/inception/_cross/WI-128/description.md)** | L4 運用ロールアウトの仕上げ。`doc-freshness` / `pointer-validation` は L4-004 / L4-005 として登録済みで、`p2:*` 互換コマンドも維持。WI-033 は完了済みとして閉じ、残りの scheduling / default / 運用 docs は後続 WI で扱う。@work-item-id WI-128 |
 
-L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。現時点では手動セットアップで利用できます。
+L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。[WI-125](docs/inception/_cross/WI-125/description.md) と L3 guide を参照してください。現時点では手動セットアップで利用できます。
 
 ---
 

package/README.md

@@ -247,6 +247,8 @@ TESTED  (test files annotated with @work-item-id, all green)
 
 `type: chore` ends at DRAFTED. `type: fix` shortcuts via DRAFTED → REFLECTED → IMPLEMENTED. PhaseGate auto-updates `status`.
 
+Use `phasegate work-items:status --dry-run` to inspect current status, derived status, reason, and next action. Add `--id WI-XXX` to scope the report, `--fail-on-stale` for CI-style stale status detection, or `--apply` to update only the `status:` line in each stale `description.md` frontmatter.
+
 Full spec: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
 
 ---
@@ -474,6 +476,7 @@ npx phasegate <command> [options]
 | `p2:check-agent-context` | Check AGENTS.md / CLAUDE.md freshness |
 | `update-skills` | Update skills to latest version |
 | `phasegate:status` | Display overall harness health summary |
+| `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
 | `check-change-category --paths <csv>` | Classify changed files into Quick Mode categories and report whether Full Mode is required (`--format json`, `--fail-on-full-required`) |
 | `baseline` | Create `.phasegate/baseline.json` snapshot for Phase A-2 retrofit grandfather (`--dry-run`, `--force`, `--paths <glob,glob,...>`, `--json`). `baseline.enabled` defaults to `true` since v0.71.0. |
@@ -517,9 +520,9 @@ The main path is ready for project use, but a few documented behaviors still req
 
 | Work Item | Title | Why it matters |
 |---|---|---|
-| **[WI-033](docs/inception/_cross/WI-033/description.md)** | Finish L4 operational rollout | `doc-freshness` and `pointer-validation` are registered as L4-004/L4-005 and also remain available through `p2:*` compatibility commands. Remaining WI-033 work is rollout polish around scheduling, defaults, and operational docs. @work-item-id WI-116 |
+| **[WI-128](docs/inception/_cross/WI-128/description.md)** | Finish L4 operational rollout | `doc-freshness` and `pointer-validation` are registered as L4-004/L4-005 and also remain available through `p2:*` compatibility commands. WI-033 is closed; remaining rollout polish around scheduling, defaults, and operational docs is tracked separately. @work-item-id WI-128 |
 
-`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see the L3 guide for the current manual setup.
+`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see [WI-125](docs/inception/_cross/WI-125/description.md) and the L3 guide for the current manual setup.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.141.0",
+  "version": "0.142.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/harness-api/domain/services/command-dispatch-service.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // command-dispatch-service.ts — CommandDispatchService Domain Service
 
 import { CommandRegistry } from './command-registry.js';

package/scripts/harness/harness-api/domain/services/status-derivation-service.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // status-derivation-service.ts — StatusDerivationService Domain Service
 
 import { LayerHealth, type LayerId } from '../value-objects/layer-health.js';

package/scripts/harness/harness-api/domain/value-objects/ci-check-result.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // ci-check-result.ts — CiCheckResult Value Object
 
 import type { HarnessError } from './harness-api-response.js';

package/scripts/harness/harness-api/domain/value-objects/drift-report-summary.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // drift-report-summary.ts — DriftReportSummary Value Object
 
 export interface DriftItem {

package/scripts/harness/harness-api/domain/value-objects/layer-health.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // layer-health.ts — LayerHealth Value Object
 
 export type LayerId = 'L1' | 'L2' | 'L3' | 'L4';

package/scripts/harness/main.ts

@@ -98,6 +98,7 @@ Commands:
   disable-feature <name>       Disable a harness feature
   list-features                List available features
   migrate                      Migrate phasegate.config.json (--schema v3, --config <path>)
+  work-items:status            Report or apply derived WI frontmatter status (--dry-run|--apply, --id, --fail-on-stale, --json)
 
   render-errors                Render harness errors (--format human|agent|ci)
   validate-fix                 Validate fix examples (--code <code>)
@@ -306,6 +307,17 @@ Options:
   "phasegate:status": `Usage: phasegate phasegate:status
 
 Display harness status (enabled validators, schema version, hook deployment).`,
+  "work-items:status": `Usage: phasegate work-items:status (--dry-run|--apply) [options]
+
+Derive WI frontmatter status from inception, product reflection, implementation, and test evidence.
+
+Options:
+  --dry-run         Print current status, derived status, reason, and next action.
+  --apply           Update only the status line in each stale description.md frontmatter.
+  --id <WI-XXX>     Limit report/apply to one work item.
+  --fail-on-stale   Return exit code 1 when dry-run finds stale status.
+  --json            Output machine-readable JSON.
+  --help, -h        Show this help`,
   "phasegate:detect-drift": `Usage: phasegate phasegate:detect-drift [options]
 
 Run L4-001 drift detection between design documents and source code. WARNING: scans the project filesystem.
@@ -962,6 +974,23 @@ async function main(): Promise<void> {
         break;
       }
 
+      case "work-items:status": {
+        const mod = createTraceabilityModelModule(
+          rootDir,
+          toTraceabilityModelOptions(resolvedConfig),
+        );
+        const result = await mod.workItemStatusCommandHandler.execute({
+          dryRun: hasFlag(args, "--dry-run"),
+          apply: hasFlag(args, "--apply"),
+          failOnStale: hasFlag(args, "--fail-on-stale"),
+          id: parseFlag(args, "--id"),
+          json,
+        });
+        console.log(result.text);
+        process.exit(result.exitCode);
+        break;
+      }
+
       // ── phase-dependency-model ──
       case "check-phase-gate": {
         const phaseConfig = resolvedConfig ? toPhaseConfigSection(resolvedConfig) : undefined;

package/scripts/harness/traceability-model/application/usecases/apply-work-item-status-usecase.ts

@@ -0,0 +1,30 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-126
+
+import type { WorkItemStatusPort } from "../../domain/ports/work-item-status-port.js";
+import type { WorkItemStatusApplyResult } from "../../domain/value-objects/work-item-status-report.js";
+import type { DeriveWorkItemStatusUseCase } from "./derive-work-item-status-usecase.js";
+
+export interface ApplyWorkItemStatusUseCaseDeps {
+  readonly deriveWorkItemStatusUseCase: Pick<DeriveWorkItemStatusUseCase, "execute">;
+  readonly workItemStatusPort: WorkItemStatusPort;
+}
+
+export class ApplyWorkItemStatusUseCase {
+  private readonly deriveWorkItemStatusUseCase: Pick<DeriveWorkItemStatusUseCase, "execute">;
+  private readonly workItemStatusPort: WorkItemStatusPort;
+
+  constructor(deps: ApplyWorkItemStatusUseCaseDeps) {
+    this.deriveWorkItemStatusUseCase = deps.deriveWorkItemStatusUseCase;
+    this.workItemStatusPort = deps.workItemStatusPort;
+  }
+
+  async execute(input: { readonly id?: string } = {}): Promise<WorkItemStatusApplyResult> {
+    const reports = await this.deriveWorkItemStatusUseCase.execute();
+    const targetReports = input.id
+      ? reports.filter((report) => report.id === input.id)
+      : reports;
+    return this.workItemStatusPort.applyDerivedStatuses(targetReports);
+  }
+}

package/scripts/harness/traceability-model/application/usecases/derive-work-item-status-usecase.ts

@@ -0,0 +1,27 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-126
+
+import type { WorkItemStatusPort } from "../../domain/ports/work-item-status-port.js";
+import { WorkItemStatusDerivationService } from "../../domain/services/work-item-status-derivation-service.js";
+import type { WorkItemStatusReport } from "../../domain/value-objects/work-item-status-report.js";
+
+export interface DeriveWorkItemStatusUseCaseDeps {
+  readonly workItemStatusPort: WorkItemStatusPort;
+  readonly derivationService: WorkItemStatusDerivationService;
+}
+
+export class DeriveWorkItemStatusUseCase {
+  private readonly workItemStatusPort: WorkItemStatusPort;
+  private readonly derivationService: WorkItemStatusDerivationService;
+
+  constructor(deps: DeriveWorkItemStatusUseCaseDeps) {
+    this.workItemStatusPort = deps.workItemStatusPort;
+    this.derivationService = deps.derivationService;
+  }
+
+  async execute(): Promise<readonly WorkItemStatusReport[]> {
+    const inputs = await this.workItemStatusPort.listWorkItemStatusInputs();
+    return Object.freeze(inputs.map((input) => this.derivationService.derive(input)));
+  }
+}

package/scripts/harness/traceability-model/composition-root.ts

@@ -7,6 +7,8 @@
  */
 
 import { ApplyWorkItemMigrationUseCase } from "./application/usecases/apply-work-item-migration-usecase.js";
+import { ApplyWorkItemStatusUseCase } from "./application/usecases/apply-work-item-status-usecase.js";
+import { DeriveWorkItemStatusUseCase } from "./application/usecases/derive-work-item-status-usecase.js";
 import { PlanWorkItemMigrationUseCase } from "./application/usecases/plan-work-item-migration-usecase.js";
 import { ValidateDesignStoryAnnotationsUseCase } from "./application/usecases/validate-design-story-annotations-usecase.js";
 import { ValidateImplementationMetadataUseCase } from "./application/usecases/validate-implementation-metadata-usecase.js";
@@ -14,17 +16,20 @@ import { ValidateTestStoryMetadataUseCase } from "./application/usecases/validat
 import { MetadataValidator } from "./domain/services/metadata-validator.js";
 import { StoryIdAliasResolver } from "./domain/services/story-id-alias-resolver.js";
 import { TraceabilityChainBuilder } from "./domain/services/traceability-chain-builder.js";
+import { WorkItemStatusDerivationService } from "./domain/services/work-item-status-derivation-service.js";
 import { ProjectRelativePath } from "./domain/value-objects/project-relative-path.js";
 import { FileSystemInceptionPlanGateway } from "./infrastructure/gateways/file-system-inception-plan-gateway.js";
 import { FileSystemMetadataReader } from "./infrastructure/gateways/file-system-metadata-reader.js";
 import { FileSystemWorkItemMigrationApplyGateway } from "./infrastructure/gateways/file-system-work-item-migration-apply-gateway.js";
 import { FileSystemWorkItemMigrationSourceGateway } from "./infrastructure/gateways/file-system-work-item-migration-source-gateway.js";
 import { FileSystemWorkItemIdentityGateway } from "./infrastructure/gateways/file-system-work-item-identity-gateway.js";
+import { FileSystemWorkItemStatusGateway } from "./infrastructure/gateways/file-system-work-item-status-gateway.js";
 import { MarkdownDesignDocumentGateway } from "./infrastructure/gateways/markdown-design-document-gateway.js";
 import { MarkdownStoryCatalogGateway } from "./infrastructure/gateways/markdown-story-catalog-gateway.js";
 import { MarkdownUnitDefinitionGateway } from "./infrastructure/gateways/markdown-unit-definition-gateway.js";
 import { MigrateWorkItemsCommandHandler } from "./presentation/cli/migrate-work-items-command-handler.js";
 import { ValidateMetadataCommandHandler } from "./presentation/cli/validate-metadata-command-handler.js";
+import { WorkItemStatusCommandHandler } from "./presentation/cli/work-item-status-command-handler.js";
 
 export interface TraceabilityModelPathRoots {
   readonly designDocsRoot: string;
@@ -63,6 +68,7 @@ export function createTraceabilityModelModule(
   const workItemMigrationSource = new FileSystemWorkItemMigrationSourceGateway({ rootDir });
   const workItemMigrationApply = new FileSystemWorkItemMigrationApplyGateway({ rootDir });
   const workItemIdentity = new FileSystemWorkItemIdentityGateway({ rootDir });
+  const workItemStatus = new FileSystemWorkItemStatusGateway({ rootDir });
 
   // Domain services
   const metadataValidator = new MetadataValidator({
@@ -78,6 +84,7 @@ export function createTraceabilityModelModule(
     storyCatalogPath,
   });
   const storyIdAliasResolver = new StoryIdAliasResolver(storyCatalog);
+  const workItemStatusDerivationService = new WorkItemStatusDerivationService();
 
   // Usecases
   const validateImplementationMetadataUseCase = new ValidateImplementationMetadataUseCase({
@@ -100,6 +107,14 @@ export function createTraceabilityModelModule(
     planWorkItemMigrationUseCase,
     applyPort: workItemMigrationApply,
   });
+  const deriveWorkItemStatusUseCase = new DeriveWorkItemStatusUseCase({
+    workItemStatusPort: workItemStatus,
+    derivationService: workItemStatusDerivationService,
+  });
+  const applyWorkItemStatusUseCase = new ApplyWorkItemStatusUseCase({
+    deriveWorkItemStatusUseCase,
+    workItemStatusPort: workItemStatus,
+  });
 
   // Presentation handlers
   const validateMetadataCommandHandler = new ValidateMetadataCommandHandler({
@@ -112,10 +127,15 @@ export function createTraceabilityModelModule(
     planWorkItemMigrationUseCase,
     applyWorkItemMigrationUseCase,
   });
+  const workItemStatusCommandHandler = new WorkItemStatusCommandHandler({
+    deriveWorkItemStatusUseCase,
+    applyWorkItemStatusUseCase,
+  });
 
   return {
     validateMetadataCommandHandler,
     migrateWorkItemsCommandHandler,
+    workItemStatusCommandHandler,
     // expose key services for cross-unit use
     storyCatalog,
     traceabilityChainBuilder,

package/scripts/harness/traceability-model/domain/ports/work-item-status-port.ts

@@ -0,0 +1,16 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-126
+
+import type {
+  WorkItemStatusApplyResult,
+  WorkItemStatusInput,
+  WorkItemStatusReport,
+} from "../value-objects/work-item-status-report.js";
+
+export interface WorkItemStatusPort {
+  listWorkItemStatusInputs(): Promise<readonly WorkItemStatusInput[]>;
+  applyDerivedStatuses(
+    reports: readonly WorkItemStatusReport[],
+  ): Promise<WorkItemStatusApplyResult>;
+}

package/scripts/harness/traceability-model/domain/services/work-item-status-derivation-service.ts

@@ -0,0 +1,121 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-126
+
+import type { WorkItemStatus } from "../value-objects/work-item-frontmatter.js";
+import type {
+  WorkItemStatusInput,
+  WorkItemStatusReport,
+} from "../value-objects/work-item-status-report.js";
+
+const ORDER: Record<WorkItemStatus, number> = {
+  drafted: 0,
+  reflected: 1,
+  implemented: 2,
+  tested: 3,
+  completed: 3,
+};
+
+export class WorkItemStatusDerivationService {
+  derive(input: WorkItemStatusInput): WorkItemStatusReport {
+    const derivedStatus = this.deriveStatus(input);
+    const currentStatus = input.frontmatter.status ?? "drafted";
+    const reason = this.reasonFor(input, derivedStatus);
+    const nextAction = this.nextActionFor(input, derivedStatus);
+
+    return Object.freeze({
+      id: input.frontmatter.id,
+      type: input.frontmatter.type,
+      descriptionPath: input.descriptionPath,
+      currentStatus,
+      derivedStatus,
+      stale: currentStatus !== derivedStatus,
+      reason,
+      nextAction,
+      evidence: Object.freeze({
+        hasRequiredInceptionArtifacts: this.hasRequiredInceptionArtifacts(input),
+        reflectedUnits: Object.freeze([...this.reflectedUnits(input)]),
+        missingReflectionUnits: Object.freeze([...this.missingReflectionUnits(input)]),
+        implementationPaths: Object.freeze([...input.implementationPaths]),
+        testPaths: Object.freeze([...input.testPaths]),
+      }),
+    });
+  }
+
+  private deriveStatus(input: WorkItemStatusInput): WorkItemStatus {
+    const type = input.frontmatter.type;
+    if (type === "chore") return "drafted";
+
+    const reflected = this.missingReflectionUnits(input).length === 0;
+    const implemented = input.implementationPaths.length > 0;
+    const tested = input.testPaths.length > 0;
+
+    if (type === "fix") {
+      if (implemented) return "implemented";
+      if (reflected) return "reflected";
+      return "drafted";
+    }
+
+    if (tested) return "tested";
+    if (implemented) return "implemented";
+    if (reflected) return "reflected";
+    return "drafted";
+  }
+
+  private reasonFor(input: WorkItemStatusInput, status: WorkItemStatus): string {
+    if (!this.hasRequiredInceptionArtifacts(input)) {
+      return `missing inception artifacts: ${this.missingInceptionArtifacts(input).join(", ")}`;
+    }
+    if (status === "tested") return "test evidence with @work-item-id exists";
+    if (status === "implemented") return "implementation evidence with @work-item-id exists";
+    if (status === "reflected") return "all affected units have product reflection";
+    if (input.frontmatter.type === "chore") return "chore work items complete at drafted";
+    return "product reflection is not complete";
+  }
+
+  private nextActionFor(input: WorkItemStatusInput, status: WorkItemStatus): string {
+    const missingArtifacts = this.missingInceptionArtifacts(input);
+    if (missingArtifacts.length > 0) {
+      return `create inception artifacts: ${missingArtifacts.join(", ")}`;
+    }
+    const missingUnits = this.missingReflectionUnits(input);
+    if (missingUnits.length > 0) {
+      return `reflect @work-item-id ${input.frontmatter.id} in product docs for: ${missingUnits.join(", ")}`;
+    }
+    if (input.frontmatter.type === "chore") return "no further status transition required";
+    if (status === "reflected") return `add implementation annotated with @work-item-id ${input.frontmatter.id}`;
+    if (status === "implemented" && input.frontmatter.type !== "fix") {
+      return `add tests annotated with @work-item-id ${input.frontmatter.id}`;
+    }
+    return "status is up to date";
+  }
+
+  private hasRequiredInceptionArtifacts(input: WorkItemStatusInput): boolean {
+    return this.missingInceptionArtifacts(input).length === 0;
+  }
+
+  private missingInceptionArtifacts(input: WorkItemStatusInput): readonly string[] {
+    const existing = new Set(input.existingInceptionArtifacts);
+    return input.requiredInceptionArtifacts.filter((artifact) => !existing.has(artifact));
+  }
+
+  private reflectedUnits(input: WorkItemStatusInput): readonly string[] {
+    const reflected = new Set<string>();
+    for (const filePath of input.productReflectionPaths) {
+      const unit = this.extractConstructionUnit(filePath);
+      if (unit) reflected.add(unit);
+    }
+    return input.affectedUnits.filter((unit) => reflected.has(unit));
+  }
+
+  private missingReflectionUnits(input: WorkItemStatusInput): readonly string[] {
+    if (input.frontmatter.type === "chore") return [];
+    const reflected = new Set(this.reflectedUnits(input));
+    return input.affectedUnits.filter((unit) => !reflected.has(unit));
+  }
+
+  private extractConstructionUnit(filePath: string): string | null {
+    const match = /^docs\/product\/construction\/([^/]+)\//.exec(filePath);
+    return match?.[1] ?? null;
+  }
+}

package/scripts/harness/traceability-model/domain/value-objects/work-item-status-report.ts

@@ -0,0 +1,47 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-126
+
+import type {
+  WorkItemFrontmatter,
+  WorkItemStatus,
+  WorkItemType,
+} from "./work-item-frontmatter.js";
+
+export interface WorkItemStatusEvidence {
+  readonly hasRequiredInceptionArtifacts: boolean;
+  readonly reflectedUnits: readonly string[];
+  readonly missingReflectionUnits: readonly string[];
+  readonly implementationPaths: readonly string[];
+  readonly testPaths: readonly string[];
+}
+
+export interface WorkItemStatusInput {
+  readonly descriptionPath: string;
+  readonly directoryId: string;
+  readonly ownerUnit: string | null;
+  readonly frontmatter: WorkItemFrontmatter;
+  readonly requiredInceptionArtifacts: readonly string[];
+  readonly existingInceptionArtifacts: readonly string[];
+  readonly affectedUnits: readonly string[];
+  readonly productReflectionPaths: readonly string[];
+  readonly implementationPaths: readonly string[];
+  readonly testPaths: readonly string[];
+}
+
+export interface WorkItemStatusReport {
+  readonly id: string;
+  readonly type: WorkItemType;
+  readonly descriptionPath: string;
+  readonly currentStatus: WorkItemStatus;
+  readonly derivedStatus: WorkItemStatus;
+  readonly stale: boolean;
+  readonly reason: string;
+  readonly nextAction: string;
+  readonly evidence: WorkItemStatusEvidence;
+}
+
+export interface WorkItemStatusApplyResult {
+  readonly updated: readonly WorkItemStatusReport[];
+  readonly unchanged: readonly WorkItemStatusReport[];
+}

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-status-gateway.ts

@@ -0,0 +1,240 @@
+// @unit traceability-model
+// @layer infrastructure
+// @work-item-id WI-126
+
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import type { WorkItemStatusPort } from "../../domain/ports/work-item-status-port.js";
+import type { WorkItemFrontmatter } from "../../domain/value-objects/work-item-frontmatter.js";
+import type {
+  WorkItemStatusApplyResult,
+  WorkItemStatusInput,
+  WorkItemStatusReport,
+} from "../../domain/value-objects/work-item-status-report.js";
+import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
+
+const WI_DIR_PATTERN = /^WI-\d+$/;
+const MARKDOWN_PATTERN = /\.mdx?$/;
+const SOURCE_PATTERN = /\.(?:ts|tsx|js|jsx)$/;
+const SKIPPED_DIRS = new Set(["archive", "_shared", "_operation", "share", "node_modules", ".git"]);
+
+export interface FileSystemWorkItemStatusGatewayDeps {
+  readonly rootDir: string;
+  readonly inceptionRoot?: string;
+  readonly productRoot?: string;
+  readonly sourceRoot?: string;
+  readonly testRoot?: string;
+}
+
+export class FileSystemWorkItemStatusGateway implements WorkItemStatusPort {
+  private readonly rootDir: string;
+  private readonly inceptionRoot: string;
+  private readonly productRoot: string;
+  private readonly sourceRoot: string;
+  private readonly testRoot: string;
+
+  constructor(deps: FileSystemWorkItemStatusGatewayDeps) {
+    this.rootDir = deps.rootDir;
+    this.inceptionRoot = deps.inceptionRoot ?? "docs/inception";
+    this.productRoot = deps.productRoot ?? "docs/product";
+    this.sourceRoot = deps.sourceRoot ?? "scripts/harness";
+    this.testRoot = deps.testRoot ?? "scripts/harness/__tests__";
+  }
+
+  async listWorkItemStatusInputs(): Promise<readonly WorkItemStatusInput[]> {
+    const entries = await this.listDescriptions(this.inceptionRoot);
+    const productFiles = await this.listFiles(this.productRoot, MARKDOWN_PATTERN);
+    const sourceFiles = (await this.listFiles(this.sourceRoot, SOURCE_PATTERN)).filter(
+      (filePath) => !filePath.startsWith(this.testRoot),
+    );
+    const testFiles = await this.listFiles(this.testRoot, SOURCE_PATTERN);
+
+    const inputs: WorkItemStatusInput[] = [];
+    for (const entry of entries) {
+      const content = await readFile(path.join(this.rootDir, entry.descriptionPath), "utf8");
+      const frontmatter = parseWorkItemFrontmatter(content);
+      if (frontmatter === null) continue;
+
+      const aliases = this.aliasesFor(frontmatter);
+      const productReflectionPaths = await this.filesContainingAny(productFiles, aliases);
+      const implementationPaths = await this.filesContainingAny(sourceFiles, aliases);
+      const testPaths = await this.filesContainingAny(testFiles, aliases);
+      const wiDir = path.posix.dirname(entry.descriptionPath);
+      const existingInceptionArtifacts = await this.existingInceptionArtifacts(wiDir);
+
+      inputs.push(Object.freeze({
+        descriptionPath: entry.descriptionPath,
+        directoryId: entry.directoryId,
+        ownerUnit: entry.ownerUnit,
+        frontmatter,
+        requiredInceptionArtifacts: this.requiredInceptionArtifacts(frontmatter),
+        existingInceptionArtifacts,
+        affectedUnits: this.affectedUnits(entry.ownerUnit, frontmatter),
+        productReflectionPaths,
+        implementationPaths,
+        testPaths,
+      }));
+    }
+    return Object.freeze(inputs.sort((a, b) => a.descriptionPath.localeCompare(b.descriptionPath)));
+  }
+
+  async applyDerivedStatuses(
+    reports: readonly WorkItemStatusReport[],
+  ): Promise<WorkItemStatusApplyResult> {
+    const updated: WorkItemStatusReport[] = [];
+    const unchanged: WorkItemStatusReport[] = [];
+    for (const report of reports) {
+      if (!report.stale) {
+        unchanged.push(report);
+        continue;
+      }
+      const absolutePath = path.join(this.rootDir, report.descriptionPath);
+      const content = await readFile(absolutePath, "utf8");
+      const nextContent = this.replaceStatusLine(content, report.derivedStatus);
+      await writeFile(absolutePath, nextContent, "utf8");
+      updated.push(report);
+    }
+    return Object.freeze({
+      updated: Object.freeze(updated),
+      unchanged: Object.freeze(unchanged),
+    });
+  }
+
+  private async listDescriptions(relativeDir: string): Promise<readonly {
+    readonly descriptionPath: string;
+    readonly directoryId: string;
+    readonly ownerUnit: string | null;
+  }[]> {
+    const results: {
+      descriptionPath: string;
+      directoryId: string;
+      ownerUnit: string | null;
+    }[] = [];
+    await this.collectDescriptions(relativeDir, results);
+    return results;
+  }
+
+  private async collectDescriptions(
+    relativeDir: string,
+    results: { descriptionPath: string; directoryId: string; ownerUnit: string | null }[],
+  ): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(path.join(this.rootDir, relativeDir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIPPED_DIRS.has(entry.name)) continue;
+      const childDir = path.posix.join(relativeDir, entry.name);
+      if (WI_DIR_PATTERN.test(entry.name)) {
+        results.push({
+          descriptionPath: path.posix.join(childDir, "description.md"),
+          directoryId: entry.name,
+          ownerUnit: this.ownerUnitFor(childDir),
+        });
+        continue;
+      }
+      await this.collectDescriptions(childDir, results);
+    }
+  }
+
+  private ownerUnitFor(wiDir: string): string | null {
+    const relative = wiDir.slice(this.inceptionRoot.length).replace(/^\/+/, "");
+    const first = relative.split("/")[0];
+    if (!first || first === "_cross") return null;
+    return first;
+  }
+
+  private async listFiles(relativeDir: string, pattern: RegExp): Promise<readonly string[]> {
+    const results: string[] = [];
+    await this.collectFiles(relativeDir, pattern, results);
+    return Object.freeze(results.sort());
+  }
+
+  private async collectFiles(relativeDir: string, pattern: RegExp, results: string[]): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(path.join(this.rootDir, relativeDir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      const childPath = path.posix.join(relativeDir, entry.name);
+      if (entry.isDirectory()) {
+        await this.collectFiles(childPath, pattern, results);
+      } else if (entry.isFile() && pattern.test(entry.name)) {
+        results.push(childPath);
+      }
+    }
+  }
+
+  private async filesContainingAny(files: readonly string[], aliases: readonly string[]): Promise<readonly string[]> {
+    const results: string[] = [];
+    for (const filePath of files) {
+      const content = await readFile(path.join(this.rootDir, filePath), "utf8");
+      if (aliases.some((alias) => this.containsWorkItemAnnotation(content, alias))) {
+        results.push(filePath);
+      }
+    }
+    return Object.freeze(results);
+  }
+
+  private containsWorkItemAnnotation(content: string, alias: string): boolean {
+    const escaped = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`@(work-item-id|story-id|issue-id|story)\\s+[^\\n]*\\b${escaped}\\b`).test(content);
+  }
+
+  private aliasesFor(frontmatter: WorkItemFrontmatter): readonly string[] {
+    return Object.freeze([frontmatter.id, frontmatter.legacyId].filter((value): value is string => Boolean(value)));
+  }
+
+  private requiredInceptionArtifacts(frontmatter: WorkItemFrontmatter): readonly string[] {
+    switch (frontmatter.type) {
+      case "story":
+        return Object.freeze(["description.md", "logical_design.md", "domain_model.md", "unit_test_design.md"]);
+      case "issue":
+        return Object.freeze(["description.md", "logical_design.md", "domain_model.md"]);
+      case "refactor":
+        return Object.freeze(["description.md", "logical_design.md"]);
+      case "fix":
+      case "chore":
+        return Object.freeze(["description.md"]);
+    }
+  }
+
+  private async existingInceptionArtifacts(wiDir: string): Promise<readonly string[]> {
+    try {
+      const entries = await readdir(path.join(this.rootDir, wiDir), { withFileTypes: true });
+      return Object.freeze(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+    } catch {
+      return Object.freeze([]);
+    }
+  }
+
+  private affectedUnits(ownerUnit: string | null, frontmatter: WorkItemFrontmatter): readonly string[] {
+    if (frontmatter.affects && frontmatter.affects.length > 0) {
+      return Object.freeze([...frontmatter.affects]);
+    }
+    if (ownerUnit) return Object.freeze([ownerUnit]);
+    return Object.freeze([]);
+  }
+
+  private replaceStatusLine(content: string, status: string): string {
+    if (!content.startsWith("---")) {
+      throw new Error("description.md frontmatter is missing");
+    }
+    const frontmatterEnd = content.indexOf("\n---", 4);
+    if (frontmatterEnd === -1) {
+      throw new Error("description.md frontmatter is not closed");
+    }
+    const frontmatter = content.slice(0, frontmatterEnd);
+    if (!/(\nstatus:\s*)[^\n]+/.test(frontmatter)) {
+      throw new Error("description.md frontmatter status is missing");
+    }
+    const nextFrontmatter = frontmatter.replace(/(\nstatus:\s*)[^\n]+/, `$1${status}`);
+    return nextFrontmatter + content.slice(frontmatterEnd);
+  }
+}

package/scripts/harness/traceability-model/presentation/cli/work-item-status-command-handler.ts

@@ -0,0 +1,103 @@
+// @unit traceability-model
+// @layer presentation
+// @work-item-id WI-126
+
+import type { ApplyWorkItemStatusUseCase } from "../../application/usecases/apply-work-item-status-usecase.js";
+import type { DeriveWorkItemStatusUseCase } from "../../application/usecases/derive-work-item-status-usecase.js";
+import type {
+  WorkItemStatusApplyResult,
+  WorkItemStatusReport,
+} from "../../domain/value-objects/work-item-status-report.js";
+
+export interface WorkItemStatusCommandInput {
+  readonly dryRun?: boolean;
+  readonly apply?: boolean;
+  readonly json?: boolean;
+  readonly failOnStale?: boolean;
+  readonly id?: string;
+}
+
+export interface WorkItemStatusCommandOutput {
+  readonly exitCode: 0 | 1 | 2;
+  readonly text: string;
+  readonly reports: readonly WorkItemStatusReport[];
+}
+
+export interface WorkItemStatusCommandHandlerDeps {
+  readonly deriveWorkItemStatusUseCase: Pick<DeriveWorkItemStatusUseCase, "execute">;
+  readonly applyWorkItemStatusUseCase: Pick<ApplyWorkItemStatusUseCase, "execute">;
+}
+
+export class WorkItemStatusCommandHandler {
+  private readonly deriveWorkItemStatusUseCase: Pick<DeriveWorkItemStatusUseCase, "execute">;
+  private readonly applyWorkItemStatusUseCase: Pick<ApplyWorkItemStatusUseCase, "execute">;
+
+  constructor(deps: WorkItemStatusCommandHandlerDeps) {
+    this.deriveWorkItemStatusUseCase = deps.deriveWorkItemStatusUseCase;
+    this.applyWorkItemStatusUseCase = deps.applyWorkItemStatusUseCase;
+  }
+
+  async execute(input: WorkItemStatusCommandInput): Promise<Readonly<WorkItemStatusCommandOutput>> {
+    if (input.apply && input.dryRun) {
+      return Object.freeze({
+        exitCode: 2,
+        text: "Error: --dry-run and --apply cannot be used together",
+        reports: Object.freeze([]),
+      });
+    }
+    if (!input.apply && !input.dryRun) {
+      return Object.freeze({
+        exitCode: 2,
+        text: "Error: either --dry-run or --apply is required",
+        reports: Object.freeze([]),
+      });
+    }
+
+    if (input.apply) {
+      const result = await this.applyWorkItemStatusUseCase.execute({ id: input.id });
+      const reports = Object.freeze([...result.updated, ...result.unchanged]);
+      return Object.freeze({
+        exitCode: 0,
+        text: input.json ? JSON.stringify(result, null, 2) : this.formatApply(result),
+        reports,
+      });
+    }
+
+    const allReports = await this.deriveWorkItemStatusUseCase.execute();
+    const reports = input.id
+      ? allReports.filter((report) => report.id === input.id)
+      : allReports;
+    const stale = reports.some((report) => report.stale);
+    return Object.freeze({
+      exitCode: stale && input.failOnStale ? 1 : 0,
+      text: input.json ? JSON.stringify({ reports }, null, 2) : this.formatReports(reports),
+      reports,
+    });
+  }
+
+  private formatReports(reports: readonly WorkItemStatusReport[]): string {
+    const lines = ["Work item status report"];
+    for (const report of reports) {
+      const marker = report.stale ? "STALE" : "OK";
+      lines.push(
+        `[${marker}] ${report.id}: current=${report.currentStatus} derived=${report.derivedStatus}`,
+        `  path: ${report.descriptionPath}`,
+        `  reason: ${report.reason}`,
+        `  next: ${report.nextAction}`,
+      );
+    }
+    return lines.join("\n");
+  }
+
+  private formatApply(result: WorkItemStatusApplyResult): string {
+    const lines = ["Work item status apply"];
+    for (const report of result.updated) {
+      lines.push(`updated ${report.id}: ${report.currentStatus} -> ${report.derivedStatus}`);
+    }
+    if (result.updated.length === 0) {
+      lines.push("no updates required");
+    }
+    lines.push(`unchanged: ${result.unchanged.length}`);
+    return lines.join("\n");
+  }
+}