Add pre-commit formatting with mdformat

Configure pre-commit with mdformat (GFM and frontmatter plugins, wrap 80, consecutive numbering enabled) to normalize Markdown files across the repository. Document setup in README_AGENTS.md.

TAG=agy

CONV=7cae30b0-e8c7-463a-89de-06542b4756ea

Change-Id: I853a05039f64786c8900ba6754aebc2baf3dd6ef

Author: nickg-ca

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.21
+    hooks:
+      - id: mdformat
+        args: ["--number", "--wrap", "80"]
+        additional_dependencies:
+          - mdformat-gfm
+          - mdformat-frontmatter

README.md

@@ -37,15 +37,15 @@ useful, it is even more important to use this in a suitably isolated environment
 to prevent impacting production systems. See the notes on unattended cloud
 deployment later in this guide.
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Architecture and Sequential Flow
 
 For a detailed breakdown of the pipeline stages, sequential flow, and
 inter-stage contracts, please refer to the
 [Agent Reference Guide](README_AGENTS.md).
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Prerequisites and Setup
 
@@ -56,23 +56,24 @@ CLI, among others. Any coding agent framework should work. We have used these
 skills successfully with both the Google ADK and Antigravity SDK. You might also
 consider:
 
-1.  **Docker** For testing containers.
-2.  **gVisor (runsc)**: For enhanced security when executing untrusted
-    AI-generated crash reproducer code, register the `runsc` runtime in your
-    Docker daemon configuration (`/etc/docker/daemon.json`):
+1. **Docker** For testing containers.
 
-    ```json
-    {
-      "runtimes": {
-        "runsc": {
-          "path": "runsc"
-        }
-      }
-    }
-    ```
+2. **gVisor (runsc)**: For enhanced security when executing untrusted
+   AI-generated crash reproducer code, register the `runsc` runtime in your
+   Docker daemon configuration (`/etc/docker/daemon.json`):
 
-3.  **Relevant Cloud SDKs**: If running remote cloud sandboxes instead of local
-    containers.
+   ```json
+   {
+     "runtimes": {
+       "runsc": {
+         "path": "runsc"
+       }
+     }
+   }
+   ```
+
+3. **Relevant Cloud SDKs**: If running remote cloud sandboxes instead of local
+   containers.
 
 ### Installing the Skills
 
