codex-workspace-bootstrap 0.4.0__tar.gz → 0.5.1__tar.gz

{codex_workspace_bootstrap-0.4.0/src/codex_workspace_bootstrap.egg-info → codex_workspace_bootstrap-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-workspace-bootstrap
-Version: 0.4.0
+Version: 0.5.1
 Summary: Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them.
 Author: kohli217
 License: MIT
@@ -30,12 +30,13 @@ Dynamic: license-file
 
 [![CI](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kohli217/codex-workspace-bootstrap/badge)](https://scorecard.dev/viewer/?uri=github.com/kohli217/codex-workspace-bootstrap)
 [![Release](https://img.shields.io/github/v/release/kohli217/codex-workspace-bootstrap)](https://github.com/kohli217/codex-workspace-bootstrap/releases/latest)
 [![PyPI](https://img.shields.io/pypi/v/codex-workspace-bootstrap)](https://pypi.org/project/codex-workspace-bootstrap/)
 [![License](https://img.shields.io/github/license/kohli217/codex-workspace-bootstrap)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
 
-**Preflight your repository before an AI coding agent touches it.**
+**Preflight your repository before an AI coding agent touches it — and catch instruction drift before different agents follow different rules.**
 
 Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.
 
@@ -58,6 +59,7 @@ State: NEEDS ATTENTION
 Project: Python
 AI instructions: none detected
 Audit: 10 passed, 4 warnings, 0 blocking
+Instruction integrity: 0 findings, 0 drift, 0 invalid commands, 0 metadata
 Next actions:
   [P1] Add repository instructions for AI coding agents -> cwb init-agents .
   [P2] Make the Codex CLI available when local Codex workflows are intended -> codex --version
@@ -70,6 +72,43 @@ cwb init-agents .
 cwb preflight .
 ```
 
+### See it catch real mistakes
+
+A reproducible demo creates a temporary repository where the project uses **pnpm** but `AGENTS.md` tells the agent to use **npm** and references a nonexistent `lint` script.
+
+```powershell
+py examples/first-run-demo/run_demo.py
+```
+
+Expected outcome:
+
+```text
+=== BEFORE ===
+State: NEEDS ATTENTION
+Findings:
+  - package-manager-mismatch
+  - missing-package-script
+
+=== AFTER ===
+State: READY
+Findings: none
+
+Demo verification: PASS
+```
+
+See [examples/first-run-demo](examples/first-run-demo) for the full reproducible demo. It uses disposable temporary Git repositories and is verified in CI.
+
+### Try it on your repository
+
+```powershell
+py -m pip install codex-workspace-bootstrap
+cwb preflight .
+```
+
+If the result is useful, noisy, or surprising, open a [Usage report](https://github.com/kohli217/codex-workspace-bootstrap/issues/new?template=usage_report.yml). Public references are optional; do not include private repository contents, credentials, or secret values.
+
+Useful feedback includes false positives, missing repository layouts, monorepo behavior, and which check saved you time.
+
 The goal is not a vanity score. The result is one of:
 
 - **READY** — core repository signals and AI instructions are present, with no blocking finding;
@@ -101,6 +140,17 @@ The preflight detects repository instruction/config signals for:
 
 It does not claim these files are correct merely because they exist. It tells you what was detected so a maintainer can review the actual instructions.
 
+### Cross-agent instruction integrity
+
+When multiple AI instruction files exist, `cwb` reads executable-looking commands and checks them against repository evidence. It understands nested `AGENTS.md` / `AGENTS.override.md`, nested Cursor `.cursor/rules`, and common path-specific frontmatter such as Copilot `applyTo` and rule `globs`. It can flag:
+
+- package-manager mismatches against `packageManager` and lockfiles;
+- cross-agent package-manager drift;
+- missing `package.json` scripts referenced by instructions;
+- conflicting test/lint/build validation commands when instruction files have no shared command for the same validation family.
+
+The lint is intentionally conservative: different files may contain additional commands without being treated as conflicts when they share a compatible validation baseline. Commands from different scopes are not compared as if they were global rules. Path-specific rules are validated individually against repository evidence but are not cross-compared for drift unless their full selector semantics can be represented safely. A repository is not marked READY when it only has nested/path-specific instructions and no repository-wide instruction baseline.
+
 ### Risk signals
 
 The audit warns about common secret-bearing filenames without printing their contents. When Git is available, it distinguishes **tracked**, **ignored**, and **untracked/unknown** candidates. Tracked risky filenames can become blocking findings in strict mode.
@@ -146,6 +196,7 @@ Write reports for automation or review:
 ```powershell
 cwb preflight . --json preflight.json
 cwb preflight . --markdown preflight.md
+cwb preflight . --sarif preflight.sarif
 ```
 
 Use strict mode when blocking findings should return a non-zero exit code:
@@ -154,6 +205,12 @@ Use strict mode when blocking findings should return a non-zero exit code:
 cwb preflight . --strict
 ```
 
+Fail CI on any instruction-integrity finding:
+
+```powershell
+cwb preflight . --fail-on-integrity
+```
+
 ### Detailed audit
 
 ```powershell
@@ -163,6 +220,20 @@ cwb audit . --sarif audit.sarif
 cwb audit . --strict
 ```
 
+### Safe fix preview
+
+```powershell
+cwb fix .
+```
+
+This is preview-only by default. To apply only low-risk supported fixes:
+
+```powershell
+cwb fix . --apply
+```
+
+Existing conflicting instruction files are never auto-rewritten. They remain human-review findings.
+
 ### Non-destructive doctor
 
 ```powershell
@@ -188,16 +259,19 @@ The reusable Action is published on GitHub Marketplace.
 - uses: actions/setup-python@v7
   with:
     python-version: "3.13"
-- uses: kohli217/codex-workspace-bootstrap@v0.4.0
+- uses: kohli217/codex-workspace-bootstrap@v0.5.1
   with:
     path: .
     strict: "true"
+    fail_on_integrity: "true"
 ```
 
-The Action adds the preflight Markdown report to the **GitHub Actions job summary**, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output can be uploaded to GitHub Code Scanning.
+The Action adds the preflight Markdown report to the **GitHub Actions job summary**, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output contains both repository-audit and instruction-integrity findings and can be uploaded to GitHub Code Scanning.
 
 See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).
 
+Read-only evaluations against real public repositories are documented in [docs/PUBLIC_REPO_EVALUATIONS.md](docs/PUBLIC_REPO_EVALUATIONS.md). They are reproducible technical evaluations, not claims of third-party adoption.
+
 ## Where it fits
 
 This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
@@ -216,6 +290,7 @@ The intent is to complement those tools, not replace them.
 - Core checks run locally.
 - Suspected secret files are not opened or printed by the filename-risk check.
 - Repository contents are not sent to a remote AI service by the core audit.
+- Instruction files are read locally for deterministic linting; extracted commands are never executed by the integrity lint.
 - Existing `AGENTS.md` files are protected unless overwrite is explicit.
 - A passing preflight is evidence about the checks performed, **not a security guarantee**.
 
@@ -248,7 +323,7 @@ py -m pip install codex-workspace-bootstrap
 Pinned GitHub release artifact:
 
 ```powershell
-py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.4.0/codex_workspace_bootstrap-0.4.0-py3-none-any.whl"
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.5.1/codex_workspace_bootstrap-0.5.1-py3-none-any.whl"
 ```
 
 ## Development

{codex_workspace_bootstrap-0.4.0 → codex_workspace_bootstrap-0.5.1}/README.md

@@ -2,12 +2,13 @@
 
 [![CI](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kohli217/codex-workspace-bootstrap/badge)](https://scorecard.dev/viewer/?uri=github.com/kohli217/codex-workspace-bootstrap)
 [![Release](https://img.shields.io/github/v/release/kohli217/codex-workspace-bootstrap)](https://github.com/kohli217/codex-workspace-bootstrap/releases/latest)
 [![PyPI](https://img.shields.io/pypi/v/codex-workspace-bootstrap)](https://pypi.org/project/codex-workspace-bootstrap/)
 [![License](https://img.shields.io/github/license/kohli217/codex-workspace-bootstrap)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
 
-**Preflight your repository before an AI coding agent touches it.**
+**Preflight your repository before an AI coding agent touches it — and catch instruction drift before different agents follow different rules.**
 
 Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.
 
@@ -30,6 +31,7 @@ State: NEEDS ATTENTION
 Project: Python
 AI instructions: none detected
 Audit: 10 passed, 4 warnings, 0 blocking
+Instruction integrity: 0 findings, 0 drift, 0 invalid commands, 0 metadata
 Next actions:
   [P1] Add repository instructions for AI coding agents -> cwb init-agents .
   [P2] Make the Codex CLI available when local Codex workflows are intended -> codex --version
@@ -42,6 +44,43 @@ cwb init-agents .
 cwb preflight .
 ```
 
+### See it catch real mistakes
+
+A reproducible demo creates a temporary repository where the project uses **pnpm** but `AGENTS.md` tells the agent to use **npm** and references a nonexistent `lint` script.
+
+```powershell
+py examples/first-run-demo/run_demo.py
+```
+
+Expected outcome:
+
+```text
+=== BEFORE ===
+State: NEEDS ATTENTION
+Findings:
+  - package-manager-mismatch
+  - missing-package-script
+
+=== AFTER ===
+State: READY
+Findings: none
+
+Demo verification: PASS
+```
+
+See [examples/first-run-demo](examples/first-run-demo) for the full reproducible demo. It uses disposable temporary Git repositories and is verified in CI.
+
+### Try it on your repository
+
+```powershell
+py -m pip install codex-workspace-bootstrap
+cwb preflight .
+```
+
+If the result is useful, noisy, or surprising, open a [Usage report](https://github.com/kohli217/codex-workspace-bootstrap/issues/new?template=usage_report.yml). Public references are optional; do not include private repository contents, credentials, or secret values.
+
+Useful feedback includes false positives, missing repository layouts, monorepo behavior, and which check saved you time.
+
 The goal is not a vanity score. The result is one of:
 
 - **READY** — core repository signals and AI instructions are present, with no blocking finding;
@@ -73,6 +112,17 @@ The preflight detects repository instruction/config signals for:
 
 It does not claim these files are correct merely because they exist. It tells you what was detected so a maintainer can review the actual instructions.
 
+### Cross-agent instruction integrity
+
+When multiple AI instruction files exist, `cwb` reads executable-looking commands and checks them against repository evidence. It understands nested `AGENTS.md` / `AGENTS.override.md`, nested Cursor `.cursor/rules`, and common path-specific frontmatter such as Copilot `applyTo` and rule `globs`. It can flag:
+
+- package-manager mismatches against `packageManager` and lockfiles;
+- cross-agent package-manager drift;
+- missing `package.json` scripts referenced by instructions;
+- conflicting test/lint/build validation commands when instruction files have no shared command for the same validation family.
+
+The lint is intentionally conservative: different files may contain additional commands without being treated as conflicts when they share a compatible validation baseline. Commands from different scopes are not compared as if they were global rules. Path-specific rules are validated individually against repository evidence but are not cross-compared for drift unless their full selector semantics can be represented safely. A repository is not marked READY when it only has nested/path-specific instructions and no repository-wide instruction baseline.
+
 ### Risk signals
 
 The audit warns about common secret-bearing filenames without printing their contents. When Git is available, it distinguishes **tracked**, **ignored**, and **untracked/unknown** candidates. Tracked risky filenames can become blocking findings in strict mode.
@@ -118,6 +168,7 @@ Write reports for automation or review:
 ```powershell
 cwb preflight . --json preflight.json
 cwb preflight . --markdown preflight.md
+cwb preflight . --sarif preflight.sarif
 ```
 
 Use strict mode when blocking findings should return a non-zero exit code:
@@ -126,6 +177,12 @@ Use strict mode when blocking findings should return a non-zero exit code:
 cwb preflight . --strict
 ```
 
+Fail CI on any instruction-integrity finding:
+
+```powershell
+cwb preflight . --fail-on-integrity
+```
+
 ### Detailed audit
 
 ```powershell
@@ -135,6 +192,20 @@ cwb audit . --sarif audit.sarif
 cwb audit . --strict
 ```
 
+### Safe fix preview
+
+```powershell
+cwb fix .
+```
+
+This is preview-only by default. To apply only low-risk supported fixes:
+
+```powershell
+cwb fix . --apply
+```
+
+Existing conflicting instruction files are never auto-rewritten. They remain human-review findings.
+
 ### Non-destructive doctor
 
 ```powershell
@@ -160,16 +231,19 @@ The reusable Action is published on GitHub Marketplace.
 - uses: actions/setup-python@v7
   with:
     python-version: "3.13"
-- uses: kohli217/codex-workspace-bootstrap@v0.4.0
+- uses: kohli217/codex-workspace-bootstrap@v0.5.1
   with:
     path: .
     strict: "true"
+    fail_on_integrity: "true"
 ```
 
-The Action adds the preflight Markdown report to the **GitHub Actions job summary**, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output can be uploaded to GitHub Code Scanning.
+The Action adds the preflight Markdown report to the **GitHub Actions job summary**, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output contains both repository-audit and instruction-integrity findings and can be uploaded to GitHub Code Scanning.
 
 See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).
 
+Read-only evaluations against real public repositories are documented in [docs/PUBLIC_REPO_EVALUATIONS.md](docs/PUBLIC_REPO_EVALUATIONS.md). They are reproducible technical evaluations, not claims of third-party adoption.
+
 ## Where it fits
 
 This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
@@ -188,6 +262,7 @@ The intent is to complement those tools, not replace them.
 - Core checks run locally.
 - Suspected secret files are not opened or printed by the filename-risk check.
 - Repository contents are not sent to a remote AI service by the core audit.
+- Instruction files are read locally for deterministic linting; extracted commands are never executed by the integrity lint.
 - Existing `AGENTS.md` files are protected unless overwrite is explicit.
 - A passing preflight is evidence about the checks performed, **not a security guarantee**.
 
@@ -220,7 +295,7 @@ py -m pip install codex-workspace-bootstrap
 Pinned GitHub release artifact:
 
 ```powershell
-py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.4.0/codex_workspace_bootstrap-0.4.0-py3-none-any.whl"
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.5.1/codex_workspace_bootstrap-0.5.1-py3-none-any.whl"
 ```
 
 ## Development

{codex_workspace_bootstrap-0.4.0 → codex_workspace_bootstrap-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-workspace-bootstrap"
-version = "0.4.0"
+version = "0.5.1"
 description = "Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them."
 readme = "README.md"
 requires-python = ">=3.10"

{codex_workspace_bootstrap-0.4.0 → codex_workspace_bootstrap-0.5.1}/src/codex_workspace_bootstrap/__init__.py

@@ -1,3 +1,3 @@
 """codex-workspace-bootstrap package."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{codex_workspace_bootstrap-0.4.0 → codex_workspace_bootstrap-0.5.1}/src/codex_workspace_bootstrap/cli.py

@@ -9,14 +9,15 @@ from . import __version__
 from .agents import generate_agents
 from .audit import audit_repository, summary
 from .doctor import doctor_findings
+from .fixes import apply_fix_plan, build_fix_plan
 from .preflight import build_preflight, render_markdown
-from .sarif import checks_to_sarif
+from .sarif import checks_to_sarif, preflight_report_to_sarif
 
 
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="codex-workspace-bootstrap",
-        description="Audit and bootstrap repositories for reliable Codex workflows.",
+        description="Preflight AI coding repositories for readiness, instruction integrity, and CI enforcement.",
     )
     parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -25,11 +26,29 @@ def _parser() -> argparse.ArgumentParser:
     preflight.add_argument("path", nargs="?", default=".")
     preflight.add_argument("--json", dest="json_path", help="Write the complete preflight report to JSON")
     preflight.add_argument("--markdown", dest="markdown_path", help="Write a concise Markdown preflight report")
+    preflight.add_argument(
+        "--sarif",
+        dest="sarif_path",
+        help="Write audit and instruction-integrity findings as SARIF 2.1.0",
+    )
     preflight.add_argument(
         "--strict",
         action="store_true",
         help="Return a non-zero exit code when blocking findings are present",
     )
+    preflight.add_argument(
+        "--fail-on-integrity",
+        action="store_true",
+        help="Return a non-zero exit code when AI instruction integrity findings are present",
+    )
+
+    fix = sub.add_parser("fix", help="Preview safe repository-readiness fixes")
+    fix.add_argument("path", nargs="?", default=".")
+    fix.add_argument(
+        "--apply",
+        action="store_true",
+        help="Apply only low-risk supported fixes; conflicting instructions are never auto-rewritten",
+    )
 
     audit = sub.add_parser("audit", help="Audit a repository and local toolchain")
     audit.add_argument("path", nargs="?", default=".")
@@ -63,7 +82,9 @@ def _run_preflight(
     path: str,
     json_path: str | None,
     markdown_path: str | None,
+    sarif_path: str | None,
     strict: bool,
+    fail_on_integrity: bool,
 ) -> int:
     root = Path(path).expanduser().resolve()
     if not root.exists() or not root.is_dir():
@@ -84,7 +105,7 @@ def _run_preflight(
     if instructions:
         print("AI instructions:")
         for item in instructions:
-            print(f"  - {item['tool']}: {item['path']}")
+            print(f"  - {item['tool']}: {item['path']} [scope={item.get('scope', '.')}]")
     else:
         print("AI instructions: none detected")
 
@@ -94,6 +115,23 @@ def _run_preflight(
         f"{totals['warnings']} warnings, {totals['blocking']} blocking"
     )
 
+    instruction_totals = report["instruction_summary"]
+    print(
+        f"Instruction integrity: {instruction_totals['findings']} findings, "
+        f"{instruction_totals['drift']} drift, "
+        f"{instruction_totals['invalid_commands']} invalid commands, "
+        f"{instruction_totals['metadata']} metadata"
+    )
+
+    findings = report["instruction_findings"]
+    if findings:
+        print("Instruction findings:")
+        for item in findings:
+            print(
+                f"  [{item['severity'].upper()}] {item['kind']}: {item['message']} "
+                f"[scope={item.get('scope', '.')}]"
+            )
+
     actions = report["next_actions"]
     if actions:
         print("Next actions:")
@@ -112,8 +150,52 @@ def _run_preflight(
         output.write_text(render_markdown(report), encoding="utf-8")
         print(f"Preflight Markdown report written to: {output}")
 
+    if sarif_path:
+        _write_json(
+            sarif_path,
+            preflight_report_to_sarif(report),
+            "Preflight SARIF report",
+        )
+
     if strict and report["state"] == "BLOCKED":
         return 1
+    if fail_on_integrity and report["instruction_summary"]["findings"]:
+        return 1
+    return 0
+
+
+def _run_fix(path: str, apply: bool) -> int:
+    root = Path(path).expanduser().resolve()
+    if not root.exists() or not root.is_dir():
+        print(f"error: repository path does not exist or is not a directory: {root}", file=sys.stderr)
+        return 2
+
+    plan = build_fix_plan(root)
+    print(f"Repository: {root}")
+    if not plan:
+        print("Fix plan: no supported fixes or instruction-integrity findings.")
+        return 0
+
+    print("Fix plan:")
+    for item in plan:
+        mode = "AUTO" if item.apply_supported else "REVIEW"
+        target = f" -> {item.target}" if item.target else ""
+        print(f"  [{mode}] {item.description}{target}")
+
+    if not apply:
+        print("Preview only. Re-run with --apply to apply low-risk supported fixes.")
+        return 0
+
+    applied = apply_fix_plan(root, plan)
+    if applied:
+        print("Applied:")
+        for path_item in applied:
+            print(f"  - {path_item}")
+    else:
+        print("No automatic changes were applied.")
+    manual = sum(not item.apply_supported for item in plan)
+    if manual:
+        print(f"{manual} finding(s) require human review and were left unchanged.")
     return 0
 
 def _run_audit(
@@ -200,7 +282,16 @@ def _run_init_agents(path: str, force: bool) -> int:
 def main(argv: list[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     if args.command == "preflight":
-        return _run_preflight(args.path, args.json_path, args.markdown_path, args.strict)
+        return _run_preflight(
+            args.path,
+            args.json_path,
+            args.markdown_path,
+            args.sarif_path,
+            args.strict,
+            args.fail_on_integrity,
+        )
+    if args.command == "fix":
+        return _run_fix(args.path, args.apply)
     if args.command == "audit":
         return _run_audit(args.path, args.json_path, args.sarif_path, args.strict)
     if args.command == "doctor":

codex_workspace_bootstrap-0.5.1/src/codex_workspace_bootstrap/fixes.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .agents import generate_agents
+from .instructions import detect_instruction_signals, lint_instructions
+
+
+@dataclass(frozen=True)
+class FixPlanItem:
+    kind: str
+    description: str
+    apply_supported: bool
+    target: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def build_fix_plan(root: Path) -> list[FixPlanItem]:
+    root = root.resolve()
+    plan: list[FixPlanItem] = []
+
+    signals = detect_instruction_signals(root)
+    findings = lint_instructions(root, signals)
+
+    has_repository_wide = any(
+        signal.scope == "." and signal.kind in {"repository", "override"}
+        for signal in signals
+    )
+    if not has_repository_wide:
+        plan.append(
+            FixPlanItem(
+                "create-agents",
+                (
+                    "Create an evidence-based AGENTS.md because no supported repository-wide "
+                    "AI instruction baseline was detected."
+                ),
+                True,
+                "AGENTS.md",
+            )
+        )
+
+    for finding in findings:
+        plan.append(
+            FixPlanItem(
+                f"manual-{finding.kind}",
+                finding.message,
+                False,
+                ", ".join(finding.files) if finding.files else None,
+            )
+        )
+
+    return plan
+
+
+def apply_fix_plan(root: Path, plan: list[FixPlanItem]) -> list[str]:
+    root = root.resolve()
+    applied: list[str] = []
+
+    for item in plan:
+        if not item.apply_supported:
+            continue
+        if item.kind == "create-agents":
+            target = root / "AGENTS.md"
+            if target.exists():
+                continue
+            target.write_text(generate_agents(root), encoding="utf-8")
+            applied.append(str(target))
+
+    return applied