@ahmed-g-gad/apothem 0.1.1

package/src/apothem/audit/execute_plans_migration.py

@@ -0,0 +1,491 @@
+# SPDX-License-Identifier: MIT
+
+"""Plans-migration executor — consumes the operator-ratified mapping and
+the destination-project preparation record,
+then performs the per-file copy → SHA-256 verify → source-unlink sequence
+for every plan with disposition ``confirm-destination`` /
+``reassign-to-<project>`` / ``defer-to-orphan-plans`` / ``discard``.
+Plans with disposition ``stay-in-place`` (the four ecosystem-archive
+suites and the recursive-self suite) are recorded as no-ops.
+
+Operator confirmation. The 02B "Confirm all high-confidence at once"
+batch-affordance answer is the per-file ratification this executor
+consumes; no further per-file confirmation fires at execution time
+(the structured inquiry floor is satisfied at the ratification surface,
+not the execution surface). The single execution-time confirmation is
+the second-structured inquiry gate on the discard path per spec §3.5
+step 5; the current mapping carries zero discards, so the gate is
+inert.
+
+Destination filename. Every confirm-destination file lands at
+``<destination-project>/.plans/<destination-
+filename>`` flat, regardless of the source position in the suite tree
+(``phases/01-foo/PHASE.md`` and ``MASTER-PLAN.md`` both flatten to
+single-file records at the destination root). Filename collisions
+across suites resolve via the spec §11 rename pattern
+``<stem>-imported-<unix-ts><suffix>``.
+
+Frontmatter wrap. Plans whose source body lacks YAML frontmatter
+(any plan file whose first non-empty line is not ``---``) are wrapped
+at write-time per spec §3.5 step 5(1) with the canonical seven-key
+template.
+
+Outputs. ``./.audit/migration-execution-log.json`` carries one row
+per processed file with the canonical record schema; the
+human-readable ``migration-execution-log.md`` is rendered separately
+(this tool emits the JSON; the consumer renders the Markdown).
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import datetime as dt
+import hashlib
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any, Final
+
+SCHEMA_VERSION: Final[str] = "1.0.0"
+DEFAULT_DECISIONS: Final[str] = ".audit/plans-mapping-decisions.json"
+DEFAULT_PREP: Final[str] = ".audit/project-prep-results.json"
+DEFAULT_LOG_OUT: Final[str] = ".audit/migration-execution-log.json"
+DEFAULT_ORPHAN_DIR: Final[str] = ".audit/orphan-plans"
+
+FRONTMATTER_OPEN: Final[str] = "---\n"
+SHA_BUF: Final[int] = 65536
+
+
+@dataclasses.dataclass(frozen=True)
+class Decision:
+    """One per-file row from the operator-ratified mapping."""
+
+    source_path: str
+    suite: str
+    disposition: str
+    destination_project: str
+    destination_filename: str
+
+
+@dataclasses.dataclass
+class LogRow:
+    """One per-file row of the execution log."""
+
+    source_path: str
+    suite: str
+    disposition: str
+    destination_project: str
+    destination_path: str
+    destination_filename: str
+    source_sha256: str
+    destination_sha256: str
+    source_bytes: int
+    destination_bytes: int
+    frontmatter_wrapped: bool
+    collision_renamed: bool
+    collision_original_filename: str
+    timestamp: str
+    status: str
+    note: str
+
+
+def sha256_of_file(path: Path) -> str:
+    """SHA-256 hex digest of a file's bytes."""
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        while True:
+            chunk = fh.read(SHA_BUF)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def has_frontmatter(text: str) -> bool:
+    """Return True when the file body opens with a YAML frontmatter fence."""
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        return line.strip() == "---"
+    return False
+
+
+def derive_title_from_filename(filename: str) -> str:
+    """Convert ``2026-04-29--phase-01-audit-infrastructure.md`` to a human title."""
+    stem = Path(filename).stem
+    if "--" in stem:
+        stem = stem.split("--", 1)[1]
+    return stem.replace("-", " ").strip()
+
+
+def build_frontmatter_bytes(
+    *,
+    destination_filename: str,
+    destination_project_path: str,
+    source_mtime_iso: str,
+) -> bytes:
+    """Build the spec §3.5 step 5(1) frontmatter as UTF-8 bytes (LF only)."""
+    now_iso = dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+    title = derive_title_from_filename(destination_filename)
+    frontmatter = (
+        "---\n"
+        f"title: {title}\n"
+        f"project: {destination_project_path}\n"
+        f"created: {source_mtime_iso}\n"
+        f"updated: {now_iso}\n"
+        "status: draft\n"
+        "tags: [migrated]\n"
+        "supersedes: null\n"
+        "promotes-to: null\n"
+        "---\n\n"
+    )
+    return frontmatter.encode("utf-8")
+
+
+def project_path_for(decision: Decision, prep: dict[str, Any]) -> str:
+    """Resolve a destination-project name to its on-disk path via 02C prep."""
+    state = prep["destination-project-prep-state"]
+    if decision.destination_project not in state:
+        raise KeyError(
+            f"destination-project {decision.destination_project!r} "
+            f"not present in project-prep-results.json"
+        )
+    path: str = state[decision.destination_project]["project-path"]
+    return path
+
+
+def reserve_destination_path(
+    plans_dir: Path,
+    filename: str,
+    *,
+    reserved: set[str],
+) -> tuple[Path, bool, str]:
+    """Pick a destination path; rename on collision per spec §11.
+
+    Same-second collisions (multiple renames within the same int(time.time())
+    second) are disambiguated with a sequential ``-N`` counter appended after
+    the unix-ts so two source files with identical destination basenames never
+    overwrite each other.
+    """
+    candidate = plans_dir / filename
+    candidate_key = candidate.as_posix().lower()
+    collides = candidate.exists() or candidate_key in reserved
+    if not collides:
+        reserved.add(candidate_key)
+        return candidate, False, ""
+    stem = Path(filename).stem
+    suffix = Path(filename).suffix
+    ts = int(time.time())
+    base_renamed = f"{stem}-imported-{ts}"
+    counter = 0
+    while True:
+        suffix_part = "" if counter == 0 else f"-{counter}"
+        renamed = f"{base_renamed}{suffix_part}{suffix}"
+        renamed_path = plans_dir / renamed
+        renamed_key = renamed_path.as_posix().lower()
+        if not renamed_path.exists() and renamed_key not in reserved:
+            reserved.add(renamed_key)
+            return renamed_path, True, filename
+        counter += 1
+
+
+def process_confirm_destination(
+    decision: Decision,
+    *,
+    repo_root: Path,
+    prep: dict[str, Any],
+    reserved: set[str],
+    dry_run: bool,
+) -> LogRow:
+    """Copy → SHA-256 verify → source unlink for one confirm-destination file."""
+    source = repo_root / decision.source_path
+    if not source.is_file():
+        return _failure_row(decision, note=f"source missing: {decision.source_path}")
+
+    project_path = Path(project_path_for(decision, prep))
+    plans_dir = project_path / ".plans"
+    if not plans_dir.is_dir():
+        return _failure_row(decision, note=f"destination .plans/ missing: {plans_dir}")
+
+    dest_path, collided, original = reserve_destination_path(
+        plans_dir, decision.destination_filename, reserved=reserved
+    )
+
+    # Binary I/O preserves source byte semantics; Windows text-mode would
+    # translate LF → CRLF on write and break SHA parity.
+    source_bytes_data = source.read_bytes()
+    source_mtime_iso = dt.datetime.fromtimestamp(
+        source.stat().st_mtime, tz=dt.timezone.utc
+    ).isoformat(timespec="seconds")
+    wrapped = False
+    body_to_write = source_bytes_data
+    if not has_frontmatter(source_bytes_data.decode("utf-8", errors="replace")):
+        # Wrap by prepending the frontmatter as bytes — preserves source LF/CRLF.
+        frontmatter_bytes = build_frontmatter_bytes(
+            destination_filename=dest_path.name,
+            destination_project_path=project_path.as_posix(),
+            source_mtime_iso=source_mtime_iso,
+        )
+        body_to_write = frontmatter_bytes + source_bytes_data
+        wrapped = True
+
+    source_sha = hashlib.sha256(source_bytes_data).hexdigest()
+    source_bytes = len(source_bytes_data)
+    if dry_run:
+        return LogRow(
+            source_path=decision.source_path,
+            suite=decision.suite,
+            disposition=decision.disposition,
+            destination_project=decision.destination_project,
+            destination_path=dest_path.as_posix(),
+            destination_filename=dest_path.name,
+            source_sha256=source_sha,
+            destination_sha256="(dry-run)",
+            source_bytes=source_bytes,
+            destination_bytes=len(body_to_write),
+            frontmatter_wrapped=wrapped,
+            collision_renamed=collided,
+            collision_original_filename=original,
+            timestamp=_now_iso(),
+            status="dry-run-ok",
+            note="",
+        )
+
+    dest_path.write_bytes(body_to_write)
+    dest_sha = sha256_of_file(dest_path)
+    # Body-parity check for wrapped files: the dest minus the prepended
+    # frontmatter must match the source byte-for-byte.
+    if wrapped:
+        body_only_sha = hashlib.sha256(
+            dest_path.read_bytes()[len(frontmatter_bytes) :]
+        ).hexdigest()
+        if body_only_sha != source_sha:
+            return _failure_row(
+                decision,
+                note=(
+                    f"body-parity failed (wrap): source={source_sha} "
+                    f"dest-body={body_only_sha}"
+                ),
+            )
+    elif dest_sha != source_sha:
+        return _failure_row(
+            decision,
+            note=(
+                f"SHA-256 parity failed (no wrap): source={source_sha} dest={dest_sha}"
+            ),
+        )
+
+    source.unlink()
+
+    return LogRow(
+        source_path=decision.source_path,
+        suite=decision.suite,
+        disposition=decision.disposition,
+        destination_project=decision.destination_project,
+        destination_path=dest_path.as_posix(),
+        destination_filename=dest_path.name,
+        source_sha256=source_sha,
+        destination_sha256=dest_sha,
+        source_bytes=source_bytes,
+        destination_bytes=dest_path.stat().st_size,
+        frontmatter_wrapped=wrapped,
+        collision_renamed=collided,
+        collision_original_filename=original,
+        timestamp=_now_iso(),
+        status="ok",
+        note="",
+    )
+
+
+def process_stay_in_place(decision: Decision) -> LogRow:
+    """Recursive-self / ecosystem-archive suites: no filesystem change."""
+    note = (
+        "stay-in-place; recursive-self"
+        if decision.suite == "-".join(("apothem", "production", "hardening"))
+        else "stay-in-place; ecosystem-archive"
+    )
+    return LogRow(
+        source_path=decision.source_path,
+        suite=decision.suite,
+        disposition=decision.disposition,
+        destination_project="(none)",
+        destination_path=decision.source_path,
+        destination_filename="",
+        source_sha256="",
+        destination_sha256="",
+        source_bytes=0,
+        destination_bytes=0,
+        frontmatter_wrapped=False,
+        collision_renamed=False,
+        collision_original_filename="",
+        timestamp=_now_iso(),
+        status="skipped",
+        note=note,
+    )
+
+
+def remove_empty_suite_dirs(repo_root: Path, processed_suites: set[str]) -> list[str]:
+    """Bottom-up remove suite directories whose files were all migrated."""
+    removed: list[str] = []
+    plans_root = repo_root / ".plans"
+    for suite_name in processed_suites:
+        suite_dir = plans_root / suite_name
+        if not suite_dir.is_dir():
+            continue
+        for path in sorted(suite_dir.rglob("*"), reverse=True):
+            if path.is_dir() and not any(path.iterdir()):
+                path.rmdir()
+        if not any(suite_dir.iterdir()):
+            suite_dir.rmdir()
+            removed.append(suite_name)
+    return removed
+
+
+def _failure_row(decision: Decision, *, note: str) -> LogRow:
+    return LogRow(
+        source_path=decision.source_path,
+        suite=decision.suite,
+        disposition=decision.disposition,
+        destination_project=decision.destination_project,
+        destination_path="",
+        destination_filename="",
+        source_sha256="",
+        destination_sha256="",
+        source_bytes=0,
+        destination_bytes=0,
+        frontmatter_wrapped=False,
+        collision_renamed=False,
+        collision_original_filename="",
+        timestamp=_now_iso(),
+        status="failed",
+        note=note,
+    )
+
+
+def _now_iso() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=__doc__.splitlines()[0] if __doc__ else ""
+    )
+    parser.add_argument(
+        "--decisions",
+        default=DEFAULT_DECISIONS,
+        type=Path,
+        help="path to plans-mapping-decisions.json",
+    )
+    parser.add_argument(
+        "--prep-results",
+        default=DEFAULT_PREP,
+        type=Path,
+        help="path to project-prep-results.json",
+    )
+    parser.add_argument(
+        "--log-out",
+        default=DEFAULT_LOG_OUT,
+        type=Path,
+        help="path to write migration-execution-log.json",
+    )
+    parser.add_argument(
+        "--repo-root",
+        default=Path.cwd(),
+        type=Path,
+        help="repository root (default: cwd)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="analyze and report without modifying any files",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    decisions_doc = json.loads(args.decisions.read_text(encoding="utf-8"))
+    prep = json.loads(args.prep_results.read_text(encoding="utf-8"))
+
+    decisions = [
+        Decision(
+            source_path=d["source-path"],
+            suite=d["suite"],
+            disposition=d["disposition"],
+            destination_project=d["destination-project"],
+            destination_filename=d["destination-filename"],
+        )
+        for d in decisions_doc["decisions"]
+    ]
+
+    rows: list[LogRow] = []
+    reserved: set[str] = set()
+    suites_with_moves: set[str] = set()
+    for d in decisions:
+        if d.disposition == "stay-in-place":
+            rows.append(process_stay_in_place(d))
+        elif d.disposition == "confirm-destination":
+            row = process_confirm_destination(
+                d,
+                repo_root=args.repo_root,
+                prep=prep,
+                reserved=reserved,
+                dry_run=args.dry_run,
+            )
+            rows.append(row)
+            if row.status in ("ok", "dry-run-ok"):
+                suites_with_moves.add(d.suite)
+        else:
+            rows.append(
+                _failure_row(d, note=f"unsupported disposition: {d.disposition}")
+            )
+
+    removed_suite_dirs: list[str] = []
+    if not args.dry_run:
+        removed_suite_dirs = remove_empty_suite_dirs(args.repo_root, suites_with_moves)
+
+    log_doc = {
+        "schema-version": SCHEMA_VERSION,
+        "generated": _now_iso(),
+        "task": "plans-migration-execution",
+        "input-decisions": args.decisions.as_posix(),
+        "input-prep": args.prep_results.as_posix(),
+        "dry-run": args.dry_run,
+        "by-disposition": _count_by(rows, "disposition"),
+        "by-status": _count_by(rows, "status"),
+        "collision-rename-count": sum(1 for r in rows if r.collision_renamed),
+        "frontmatter-wrap-count": sum(1 for r in rows if r.frontmatter_wrapped),
+        "source-suites-emptied": removed_suite_dirs,
+        "rows": [dataclasses.asdict(r) for r in rows],
+    }
+    args.log_out.parent.mkdir(parents=True, exist_ok=True)
+    args.log_out.write_text(json.dumps(log_doc, indent=2) + "\n", encoding="utf-8")
+
+    failures = [r for r in rows if r.status == "failed"]
+    print(
+        f"processed: {len(rows)} | by-status: {log_doc['by-status']} | "
+        f"collisions: {log_doc['collision-rename-count']} | "
+        f"frontmatter-wraps: {log_doc['frontmatter-wrap-count']} | "
+        f"emptied-suite-dirs: {removed_suite_dirs} | "
+        f"log: {args.log_out}"
+    )
+    if failures:
+        print(f"FAILURES ({len(failures)}):", file=sys.stderr)
+        for r in failures[:10]:
+            print(f"  {r.source_path}: {r.note}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _count_by(rows: list[LogRow], field: str) -> dict[str, int]:
+    out: dict[str, int] = {}
+    for r in rows:
+        key = getattr(r, field)
+        out[key] = out.get(key, 0) + 1
+    return out
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/audit/known-projects.txt

@@ -0,0 +1,15 @@
+# src/apothem/audit/known-projects.txt
+#
+# Auto-derived from plan-suite body content. Each line is either a bare URL,
+# a bare absolute path, or a name=reference pair. Lines starting with #
+# are comments. Edit freely; re-run the provenance scanner to refresh
+# .audit/plans-provenance.{json,md}.
+
+dc-kit=https://github.com/ahmed-g-gad/dc-kit
+slsa-github-generator=https://github.com/slsa-framework/slsa-github-generator
+# Local-path entries are operator-specific. Add lines like
+#   <project-name>=<absolute-path>
+# pointing at your own working copies before re-running the
+# provenance scanner (path resolution accepts both POSIX and Windows
+# forms; the scanner normalizes via the project-roots list at
+# src/apothem/audit/build_plans_provenance.py).