@dailephd/my-dev-kit-orchestrator 1.0.0

package/README.md

@@ -0,0 +1,295 @@
+# my-dev-kit-orchestrator
+
+`my-dev-kit-orchestrator` is a CLI-first workflow shell for design-first software development with coding agents.
+
+It is for teams or individual developers who want a coding agent to work through a bounded sequence of design, pseudocode, testing, implementation, and verification steps instead of jumping straight from a raw request to code.
+
+## Capabilities
+
+`v0.1.0` provided the workflow shell:
+
+- a small CLI command surface
+- five workflow modes: `feature`, `repair`, `test`, `refactor`, `harden`
+- local run folders under `.my-dev-kit-orchestrator/runs/`
+- stage-specific prompt generation
+- plain-text prompt and artifact files
+- simple stage advancement based on expected artifact file existence
+
+`v0.6.0` adds judge correction routing and trace-aware workflow recovery:
+
+- judge verdict parser: reads `Verdict:` and `Recommended next stage:` from `judge-report.txt`
+- supported verdicts: `PASS`, `DESIGN_INCOMPLETE`, `PSEUDOCODE_INCOMPLETE`, `IMPLEMENTATION_MISMATCH`, `TEST_COVERAGE_INCOMPLETE`, `ARCHITECTURE_MISMATCH`, `NEED_VERIFICATION`, `NEED_CONTEXT`, `SCOPE_VIOLATION`, `BLOCKED`
+- deterministic routing table maps each non-PASS verdict to a correction stage
+- `status` command shows a Judge correction section when a judge report is present (verdict, routed stage, warnings)
+- `prompt` command selects the routed correction stage and generates a bounded correction-stage prompt
+- correction prompts include the judge report, prior stage inputs, and design-map when present
+- `SCOPE_VIOLATION` and `BLOCKED` verdicts produce a blocked state - no correction stage is routed
+- unknown verdicts fail the parser instead of being guessed
+- `check --trace` and `check --design-map` suggest a correction stage for each trace issue
+- trace-aware correction suggestions are deterministic: missing `BEH-NNN` target → suggest `behavior-model`, missing `PSE-NNN` → suggest `pseudocode-packet`, etc.
+- correction routing is a prompt-generation aid, not an autonomous repair runtime
+- `src/judgeParser.ts`: `parseJudgeReport`, `isValidVerdict`, `JUDGE_VERDICTS`, `JudgeVerdict`
+- `src/correctionRouter.ts`: `routeJudgeVerdict`, `parseAndRoute`, `CORRECTABLE_STAGES`, `CorrectionRouteResult`
+- `src/correctionState.ts`: `readCorrectionState`, `isCorrectionActive`
+- see [docs/ARTIFACTS.md](docs/ARTIFACTS.md) and [docs/USAGE.md](docs/USAGE.md) for correction routing usage
+
+`v0.5.0` adds design trace IDs and trace link checking:
+
+- `check --trace`: deterministic trace link checker across all run artifacts
+- `check --design-map`: checks the DesignMap artifact (required sections + trace links)
+- `check --strict --trace` / `check --strict --design-map`: promote warns to failures
+- `trace-check-results.json` persists trace check results per run
+- `status` command shows a trace check summary when results are available
+- `src/traceModel.ts`: `TRACE_PREFIXES`, `TRACE_ID_RE`, `isValidTraceId`, `isMalformedTraceId`
+- `src/traceParser.ts`: `parseTraceIds`, `parseTraceLinks`, `findMalformedTraceIds`, `findDuplicateIds`, `findOrphanIds`, `findMissingLinkTargets`, `parseTrace`
+- `src/traceChecker.ts`: `parseDeclaredTraceIds` (skips link lines to avoid false negatives), `checkArtifactTrace`, `checkAllTraces`, `checkDesignMapTrace`
+- `DesignMap` artifact kind added to section registry with 18 required sections
+- Trace IDs are optional guidance in `behavior-model`, `pseudocode-packet`, and `test-strategy` prompts
+- `judge` prompt requests trace link review when trace IDs are present
+- check codes: `TRACE_MALFORMED_ID`, `TRACE_DUPLICATE_ID`, `TRACE_ORPHAN_ID`, `TRACE_MISSING_LINK_TARGET`
+- canonical trace ID format: `PREFIX-NNN` (3+ zero-padded digits; prefix one of `REQ|CTX|BEH|INV|TRN|PSE|TST|IMP|VER|RISK`)
+- see [docs/ARTIFACTS.md](docs/ARTIFACTS.md) for trace check codes and DesignMap sections
+
+`v0.4.0` adds artifact content checks and prompt quality checks:
+
+- `check` command: `my-dev-kit-orchestrator check [--artifact <name>] [--prompts] [--strict]`
+- deterministic text-based checks for required sections in each artifact kind
+- check codes: `MISSING_FILE`, `MISSING_SECTION`, `EMPTY_SECTION`, `PLACEHOLDER_CONTENT`, `STATUS_MISMATCH` (artifacts); `PROMPT_MISSING_FILE`, `PROMPT_EMPTY`, `PROMPT_MISSING_STAGE_HEADER`, `PROMPT_MISSING_TASK_SECTION`, `PROMPT_MISSING_OUTPUT_ARTIFACT`, `PROMPT_PLACEHOLDER` (prompts)
+- `artifact-check-results.json` persists check results per run
+- `status` command shows a content check summary when results are available
+- `--strict` mode exits 1 on any `warn` in addition to `fail`
+- see [docs/ARTIFACTS.md](docs/ARTIFACTS.md) for check codes and result schema
+
+`v0.3.0` adds artifact lifecycle and resume states:
+
+- artifact lifecycle states: `missing`, `incomplete`, `blocked`, `complete`, `stale`
+- `artifact-state.json` per run persists manual lifecycle state
+- stale artifact detection when upstream artifacts change
+- `status` shows lifecycle state for each artifact with reason for blocked/incomplete/stale
+- `prompt` progression respects incomplete, blocked, and stale states
+- `mark` command for manual lifecycle state updates: `mark <artifact-name> --state <state> [--reason]`
+- backward compatible: existing runs without `artifact-state.json` use file-existence behavior
+
+`v0.2.1` adds extraction mode:
+
+- `--mode extraction` for transferring a bounded feature, workflow, or subsystem from an existing source repository into a new or separate target repository
+- `--source <path>` and `--target <path>` options required for extraction runs
+- the source repository is used for inspection and evidence only; the target repository is where the extracted workflow is implemented, tested, verified, and reported
+- source and target `.my-dev-kit` index directories are kept separate
+- extraction-specific 14-stage workflow with artifact gates before implementation begins: `SourceWorkflowMap`, `SourceToTargetPortingMap`, `DoNotPortList`, `GoldenBehaviorContract`, and `TargetArchitectureProposal`
+- run artifacts placed under the target repository by default
+- cross-platform support verified in the GitHub Actions OS matrix on Ubuntu, Windows, and macOS
+- see [docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the full extraction workflow and [docs/ARTIFACTS.md](docs/ARTIFACTS.md) for artifact contracts
+
+`v0.2.0` added graph-guided architecture context support:
+
+- architecture-context stage prompt now guides the coding agent through graph-guided context acquisition with `my-dev-kit`
+- generated prompt includes the full retrieval sequence, retrieval evidence report template, and ArchitectureContextPacket template
+- `status` command shows supporting report presence for the architecture-context stage
+- stage progression remains based on required artifact presence only
+
+The CLI owns workflow order and prompt generation. Each run advances as the expected artifact files appear on disk.
+
+## How it works with my-dev-kit
+
+`my-dev-kit` and `my-dev-kit-orchestrator` have different responsibilities.
+
+- `my-dev-kit` retrieves bounded project context through graph-guided architecture context workflows such as indexing, search, lookup, slice generation, source retrieval, and optional semantic inspection
+- `my-dev-kit-orchestrator` organizes the staged design-to-code workflow after context acquisition
+- the coding agent records retrieval evidence in `reports/architecture-context-retrieval-report.txt`
+- the coding agent synthesizes that evidence into `artifacts/architecture-context-packet.txt`
+- downstream stages consume the ArchitectureContextPacket rather than raw retrieval output
+
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/WORKFLOWS.md](docs/WORKFLOWS.md), and [docs/ARTIFACTS.md](docs/ARTIFACTS.md) for the detailed design.
+
+## Non-goals (current release)
+
+`my-dev-kit-orchestrator` does not include in v0.6.0:
+
+- full JSON schema validation or Zod/AJV enforcement
+- LLM-based artifact judging or semantic artifact grading
+- automatic artifact rewriting or correction loops
+- automatic judge routing
+- automatic code modification after a judge failure
+- automatic code-to-symbol tracing or AST-level dependency graph tracing
+- test coverage instrumentation
+- LLM-based trace inference or judge inference
+- automatic coding-agent execution
+- automatic `my-dev-kit` command execution
+- design-map visualization
+- direct LLM-provider execution
+- multi-agent runtime
+- extra low-level CLI commands beyond the current surface
+
+Architecture-context prompts may suggest use of `my-dev-kit` when it is available, but `my-dev-kit-orchestrator` does not run `my-dev-kit` automatically.
+
+## Command surface
+
+```text
+my-dev-kit-orchestrator init
+my-dev-kit-orchestrator start "<request>"
+my-dev-kit-orchestrator start --mode <feature|repair|test|refactor|harden|extraction> "<request>"
+my-dev-kit-orchestrator status
+my-dev-kit-orchestrator status --run <run-id>
+my-dev-kit-orchestrator prompt
+my-dev-kit-orchestrator prompt <stage>
+my-dev-kit-orchestrator prompt <stage> --run <run-id>
+my-dev-kit-orchestrator list
+my-dev-kit-orchestrator list --mode <mode>
+my-dev-kit-orchestrator mark <artifact-name> --state <incomplete|blocked|complete> [--reason "<reason>"]
+my-dev-kit-orchestrator check
+my-dev-kit-orchestrator check --artifact <stage-name|filename>
+my-dev-kit-orchestrator check --prompts
+my-dev-kit-orchestrator check --strict
+```
+
+Common flags:
+
+- `--root <path>`: use a specific project root
+- `--mode <mode>`: choose the workflow mode for `start`
+- `--name <run-name>`: use a readable suffix in the run ID
+- `--run <run-id>`: target a specific run for `status` or `prompt`
+- `--output-dir <path>`: write runs outside the default workspace
+
+## Quick start
+
+1. Install dependencies and build the CLI:
+
+   ```bash
+   npm install
+   npm run build
+   ```
+
+2. Initialize the workspace in your project:
+
+   ```bash
+   node dist/cli.js init
+   ```
+
+3. Start a workflow run:
+
+   ```bash
+   node dist/cli.js start "add audit logging to the export command"
+   ```
+
+4. Print the next stage prompt:
+
+   ```bash
+   node dist/cli.js prompt
+   ```
+
+5. Paste the prompt into your coding tool of choice and save the returned artifact into the run folder.
+
+6. Continue stage by stage:
+
+   ```bash
+   node dist/cli.js status
+   node dist/cli.js prompt
+   node dist/cli.js list
+   ```
+
+If you link the package locally, you can use the installed command directly:
+
+```bash
+npm link
+my-dev-kit-orchestrator --help
+```
+
+## Supported modes
+
+### `feature`
+
+Use for new behavior or intentional behavior changes.
+
+Stage order:
+`request-brief -> architecture-context -> behavior-model -> pseudocode-packet -> test-strategy -> implementation -> test-implementation -> verification -> judge -> final-report`
+
+### `repair`
+
+Use when observed behavior diverges from intended design.
+
+Stage order:
+`observed-behavior-report -> architecture-context -> behavior-trace -> divergence-report -> correction-design -> regression-test-strategy -> implementation -> test-implementation -> verification -> judge -> final-report`
+
+### `test`
+
+Use for behavior-derived test design or test implementation for existing behavior.
+
+Stage order:
+`test-target-brief -> architecture-context -> behavior-reconstruction -> pseudocode-summary -> test-strategy -> test-implementation -> verification -> judge -> final-report`
+
+### `refactor`
+
+Use for structure changes that must preserve behavior.
+
+Stage order:
+`refactor-brief -> architecture-context -> existing-behavior-map -> preserved-invariant-list -> compatibility-test-strategy -> refactor-pseudocode-packet -> implementation -> test-implementation -> verification -> judge -> final-report`
+
+### `harden`
+
+Use for validation, guard, resilience, and failure-handling work.
+
+Stage order:
+`hardening-brief -> architecture-context -> assumption-report -> failure-mode-matrix -> guard-pseudocode-packet -> resilience-test-strategy -> implementation -> test-implementation -> verification -> judge -> final-report`
+
+### `extraction`
+
+Use for transferring a bounded feature, workflow, subsystem, or behavior from an existing source repository into a new or separate target repository.
+
+Requires `--source <path>` (source repo, read-only evidence) and `--target <path>` (target repo, implementation destination).
+
+Stage order:
+`request-brief -> source-architecture-context -> source-workflow-map -> porting-map -> golden-behavior-contract -> target-architecture -> behavior-model -> pseudocode-packet -> test-strategy -> implementation -> test-implementation -> verification -> judge -> final-report`
+
+See [docs/WORKFLOWS.md](docs/WORKFLOWS.md) and [docs/ARTIFACTS.md](docs/ARTIFACTS.md) for the full extraction workflow and artifact contracts.
+
+## Run folder layout
+
+Each run lives under `.my-dev-kit-orchestrator/runs/<run-id>/`.
+
+```text
+.my-dev-kit-orchestrator/
+  config.json
+  runs/
+    <run-id>/
+      00-request.txt
+      run.json
+      prompts/
+      artifacts/
+      reports/
+```
+
+Key files and folders:
+
+- `00-request.txt`: the original request passed to `start`
+- `run.json`: run metadata, mode, and ordered stage definitions
+- `prompts/`: generated stage prompt files such as `01-request-brief.prompt.txt`
+- `artifacts/`: stage outputs such as `request-brief.txt` and `pseudocode-packet.txt`
+- `reports/`: reserved run folder for report-oriented outputs and future expansion
+
+The next stage is determined by the first expected artifact file that is missing for the current workflow.
+
+## Install, build, test
+
+```bash
+npm install
+npm run build
+npx tsc --noEmit
+npm test
+```
+
+Optional local lint check:
+
+```bash
+npm run lint
+```
+
+## Documentation
+
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- [docs/USAGE.md](docs/USAGE.md)
+- [docs/WORKFLOWS.md](docs/WORKFLOWS.md)
+- [docs/ARTIFACTS.md](docs/ARTIFACTS.md)
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [ROADMAP.md](docs/ROADMAP.md)

