docs: add PMM transformation rules as operational rulebook

[konard]

Summary

Adds one new canonical top-level document — docs/pmm_transformation_rules.md — that fixes the operational rules for transforming PMM and makes controlled development the default mode of work.

The document is intentionally short and normative: it complements pmm_target_model.md without restating it, and it gives subsequent issues, PRs, reviews, and future repo-guard policy a single place to cite.

Fixes #277

Change Contract

change_type: governance/repo-guard
scope:
  - docs/pmm_transformation_rules.md
  - docs/index.md
budgets:
  max_new_files: 1
  max_new_docs: 1
  max_net_added_lines: 220
must_touch:
  - docs/pmm_transformation_rules.md
must_not_touch:
  - include/
  - tests/
  - single_include/
  - scripts/
  - .github/
  - repo-policy.json
  - README.md
expected_effects:
  - Introduces a normative operational rulebook for PMM transformation
  - Surfaces the new document from the canonical docs index
  - Does not change code, tests, scripts, generated surface, or governance files

Surface delta

• New files: 1 (docs/pmm_transformation_rules.md)
• Modified files: 1 (docs/index.md — one index row)
• Net added lines: 111 (110 new doc + 1 index row), well under the 220-line budget
• Docs delta: +1 canonical document, +1 index row
• Comments delta: none
• Code delta: none
• Generated surface: untouched (single_include/** not modified)
• Touched forbidden scope: none
• README.md: untouched

Document sections

Per the issue contract, docs/pmm_transformation_rules.md contains exactly the required rules:

1. Allowed issue types — kernel-hardening, kernel-compaction, extraction-prep, governance/repo-guard, docs-comments-cleanup
2. Atomic issue rule — one issue = one intent, one PR = one reason
3. No mixed PR rule — kernel-hardening, docs cleanup, packaging, generated updates, and governance must not be combined
4. Extraction-first rule — non-substrate capabilities stay outside PMM or are prepared for extraction, never absorbed
5. Surface compression rule — non-positive surface delta by default; growth only as declared surface debt
6. Source/generated separation rule — single_include/** regenerations stay isolated from kernel/governance PRs
7. Text discipline rule — every new doc has a canonical place and clear purpose; no process-noise accumulation
8. PR review semantics — contract conformance is assessed above local code quality

Verification

• Exactly one new file under docs/ (scope respected)
• No changes to include/, tests/, single_include/, scripts/, .github/, repo-policy.json, or README.md
• Net added lines within the 220-line surface budget (111)
• Document remains short and structural — not an architectural essay (≈ 110 lines)
• Does not duplicate pmm_target_model.md; adds only operational rules
• Introduces allowed issue types explicitly
• Introduces atomic issue / no-mixed-PR / extraction-first / surface-compression rules
• No new markdown files other than docs/pmm_transformation_rules.md
• Generated surface not touched

Governance notes

Following the precedent from #276, this PR does not bump the README.md version badge. The README is release-owned surface and out of scope per the issue contract; the 0.55.x drift between CMakeLists.txt and README.md on main is a pre-existing concern for a separate governance PR.

No changelog fragment is added: scripts/check-changelog-fragment.sh exempts docs-only PRs, and the issue explicitly forbids changes outside docs/pmm_transformation_rules.md and a minimal docs index entry.

repo-policy.json is deliberately not updated — the issue places it in the forbidden scope. Promoting the new document into canonical_docs can happen in a follow-up governance PR.

Test plan

• File count matches contract (1 new doc, 1 index line)
• Byte-level diff stays within docs/ only
• Local git diff --stat matches declared surface delta
• CI: docs-consistency, repo-guard advisory, build/test workflows pass on the PR

🤖 Generated with Claude Code

[konard]

Solution summary

PR #280 is ready for review with all checks passing: #280

What shipped:

• New canonical doc docs/pmm_transformation_rules.md (110 lines) — 8 operational rules from the issue: allowed issue types, atomic issue, no mixed PR, extraction-first, surface compression, source/generated separation, text discipline, PR review semantics.
• One index row added to docs/index.md.
• Net +111 lines (under the 220 budget); no code, test, script, generated, or governance-file changes.

CI: Docs consistency ✓, Version consistency ✓, repo-guard advisory ✓.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $1.100235

📊 Context and tokens usage:

Claude Opus 4.7:

• 58.9K / 1M (6%) input tokens, 8.6K / 128K (7%) output tokens

Total: (56.4K + 1.1M cached) input tokens, 8.6K output tokens, $1.099614 cost

Claude Haiku 4.5:

• 21 / 64K (0%) output tokens

Total: 516 input tokens, 21 output tokens, $0.000621 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Main model: Claude Opus 4.7 (claude-opus-4-7)
• Additional models:
  • Claude Haiku 4.5 (claude-haiku-4-5-20251001)

📎 Log file uploaded as Gist (694KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag