@try-works/dsh-recursive-mode 0.1.0

package/scripts/recursive-init.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+"""
+Initialize a recursive-mode run folder and requirements scaffold.
+
+Python equivalent to scripts/recursive-init.ps1.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+
+def write_utf8_no_bom(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8", newline="\n")
+
+
+def ensure_directory(path: Path) -> None:
+    if not path.exists():
+        path.mkdir(parents=True, exist_ok=True)
+        print(f"[OK] Created directory: {path}")
+    else:
+        print(f"[OK] Directory exists: {path}")
+
+
+def load_lint_module():
+    module_path = Path(__file__).with_name("lint-recursive-run.py")
+    spec = importlib.util.spec_from_file_location("recursive_mode_lint", module_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load lint module from {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def run_git(repo_root: Path, *args: str) -> tuple[str | None, str | None]:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), *args],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        return None, f"Unable to execute git: {exc}"
+    if result.returncode != 0:
+        message = result.stderr.strip() or result.stdout.strip() or f"git {' '.join(args)} failed"
+        return None, message
+    return result.stdout.strip(), None
+
+
+def detect_git_context(repo_root: Path) -> tuple[dict[str, str], str | None]:
+    head_sha, head_error = run_git(repo_root, "rev-parse", "--verify", "HEAD^{commit}")
+    if head_error or not head_sha:
+        return {}, f"Unable to resolve HEAD commit for Phase 0 diff basis prefill: {head_error or 'git rev-parse returned no output'}"
+
+    branch_name, branch_error = run_git(repo_root, "symbolic-ref", "--quiet", "--short", "HEAD")
+    if branch_error or not branch_name:
+        branch_name = "(detached HEAD)"
+
+    diff_command = f"git diff --name-only {head_sha}"
+    return {
+        "baseline_type": "local commit",
+        "baseline_reference": head_sha,
+        "comparison_reference": "working-tree",
+        "normalized_baseline": head_sha,
+        "normalized_comparison": "working-tree",
+        "normalized_diff_command": diff_command,
+        "base_branch": branch_name,
+        "worktree_branch": branch_name,
+        "base_commit": head_sha,
+        "notes": "recursive-init prefilled this executable diff basis from the current HEAD commit. If Phase 0 later changes the chosen baseline, update every diff-basis field and rerun lint before locking.",
+    }, None
+
+
+def validate_phase0_diff_basis(repo_root: Path, run_dir: Path) -> str | None:
+    lint = load_lint_module()
+    diff_basis = lint.get_run_diff_basis(run_dir)
+    _normalized_basis, error = lint.normalize_diff_basis(repo_root, diff_basis)
+    return error
+
+
+def build_training_loader_query(run_id: str, template: str, from_issue: str) -> str:
+    run_phrase = re.sub(r"[-_]+", " ", run_id).strip()
+    parts = [f"{template.strip()} recursive run".strip()]
+    if run_phrase:
+        parts.append(run_phrase)
+    if from_issue.strip():
+        parts.append(from_issue.strip())
+    return " ".join(part for part in parts if part)
+
+
+def run_training_loader(repo_root: Path, run_id: str, template: str, from_issue: str) -> int:
+    loader_script = repo_root / ".recursive" / "scripts" / "recursive-training-loader.py"
+    if not loader_script.exists():
+        print("[INFO] recursive-training loader not installed; skipping experiential memory load.")
+        return 0
+
+    query = build_training_loader_query(run_id, template, from_issue)
+    command = [
+        sys.executable,
+        str(loader_script),
+        "--repo-root",
+        str(repo_root),
+        "--query",
+        query,
+    ]
+    result = subprocess.run(command, check=False, capture_output=True, text=True)
+    if result.returncode != 0:
+        details = result.stderr.strip() or result.stdout.strip() or "no diagnostics emitted"
+        print(f"[WARN] recursive-training loader failed: {details}")
+        print("[WARN] Continuing without loaded experiential memory.")
+        return 0
+
+    print("[OK] Loaded repository memory context via recursive-training.")
+    if result.stdout.strip():
+        print(result.stdout.strip())
+    if result.stderr.strip():
+        print(result.stderr.strip())
+    return 0
+
+
+def requirements_content(run_id: str, template: str, from_issue: str) -> str:
+    inputs = ["- [chat summary or source notes if captured in repo]"]
+    if from_issue.strip():
+        inputs.append(f"- Source: {from_issue.strip()}")
+    inputs_block = "\n".join(inputs)
+
+    return f"""Run: `/.recursive/run/{run_id}/`
+Phase: `00 Requirements`
+Status: `DRAFT`
+Workflow version: `recursive-mode-audit-v2`
+Inputs:
+{inputs_block}
+Outputs:
+- `/.recursive/run/{run_id}/00-requirements.md`
+Scope note: This document defines stable requirement identifiers and acceptance criteria. (Template: {template})
+
+## TODO
+
+- [ ] Elicit requirements from user/context
+- [ ] Define requirement identifiers (R1, R2, ...)
+- [ ] Write acceptance criteria for each requirement
+- [ ] Document out of scope items (OOS1, OOS2, ...)
+- [ ] List constraints and assumptions
+- [ ] Complete Coverage Gate checklist
+- [ ] Complete Approval Gate checklist
+
+## Requirements
+
+### `R1` <short title>
+
+Description:
+Acceptance criteria:
+- [observable condition 1]
+- [observable condition 2]
+
+## Out of Scope
+
+- `OOS1`: ...
+
+## Constraints
+
+- ...
+
+## Coverage Gate
+...
+Coverage: FAIL
+
+## Approval Gate
+...
+Approval: FAIL
+"""
+
+
+def worktree_content(run_id: str, repo_root: Path, git_context: dict[str, str], prefill_error: str | None) -> str:
+    base_branch = git_context.get("base_branch", "(resolve during Phase 0)")
+    worktree_branch = git_context.get("worktree_branch", "(resolve during Phase 0)")
+    base_commit = git_context.get("base_commit", "<resolve-before-locking>")
+    baseline_type = git_context.get("baseline_type", "local commit")
+    baseline_reference = git_context.get("baseline_reference", "<resolve-before-locking>")
+    comparison_reference = git_context.get("comparison_reference", "working-tree")
+    normalized_baseline = git_context.get("normalized_baseline", "<resolve-before-locking>")
+    normalized_comparison = git_context.get("normalized_comparison", "working-tree")
+    normalized_diff_command = git_context.get("normalized_diff_command", "git diff --name-only <resolve-before-locking>")
+    notes = git_context.get(
+        "notes",
+        "Populate an executable diff basis before locking Phase 0. Lint and lock will fail until the normalized basis matches live git state.",
+    )
+    setup_note = "recursive-init detected the current repository context and prefilled the Phase 0 diff basis."
+    if prefill_error:
+        setup_note = f"recursive-init could not prefill the Phase 0 diff basis automatically: {prefill_error}"
+
+    return f"""Run: `/.recursive/run/{run_id}/`
+Phase: `00 Worktree`
+Status: `DRAFT`
+Inputs:
+- `/.recursive/run/{run_id}/00-requirements.md`
+- Current git repository state
+Outputs:
+- `/.recursive/run/{run_id}/00-worktree.md`
+Scope note: This document records the Phase 0 worktree context and the executable diff basis that all later audited phases must reuse.
+
+## TODO
+
+- [ ] Confirm the selected worktree location and isolation approach
+- [ ] Confirm the base branch and worktree branch values
+- [ ] Run setup and verify the clean test baseline
+- [ ] Confirm the diff basis fields still match live git state
+- [ ] Complete Coverage Gate checklist
+- [ ] Complete Approval Gate checklist
+
+## Directory Selection
+
+- Repository root: `{repo_root}`
+- Preferred worktree location: `.worktrees/{run_id}/`
+- Update this section with the actual selected location before locking Phase 0.
+
+## Safety Verification
+
+- Original branch / repo state observed at init time: `{base_branch}`
+- Isolation still must be confirmed after the actual worktree is created.
+
+## Worktree Creation
+
+- Intended worktree branch: `{worktree_branch}`
+- Record the actual worktree creation command and output before locking.
+
+## Main Branch Protection
+
+- Base branch source of truth at init time: `{base_branch}`
+- Explicitly document any deviation from isolated worktree execution before locking.
+
+## Project Setup
+
+- Init-time note: {setup_note}
+- Replace this section with the actual setup commands and results during Phase 0.
+
+## Test Baseline Verification
+
+- Record the baseline commands and results after setup completes.
+
+## Worktree Context
+
+- Base branch: `{base_branch}`
+- Worktree branch: `{worktree_branch}`
+- Base commit: `{base_commit}`
+
+## Diff Basis For Later Audits
+
+- Baseline type: `{baseline_type}`
+- Baseline reference: `{baseline_reference}`
+- Comparison reference: `{comparison_reference}`
+- Normalized baseline: `{normalized_baseline}`
+- Normalized comparison: `{normalized_comparison}`
+- Normalized diff command: `{normalized_diff_command}`
+- Base branch: `{base_branch}`
+- Worktree branch: `{worktree_branch}`
+- Diff basis notes: `{notes}`
+
+## Traceability
+
+- Recursive workflow safety -> Phase 0 records a reusable executable diff basis before audited phases begin.
+
+## Coverage Gate
+
+- [ ] Worktree location and branch context are recorded
+- [ ] Setup and clean baseline verification are recorded
+- [ ] Diff basis fields are executable against live git state
+
+Coverage: FAIL
+
+## Approval Gate
+
+- [ ] Phase 0 context is ready for downstream audited phases
+- [ ] No unresolved setup or diff-basis inconsistencies remain
+
+Approval: FAIL
+"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Initialize a recursive-mode run folder and requirements template.")
+    parser.add_argument("--run-id", required=True, help="Run ID (folder name under .recursive/run/).")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    parser.add_argument(
+        "--template",
+        choices=["feature", "bugfix", "refactor"],
+        default="feature",
+        help="Requirements template flavor.",
+    )
+    parser.add_argument("--from-issue", default="", help="Optional issue/ticket/source reference.")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing 00-requirements.md.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    print(f"[INFO] Repo root: {repo_root}")
+
+    run_root = repo_root / ".recursive" / "run"
+    run_dir = run_root / args.run_id
+
+    ensure_directory(run_root)
+    ensure_directory(run_dir)
+    ensure_directory(run_dir / "addenda")
+    ensure_directory(run_dir / "subagents")
+    ensure_directory(run_dir / "router-prompts")
+
+    evidence_dir = run_dir / "evidence"
+    ensure_directory(evidence_dir)
+    for sub in ("screenshots", "logs", "perf", "traces", "review-bundles", "router", "other"):
+        ensure_directory(evidence_dir / sub)
+
+    requirements_path = run_dir / "00-requirements.md"
+    if requirements_path.exists() and not args.force:
+        print(f"[INFO] Requirements file exists, not overwriting: {requirements_path}")
+    else:
+        write_utf8_no_bom(requirements_path, requirements_content(args.run_id, args.template, args.from_issue))
+        print(f"[OK] Wrote requirements template: {requirements_path}")
+
+    git_context, prefill_error = detect_git_context(repo_root)
+    if prefill_error:
+        print(f"[WARN] {prefill_error}")
+
+    worktree_path = run_dir / "00-worktree.md"
+    if worktree_path.exists() and not args.force:
+        print(f"[INFO] Worktree file exists, not overwriting: {worktree_path}")
+    else:
+        write_utf8_no_bom(worktree_path, worktree_content(args.run_id, repo_root, git_context, prefill_error))
+        print(f"[OK] Wrote Phase 0 worktree template: {worktree_path}")
+
+    diff_basis_error = validate_phase0_diff_basis(repo_root, run_dir)
+    if diff_basis_error:
+        print(f"[FAIL] 00-worktree.md diff basis is not executable yet: {diff_basis_error}")
+        print("       Fix the Phase 0 diff-basis fields before locking or relying on downstream audit tooling.")
+        return 1
+    print("[OK] Phase 0 diff basis is executable against live git state.")
+
+    training_status = run_training_loader(repo_root, args.run_id, args.template, args.from_issue)
+    if training_status != 0:
+        return training_status
+
+    print()
+    print("Next steps:")
+    print(f"1) Edit: .recursive/run/{args.run_id}/00-requirements.md")
+    print(f"2) Edit: .recursive/run/{args.run_id}/00-worktree.md")
+    print(f"3) Run:  Implement requirement '{args.run_id}'")
+    print("4) Complete the run through the audited Phase 8 closeout before considering it done.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/recursive-lock.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""
+Lock a recursive-mode artifact after validating gates, structure, and audit requirements.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.util
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+LOCK_HASH_LINE_RE = re.compile(r"(?m)^[ \t]*LockHash:.*(?:\n|$)")
+
+
+def load_phase_rules_module():
+    module_path = Path(__file__).with_name("recursive_phase_rules.py")
+    spec = importlib.util.spec_from_file_location("recursive_phase_rules", module_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load phase rules module from {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except FileNotFoundError:
+        raise RuntimeError(f"Phase rules module not found: {module_path}")
+    return module
+
+
+def load_lint_module():
+    module_path = Path(__file__).with_name("lint-recursive-run.py")
+    spec = importlib.util.spec_from_file_location("recursive_mode_lint", module_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Unable to load lint module from {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def normalize_for_lock_hash(content: str) -> str:
+    normalized = content.replace("\r\n", "\n").replace("\r", "\n")
+    return LOCK_HASH_LINE_RE.sub("", normalized)
+
+
+def lock_hash_from_content(content: str) -> str:
+    normalized = normalize_for_lock_hash(content)
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def render_field(field_name: str, value: str) -> str:
+    return f"{field_name}: `{value}`"
+
+
+def set_or_insert_field(content: str, field_name: str, value: str, after_fields: list[str]) -> str:
+    line = render_field(field_name, value)
+    field_re = re.compile(rf"(?m)^[ \t]*(?:[-*][ \t]+)?{re.escape(field_name)}:\s*.*$")
+    if field_re.search(content):
+        return field_re.sub(line, content, count=1)
+
+    lines = content.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    insert_at = 0
+    for after_field in after_fields:
+        after_re = re.compile(rf"^[ \t]*(?:[-*][ \t]+)?{re.escape(after_field)}:\s*.*$")
+        for index, existing_line in enumerate(lines):
+            if after_re.match(existing_line):
+                insert_at = max(insert_at, index + 1)
+    lines.insert(insert_at, line)
+    return "\n".join(lines)
+
+
+def validate_lockable(lint, repo_root: Path, run_dir: Path, artifact_path: Path) -> tuple[list[str], str, str]:
+    issues: list[str] = []
+    content = artifact_path.read_text(encoding="utf-8")
+    workflow_profile = lint.get_workflow_profile(run_dir)
+    requirement_ids: list[str] = []
+    status = lint.get_md_field_value(content, "Status") or "UNKNOWN"
+
+    requirements_path = run_dir / "00-requirements.md"
+    if requirements_path.exists():
+        requirement_ids = lint.parse_requirement_ids(requirements_path.read_text(encoding="utf-8"))
+
+    actual_changed_files: list[str] | None = None
+    diff_basis_error: str | None = None
+    if workflow_profile == lint.STRICT_WORKFLOW_PROFILE:
+        diff_basis = lint.get_run_diff_basis(run_dir)
+        raw_changed_files, diff_basis_error = lint.get_git_changed_files(repo_root, diff_basis)
+        if raw_changed_files is not None:
+            actual_changed_files = lint.filter_runtime_changed_files(raw_changed_files, run_dir.name)
+
+    if status not in {"DRAFT", "LOCKED"}:
+        issues.append(f"Artifact Status must be DRAFT before locking (found {status})")
+
+    missing_header_fields = [
+        field for field in ("Run", "Phase", "Status", "Inputs", "Outputs", "Scope note") if not lint.has_header_field(content, field)
+    ]
+    if missing_header_fields:
+        issues.append(f"Missing required header field(s): {', '.join(missing_header_fields)}")
+
+    todo_has_section, _todo_total, _todo_checked, todo_unchecked = lint.get_todo_stats(content)
+    if not todo_has_section:
+        issues.append("Missing required section: ## TODO")
+    elif todo_unchecked > 0:
+        issues.append(f"Unchecked TODO items remain: {todo_unchecked}")
+
+    for heading in lint.get_artifact_required_sections(artifact_path.name, workflow_profile):
+        if not lint.has_heading(content, heading):
+            issues.append(f"Missing required section heading: ## {heading}")
+
+    for gate_name in ("Coverage", "Approval"):
+        if not lint.has_gate_line(content, gate_name):
+            issues.append(f"Missing required gate line: {gate_name}: PASS|FAIL")
+
+    issues.extend(lint.lint_traceability(artifact_path, content, requirement_ids))
+    issues.extend(
+        lint.lint_audit_sections(
+            artifact_path,
+            content,
+            workflow_profile,
+            actual_changed_files,
+            diff_basis_error,
+            run_dir.name,
+            run_dir,
+        )
+    )
+    issues.extend(
+        lint.lint_phase_specific_rules(
+            artifact_path,
+            content,
+            workflow_profile,
+            run_dir,
+            repo_root,
+            requirement_ids,
+            actual_changed_files,
+        )
+    )
+
+    if lint.get_gate_status(content, "Coverage") != "PASS":
+        issues.append("Coverage gate must be PASS before locking")
+    if lint.get_gate_status(content, "Approval") != "PASS":
+        issues.append("Approval gate must be PASS before locking")
+    if artifact_path.name == "03-implementation-summary.md" and lint.get_gate_status(content, "TDD Compliance") != "PASS":
+        issues.append("TDD Compliance gate must be PASS before locking Phase 3")
+    if workflow_profile == lint.STRICT_WORKFLOW_PROFILE and artifact_path.name in lint.AUDITED_PHASE_FILES:
+        if lint.get_gate_status(content, "Audit") != "PASS":
+            issues.append("Audit gate must be PASS before locking this audited phase")
+
+    deduped_issues = sorted(set(issues))
+    if status == "LOCKED":
+        locked_at = lint.get_md_field_value(content, "LockedAt")
+        stored_hash = lint.get_md_field_value(content, "LockHash")
+        actual_hash = lock_hash_from_content(content) if stored_hash else None
+        if locked_at and stored_hash and actual_hash and stored_hash.lower() == actual_hash.lower() and not deduped_issues:
+            return [], content, workflow_profile
+        if not deduped_issues:
+            deduped_issues.append("Artifact is already LOCKED but its lock metadata is invalid")
+        else:
+            deduped_issues.append("Artifact is already LOCKED but not lock-valid under current rules; set it back to DRAFT before re-locking")
+
+    return sorted(set(deduped_issues)), content, workflow_profile
+
+
+def resolve_artifact_path(run_dir: Path, artifact_arg: str) -> Path:
+    artifact_path = Path(artifact_arg)
+    if not artifact_path.is_absolute():
+        artifact_path = run_dir / artifact_path
+    artifact_path = artifact_path.resolve()
+    run_root = run_dir.resolve()
+    try:
+        artifact_path.relative_to(run_root)
+    except ValueError as exc:
+        raise ValueError(f"Artifact path must stay within the run directory: {run_root}") from exc
+    return artifact_path
+
+
+def reopen_artifact(phase_rules, run_dir: Path, artifact_path: Path, repo_root: Path) -> int:
+    """
+    Revert a locked artifact back to DRAFT status and invalidate all downstream
+    lock receipts so they must be re-locked in order.
+    """
+    content = artifact_path.read_text(encoding="utf-8")
+    status_re = re.compile(r"(?m)^[ \t]*Status:.*$")
+    locked_at_re = re.compile(r"(?m)^[ \t]*LockedAt:.*\n?")
+    hash_re = re.compile(r"(?m)^[ \t]*LockHash:.*\n?")
+
+    updated = status_re.sub("Status: `DRAFT`", content, count=1)
+    updated = locked_at_re.sub("", updated, count=1)
+    updated = hash_re.sub("", updated, count=1)
+
+    temp_path = artifact_path.with_name(f".{artifact_path.name}.tmp")
+    temp_path.write_text(updated, encoding="utf-8", newline="\n")
+    temp_path.replace(artifact_path)
+
+    rel = artifact_path.relative_to(repo_root)
+    print(f"[OK] Reopened {rel}: reverted to DRAFT")
+
+    artifact_name = artifact_path.name
+    if phase_rules.is_core_artifact(artifact_name):
+        removed = phase_rules.invalidate_receipt(run_dir, artifact_name)
+        if removed:
+            print(f"[OK] Invalidated lock receipt for {artifact_name}")
+
+        stale = phase_rules.get_stale_downstream_phases(artifact_name, run_dir)
+        if stale:
+            print("[WARN] The following downstream phases have stale receipts; re-lock them in order after fixing this phase:")
+            for entry in stale:
+                phase_rules.invalidate_receipt(run_dir, entry["artifact"])
+                print(f"  - {entry['artifact']}: {entry['reason']} (receipt invalidated)")
+
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Lock a recursive-mode artifact after validating gates and structure.")
+    parser.add_argument("--run-id", required=True, help="Run ID under .recursive/run/.")
+    parser.add_argument("--artifact", required=True, help="Artifact file inside the run directory, e.g. 04-test-summary.md or addenda/foo.addendum-01.md")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    parser.add_argument("--reopen", action="store_true", help="Reopen a locked artifact: revert to DRAFT, remove lock metadata, and invalidate downstream receipts.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    run_dir = repo_root / ".recursive" / "run" / args.run_id.strip()
+    if not run_dir.exists():
+        print(f"[FAIL] Run directory not found: {run_dir}")
+        return 1
+
+    try:
+        artifact_path = resolve_artifact_path(run_dir, args.artifact.strip())
+    except ValueError as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    if not artifact_path.exists():
+        print(f"[FAIL] Artifact not found: {artifact_path}")
+        return 1
+
+    phase_rules = load_phase_rules_module()
+
+    if args.reopen:
+        return reopen_artifact(phase_rules, run_dir, artifact_path, repo_root)
+
+    # Prerequisite gate: all earlier phases that exist must be LOCKED first.
+    artifact_name = artifact_path.name
+    if phase_rules.is_core_artifact(artifact_name):
+        blockers = phase_rules.get_prerequisite_blockers(artifact_name, run_dir)
+        if blockers:
+            print(f"[FAIL] Cannot lock {artifact_path.relative_to(repo_root)}: prerequisite phases are not yet LOCKED")
+            for blocker in blockers:
+                print(f"  - {blocker['artifact']}: {blocker['status']} ({blocker['path']})")
+            return 1
+
+    lint = load_lint_module()
+    issues, content, workflow_profile = validate_lockable(lint, repo_root, run_dir, artifact_path)
+
+    if not issues:
+        status = lint.get_md_field_value(content, "Status") or "UNKNOWN"
+        if status == "LOCKED":
+            print(f"[OK] Artifact already lock-valid: {artifact_path.relative_to(repo_root)}")
+            print(f"Workflow Profile: {workflow_profile}")
+            return 0
+
+    if issues:
+        print(f"[FAIL] Refusing to lock {artifact_path.relative_to(repo_root)}")
+        print(f"Workflow Profile: {workflow_profile}")
+        for issue in issues:
+            print(f"- {issue}")
+        return 1
+
+    locked_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    updated = set_or_insert_field(content, "Status", "LOCKED", ["Phase"])
+    updated = set_or_insert_field(updated, "LockedAt", locked_at, ["Status"])
+    provisional = set_or_insert_field(updated, "LockHash", "0" * 64, ["LockedAt", "Status"])
+    lock_hash = lock_hash_from_content(provisional)
+    final_content = set_or_insert_field(updated, "LockHash", lock_hash, ["LockedAt", "Status"])
+
+    temp_path = artifact_path.with_name(f".{artifact_path.name}.tmp")
+    temp_path.write_text(final_content, encoding="utf-8", newline="\n")
+    temp_path.replace(artifact_path)
+
+    # Write lock receipt for chain tracking.
+    if phase_rules.is_core_artifact(artifact_name):
+        phase_rules.write_receipt(run_dir, artifact_name, artifact_path)
+
+    # Report stale downstream phases so the caller knows what needs re-locking.
+    if phase_rules.is_core_artifact(artifact_name):
+        stale = phase_rules.get_stale_downstream_phases(artifact_name, run_dir)
+        if stale:
+            print(f"[WARN] The following downstream phases have stale receipts and may need re-locking:")
+            for entry in stale:
+                print(f"  - {entry['artifact']}: {entry['reason']}")
+
+    print(f"[OK] Locked {artifact_path.relative_to(repo_root)}")
+    print(f"Workflow Profile: {workflow_profile}")
+    print(f"LockedAt: {locked_at}")
+    print(f"LockHash: {lock_hash}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())