package/dist/artifactChecker.d.ts

@@ -0,0 +1,31 @@
+import { ArtifactStateFile } from './artifactLifecycle';
+import { RunMetadata } from './run';
+export type CheckSeverity = 'pass' | 'warn' | 'fail';
+export interface ArtifactCheckIssue {
+    code: string;
+    severity: CheckSeverity;
+    message: string;
+    section?: string;
+}
+export interface ArtifactCheckResult {
+    artifactFile: string;
+    artifactKind: string;
+    issues: ArtifactCheckIssue[];
+    passed: boolean;
+    checkedAt: string;
+}
+export interface SectionRequirements {
+    required: string[];
+}
+export declare function resolveArtifactKind(stageName: string): string | undefined;
+export declare function getArtifactSectionRequirements(artifactKind: string): SectionRequirements | undefined;
+export interface ParsedArtifact {
+    sections: Map<string, string>;
+    rawContent: string;
+}
+export declare function parseArtifact(content: string): ParsedArtifact;
+export declare function isPlaceholderContent(content: string): boolean;
+export declare function hasStatusMismatch(artifactStatus: string | undefined, lifecycleState: string | undefined): boolean;
+export declare function checkArtifact(runFolder: string, artifactFile: string, stageName: string, stateFile: ArtifactStateFile): ArtifactCheckResult;
+export declare function checkAllArtifacts(meta: RunMetadata, stateFile: ArtifactStateFile): ArtifactCheckResult[];
+//# sourceMappingURL=artifactChecker.d.ts.map

package/dist/artifactChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactChecker.d.ts","sourceRoot":"","sources":["../src/artifactChecker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAIpC,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA6JD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,GACnB,mBAAmB,GAAG,SAAS,CAEjC;AAQD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CA8B7D;AAOD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAID,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,OAAO,CAQT;AAID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,iBAAiB,GAC3B,mBAAmB,CAyErB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,iBAAiB,GAC3B,mBAAmB,EAAE,CASvB"}

package/dist/artifactChecker.js

@@ -0,0 +1,341 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveArtifactKind = resolveArtifactKind;
+exports.getArtifactSectionRequirements = getArtifactSectionRequirements;
+exports.parseArtifact = parseArtifact;
+exports.isPlaceholderContent = isPlaceholderContent;
+exports.hasStatusMismatch = hasStatusMismatch;
+exports.checkArtifact = checkArtifact;
+exports.checkAllArtifacts = checkAllArtifacts;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const SECTION_REGISTRY = {
+    RequestBrief: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Original request',
+            'Requested change',
+            'Target area',
+            'User-visible or external behavior',
+            'Constraints',
+            'Non-goals',
+            'Success criteria',
+            'Ambiguity or missing information',
+            'Expected next stage',
+            'Status',
+        ],
+    },
+    ArchitectureContextPacket: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Project root',
+            'Relevant files',
+            'Relevant symbols',
+            'Status',
+        ],
+    },
+    BehaviorModel: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Status',
+        ],
+    },
+    PseudocodePacket: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Status',
+        ],
+    },
+    TestStrategyPacket: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Status',
+        ],
+    },
+    ImplementationReport: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Status',
+        ],
+    },
+    TestImplementationReport: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Status',
+        ],
+    },
+    VerificationReport: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Status',
+        ],
+    },
+    JudgeReport: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Verdict',
+            'Status',
+        ],
+    },
+    FinalReport: {
+        required: [
+            'Artifact',
+            'Workflow mode',
+            'Run ID',
+            'Status',
+        ],
+    },
+    DesignMap: {
+        required: [
+            'Artifact',
+            'DesignMap',
+            'Workflow mode',
+            'Inputs used',
+            'Trace ID registry',
+            'Requirement links',
+            'Context links',
+            'Behavior links',
+            'Invariant links',
+            'Transition links',
+            'Pseudocode links',
+            'Test responsibility links',
+            'Implementation links',
+            'Verification links',
+            'Risk links',
+            'Orphan or missing links',
+            'Trace gaps',
+            'Status',
+        ],
+    },
+};
+// ─── Artifact kind resolver ───────────────────────────────────────────────────
+const STAGE_TO_KIND = {
+    // core
+    'request-brief': 'RequestBrief',
+    'architecture-context': 'ArchitectureContextPacket',
+    'behavior-model': 'BehaviorModel',
+    'pseudocode-packet': 'PseudocodePacket',
+    'test-strategy': 'TestStrategyPacket',
+    'implementation': 'ImplementationReport',
+    'test-implementation': 'TestImplementationReport',
+    'verification': 'VerificationReport',
+    'judge': 'JudgeReport',
+    'final-report': 'FinalReport',
+    // repair-specific
+    'observed-behavior-report': 'ObservedBehaviorReport',
+    'behavior-trace': 'BehaviorTrace',
+    'divergence-report': 'DivergenceReport',
+    'correction-design': 'CorrectionDesign',
+    'regression-test-strategy': 'RegressionTestStrategy',
+    // test-specific
+    'test-target-brief': 'TestTargetBrief',
+    'behavior-reconstruction': 'BehaviorReconstruction',
+    'pseudocode-summary': 'PseudocodeSummary',
+    // refactor-specific
+    'refactor-brief': 'RefactorBrief',
+    'existing-behavior-map': 'ExistingBehaviorMap',
+    'preserved-invariant-list': 'PreservedInvariantList',
+    'compatibility-test-strategy': 'CompatibilityTestStrategy',
+    'refactor-pseudocode-packet': 'RefactorPseudocodePacket',
+    // harden-specific
+    'hardening-brief': 'HardeningBrief',
+    'assumption-report': 'AssumptionReport',
+    'failure-mode-matrix': 'FailureModeMatrix',
+    'guard-pseudocode-packet': 'GuardPseudocodePacket',
+    'resilience-test-strategy': 'ResilienceTestStrategy',
+    // extraction-specific
+    'source-architecture-context': 'SourceArchitectureContextPacket',
+    'source-workflow-map': 'SourceWorkflowMap',
+    'porting-map': 'PortingMap',
+    'golden-behavior-contract': 'GoldenBehaviorContract',
+    'target-architecture': 'TargetArchitectureProposal',
+    // design trace
+    'design-map': 'DesignMap',
+};
+function resolveArtifactKind(stageName) {
+    return STAGE_TO_KIND[stageName];
+}
+function getArtifactSectionRequirements(artifactKind) {
+    return SECTION_REGISTRY[artifactKind];
+}
+// ─── Text artifact parser ─────────────────────────────────────────────────────
+// Matches section headers: line starting with capital letter, alphanumeric/space/special, colon.
+// Examples: "Artifact:", "Workflow mode:", "Run ID:", "User-visible or external behavior:"
+const SECTION_HEADER_RE = /^([A-Z][A-Za-z0-9 ()/-]{0,79}):\s*(.*)$/;
+function parseArtifact(content) {
+    const sections = new Map();
+    const lines = content.split('\n');
+    let currentKey = null;
+    const accumulator = [];
+    const flushSection = () => {
+        if (currentKey !== null) {
+            sections.set(currentKey, accumulator.join('\n').trim());
+        }
+    };
+    for (const line of lines) {
+        const match = SECTION_HEADER_RE.exec(line);
+        if (match) {
+            flushSection();
+            currentKey = match[1].trim();
+            accumulator.length = 0;
+            const inline = match[2].trim();
+            if (inline) {
+                accumulator.push(inline);
+            }
+        }
+        else if (currentKey !== null) {
+            accumulator.push(line);
+        }
+    }
+    flushSection();
+    return { sections, rawContent: content };
+}
+// ─── Placeholder detection ────────────────────────────────────────────────────
+const PLACEHOLDER_MARKERS = ['TODO', 'PLACEHOLDER', '[TBD]', '[TODO]'];
+const CONTENT_MIN_LENGTH = 80;
+function isPlaceholderContent(content) {
+    const stripped = content.replace(/\s/g, '');
+    if (stripped.length < CONTENT_MIN_LENGTH)
+        return true;
+    for (const marker of PLACEHOLDER_MARKERS) {
+        if (content.includes(marker))
+            return true;
+    }
+    if (/^\s*\.{3,}\s*$/.test(content))
+        return true;
+    return false;
+}
+// ─── Status mismatch detection ────────────────────────────────────────────────
+function hasStatusMismatch(artifactStatus, lifecycleState) {
+    if (!artifactStatus || !lifecycleState)
+        return false;
+    // Take only the first line of Status field; agents may write extra content below it
+    const artStatus = (artifactStatus.split(/[\n\r]/)[0] ?? '').toLowerCase().trim();
+    const lcState = lifecycleState.toLowerCase().trim();
+    if ((artStatus === 'blocked' || artStatus === 'incomplete') && lcState === 'complete')
+        return true;
+    if (artStatus === 'complete' && (lcState === 'blocked' || lcState === 'incomplete'))
+        return true;
+    return false;
+}
+// ─── Check runner ─────────────────────────────────────────────────────────────
+function checkArtifact(runFolder, artifactFile, stageName, stateFile) {
+    const fullPath = path.join(runFolder, artifactFile);
+    const artifactKind = resolveArtifactKind(stageName) ?? 'Unknown';
+    const checkedAt = new Date().toISOString();
+    const issues = [];
+    if (!fs.existsSync(fullPath)) {
+        return {
+            artifactFile,
+            artifactKind,
+            issues: [
+                {
+                    code: 'MISSING_FILE',
+                    severity: 'fail',
+                    message: `Artifact file does not exist: ${artifactFile}`,
+                },
+            ],
+            passed: false,
+            checkedAt,
+        };
+    }
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const parsed = parseArtifact(content);
+    if (isPlaceholderContent(content)) {
+        issues.push({
+            code: 'PLACEHOLDER_CONTENT',
+            severity: 'warn',
+            message: 'Artifact appears to be a placeholder or is suspiciously short',
+        });
+    }
+    const requirements = getArtifactSectionRequirements(artifactKind);
+    if (requirements) {
+        for (const section of requirements.required) {
+            if (!parsed.sections.has(section)) {
+                issues.push({
+                    code: 'MISSING_SECTION',
+                    severity: 'fail',
+                    message: `Required section "${section}" is not present`,
+                    section,
+                });
+            }
+            else {
+                const sectionContent = parsed.sections.get(section) ?? '';
+                if (!sectionContent.trim()) {
+                    issues.push({
+                        code: 'EMPTY_SECTION',
+                        severity: 'warn',
+                        message: `Required section "${section}" is present but empty`,
+                        section,
+                    });
+                }
+            }
+        }
+        const artifactStatus = parsed.sections.get('Status');
+        const stateRecord = stateFile.artifacts[artifactFile];
+        const lifecycleState = stateRecord?.state;
+        if (hasStatusMismatch(artifactStatus, lifecycleState)) {
+            issues.push({
+                code: 'STATUS_MISMATCH',
+                severity: 'warn',
+                message: `Artifact Status field "${artifactStatus}" does not match lifecycle state "${lifecycleState}"`,
+                section: 'Status',
+            });
+        }
+    }
+    const passed = !issues.some((i) => i.severity === 'fail');
+    return { artifactFile, artifactKind, issues, passed, checkedAt };
+}
+function checkAllArtifacts(meta, stateFile) {
+    const results = [];
+    for (const stage of meta.stages) {
+        results.push(checkArtifact(meta.runFolder, stage.artifactFile, stage.name, stateFile));
+        for (const additional of stage.additionalArtifactFiles ?? []) {
+            results.push(checkArtifact(meta.runFolder, additional, stage.name, stateFile));
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=artifactChecker.js.map