@@ -87,7 +88,7 @@ To install the skills via CLI:
 npx skills add google/mantis
 ```
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Beginner's Guide & Best Practices
 
@@ -142,80 +143,80 @@ AI-based scanning will produce
 [false positives](README_AGENTS.md#understanding-false-positives-the-negative-filter-rule)
 (the review stage applies negative rules to filter them).
 
-*   **Expect Noise**: Customize the negative validation filters in
-    `/mantis-review` to match your codebase.
-*   **Iterate Small**: Start with narrow-scope scans to tune the pipeline rather
-    than running a repository-wide sweep on Day 1.
+- **Expect Noise**: Customize the negative validation filters in
+  `/mantis-review` to match your codebase.
+- **Iterate Small**: Start with narrow-scope scans to tune the pipeline rather
+  than running a repository-wide sweep on Day 1.
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Running the Pipeline (Manual Mode)
 
 You can execute the reviewing stages sequentially from **inside** your active
 CLI terminal.
 
-1.  Start your CLI from your terminal.
+1. Start your CLI from your terminal.
 
-2.  Inside the interactive UI prompt, type the skills sequentially:
+2. Inside the interactive UI prompt, type the skills sequentially:
 
-    ```text
-    # 0. (Optional) Analyze repository's version control system (VCS) history and extract past vulnerabilities
-    /mantis-history
+   ```text
+   # 0. (Optional) Analyze repository's version control system (VCS) history and extract past vulnerabilities
+   /mantis-history
 
-    # 1. (Optional) Generate mantis-summary.md directory maps
-    /mantis-summarize
+   # 1. (Optional) Generate mantis-summary.md directory maps
+   /mantis-summarize
 
-    # 2. Synthesize codebase structure and historical learnings into the Markdown Knowledge Base
-    /mantis-architecture
+   # 2. Synthesize codebase structure and historical learnings into the Markdown Knowledge Base
+   /mantis-architecture
 
-    # 3. Iteratively develop the project's living threat model based on the KB
-    /mantis-threat-model
+   # 3. Iteratively develop the project's living threat model based on the KB
+   /mantis-threat-model
 
-    # 4. Map target external boundary and build scanning roadmap, injecting KB references
-    /mantis-plan
+   # 4. Map target external boundary and build scanning roadmap, injecting KB references
+   /mantis-plan
 
-    # 5. Run multi-threaded/sequential security flaw sweep using injected context
-    /mantis-researcher
+   # 5. Run multi-threaded/sequential security flaw sweep using injected context
+   /mantis-researcher
 
-    # 6. Consolidate overlapping files and duplicate bugs
-    /mantis-dedupe
+   # 6. Consolidate overlapping files and duplicate bugs
+   /mantis-dedupe
 
-    # 7. Verify code validity & filter false positives
-    /mantis-review
+   # 7. Verify code validity & filter false positives
+   /mantis-review
 
-    # 8. Eliminate non-viable production issues
-    /mantis-critic
+   # 8. Eliminate non-viable production issues
+   /mantis-critic
 
-    # 9. Generate proof-of-concept crash reproducers and run them in sandboxes
-    /mantis-reproduce
+   # 9. Generate proof-of-concept crash reproducers and run them in sandboxes
+   /mantis-reproduce
 
-    # 10. Combine validated individual findings into multi-step exploit chains
-    /mantis-chain
+   # 10. Combine validated individual findings into multi-step exploit chains
+   /mantis-chain
 
-    # 11. Apply minimal fixes and verify they block the crash reproducer
-    /mantis-patch
+   # 11. Apply minimal fixes and verify they block the crash reproducer
+   /mantis-patch
 
-    # 12. Calculate final matrix risk ratings and append to individual findings
-    /mantis-calibrate
+   # 12. Calculate final matrix risk ratings and append to individual findings
+   /mantis-calibrate
 
-    # 13. Extract insights from execution trajectories and append to the learnings inbox
-    /mantis-reflect
+   # 13. Extract insights from execution trajectories and append to the learnings inbox
+   /mantis-reflect
 
-    # 14. Generate human-readable security review packet report
-    /mantis-report
+   # 14. Generate human-readable security review packet report
+   /mantis-report
 
-    # 15. (Manual Step) Review the report. Optionally, you can apply & commit approved patches to your codebase. To continue analysis, archive workspace/findings/, and loop back to Step 2 to start the next pass.
-    ```
+   # 15. (Manual Step) Review the report. Optionally, you can apply & commit approved patches to your codebase. To continue analysis, archive workspace/findings/, and loop back to Step 2 to start the next pass.
+   ```
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Building Deterministic Pipelines & Non-Determinism
 
 For information on how to build production-grade deterministic pipelines
 wrapping these skills, and how to manage LLM non-determinism, see the
 [Agent Reference Guide](README_AGENTS.md).
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Advanced / Unattended Cloud Deployment (GCE)
 
@@ -224,62 +225,61 @@ hardened environment to mitigate security risks (such as prompt injection). For
 the step-by-step hardened Google Compute Engine (GCE) deployment guide, see the
 [Agent Reference Guide](README_AGENTS.md#advanced--unattended-cloud-deployment-gce).
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Meta-Agent Orchestration & Evaluation
 
 For details on autonomous Meta-Agent execution and how to evaluate/optimize
 skill performance, see the [Agent Reference Guide](README_AGENTS.md).
 
---------------------------------------------------------------------------------
+______________________________________________________________________
 
 ## Roadmap / Future Work
 
-*   **Continuous Pipeline:** The current pipeline is designed to be run as a
-    point-in-time review of a codebase, and not as something that is intended to
-    regularly sync with upstream changes mid-run. It should be straightforward
-    (if a little tricky) to tweak the pipeline to better support this, but it
-    probably will not work today.
-*   **Skill Self-Improvement (Meta-Learning):** The current
-    `workspace/learnings.jsonl` and Knowledge Base (KB) architecture tracks
-    codebase-specific empirical outcomes to adapt the `THREAT_MODEL.md` and
-    context pointers. Future iterations of the pipeline could take this a step
-    further and use this historical data to reflect on and automatically rewrite
-    its own `SKILL.md` prompts. For example, if a certain type of hallucination
-    is repeatedly caught by the Critic, a self-improvement meta-agent could
-    update the Researcher's `SKILL.md` instructions to explicitly filter out
-    that specific pattern before it even reaches the Review stage. **Security
-    Note:** Committing automated changes to `SKILL.md` files must always be
-    human-gated to prevent an attacker from using prompt injection (e.g., via a
-    malicious payload in a target file) to trick the meta-agent into ignoring a
-    vulnerability class globally.
-*   **Software Dark Factory:** Integrate this pipeline into an entirely AI
-    driven software development. Instead of vulnerable discovery for action by
-    humans, Mantis would become the autonomous vulnerability research and
-    release gating component of the dark factory. Before the dark factory can
-    push to production, it must have had N hours of adversarial vulnerability
-    research or "red teaming" by a pipeline like Mantis.
-
---------------------------------------------------------------------------------
+- **Continuous Pipeline:** The current pipeline is designed to be run as a
+  point-in-time review of a codebase, and not as something that is intended to
+  regularly sync with upstream changes mid-run. It should be straightforward (if
+  a little tricky) to tweak the pipeline to better support this, but it probably
+  will not work today.
+- **Skill Self-Improvement (Meta-Learning):** The current
+  `workspace/learnings.jsonl` and Knowledge Base (KB) architecture tracks
+  codebase-specific empirical outcomes to adapt the `THREAT_MODEL.md` and
+  context pointers. Future iterations of the pipeline could take this a step
+  further and use this historical data to reflect on and automatically rewrite
+  its own `SKILL.md` prompts. For example, if a certain type of hallucination is
+  repeatedly caught by the Critic, a self-improvement meta-agent could update
+  the Researcher's `SKILL.md` instructions to explicitly filter out that
+  specific pattern before it even reaches the Review stage. **Security Note:**
+  Committing automated changes to `SKILL.md` files must always be human-gated to
+  prevent an attacker from using prompt injection (e.g., via a malicious payload
+  in a target file) to trick the meta-agent into ignoring a vulnerability class
+  globally.
+- **Software Dark Factory:** Integrate this pipeline into an entirely AI driven
+  software development. Instead of vulnerable discovery for action by humans,
+  Mantis would become the autonomous vulnerability research and release gating
+  component of the dark factory. Before the dark factory can push to production,
+  it must have had N hours of adversarial vulnerability research or "red
+  teaming" by a pipeline like Mantis.
+
+______________________________________________________________________
 
 ## Troubleshooting Guide
 
 ### 1. Loop Iterations are Re-Evaluating the Same Code
 
-*   **Symptom:** The loop keeps reviewing the same files and reporting identical
-    bugs.
-*   **Solution:** Ensure `/mantis-architecture` completes successfully and
-    writes its synthesized knowledge to the `workspace/kb/` directory. The
-    `/mantis-plan` strategist checks this Knowledge Base to dynamically skip
-    already analyzed areas. Check that file permissions allow writing to
-    `workspace/kb/`.
+- **Symptom:** The loop keeps reviewing the same files and reporting identical
+  bugs.
+- **Solution:** Ensure `/mantis-architecture` completes successfully and writes
+  its synthesized knowledge to the `workspace/kb/` directory. The `/mantis-plan`
+  strategist checks this Knowledge Base to dynamically skip already analyzed
+  areas. Check that file permissions allow writing to `workspace/kb/`.
 
 ### 2. Other Issues
 
-*   **Symptom:** Something isn't working.
-*   **Solution:** Ask an AI coding tool to review your pipeline and the
-    conversations or trajectories that are leading to the unexpected behavior.
-    They will often give you useful insights.
+- **Symptom:** Something isn't working.
+- **Solution:** Ask an AI coding tool to review your pipeline and the
+  conversations or trajectories that are leading to the unexpected behavior.
+  They will often give you useful insights.
 
 This is not an officially supported Google product. This project is not eligible
 for the