[AMEND] Implement LAWS.md v2.0 — Constitutional Document with NASA-grade Protection, CI Gates & Nine Kingdoms Invariants

[gHashTag]

⚖️ [AMEND] LAWS.md v2.0 — Constitutional Document with NASA-grade Protection

"Every agent is a temporary citizen with bounded authority. Every task has a contract. Every mutation leaves evidence. Every victory must improve the long-term health of the realm."

---

🎯 Goal

Upgrade LAWS.md from an informal markdown document to a constitutionally protected, machine-validated, NASA NPR 7150.2D-compliant supreme law document for the trios repository.

The new v2.0 introduces:

• Immutability infrastructure (CODEOWNERS + branch protection + CI gate)
• Full Nine Kingdoms Invariants (I1–I9) with testable CI gates
• NASA-standard issue schema, heartbeat protocol, and PHI LOOP+
• Amendment process requiring human approval + LAWS_HASH verification
• laws-guard.yml CI workflow that enforces all core laws on every push/PR

---

🚫 Non-Goals

• This is NOT a refactor of existing Rust code
• This is NOT a change to agent runtime logic
• This does NOT touch CLAUDE.md, AGENTS.md, or TASK.md content (only adds references to hierarchy)
• This does NOT introduce new features — only governance infrastructure

---

📋 Acceptance Criteria

- [ ] LAWS.md v2.0 exists at repository root with LAWS_SCHEMA_VERSION: 2.0
- [ ] § 0 SUPREMACY CLAUSE present with immutability table
- [ ] § 1 Constitutional Hierarchy (rank 1–8 files) present
- [ ] § 2 Required Repository Layout matches actual repo structure
- [ ] § 3 Core Laws L1–L20 present with CI gate descriptions
- [ ] § 4 Nine Kingdoms Invariants I1–I9 with testable gates
- [ ] § 5 Issue Standards: YAML schema + taxonomy + lifecycle + comment types
- [ ] § 6 Heartbeat Protocol: canonical format with loop: field
- [ ] § 7 PHI LOOP+ steps documented (CLAIM→PUSH)
- [ ] § 8 Amendment Process: 6-step procedure
- [ ] § 9 Agent Personhood: soul-name rules
- [ ] § 10 Priority Matrix: P0–P3 with current open issues
- [ ] § 11 Law Status Dashboard: all L1–L20 with current status
- [ ] § 12 Closing Clause present
- [ ] .github/workflows/laws-guard.yml created and passing
- [ ] .github/CODEOWNERS updated: LAWS.md @gHashTag
- [ ] .github/ISSUE_TEMPLATE/task_contract.yml created
- [ ] .github/ISSUE_TEMPLATE/constitutional_amendment.yml created
- [ ] .trinity/state/LAWS_HASH file created with SHA256 of new LAWS.md
- [ ] cargo clippy = 0 warnings (no Rust changes, trivially passes)
- [ ] laws-guard CI job passes on main
- [ ] Evidence written to .trinity/experience/laws-v2-amendment.md

---

🏗️ Implementation Plan

Step 1 — Write LAWS.md v2.0

Replace current LAWS.md with the full v2.0 document containing all 12 sections.

Key structural upgrades vs v1:

Section	v1	v2.0
Supremacy	Implicit	§ 0 explicit + immutability table
Invariants	Listed inline	§ 4 Nine Kingdoms I1–I9 with CI gates
Issue standards	None	§ 5 full YAML schema + NASA taxonomy
Heartbeat	Minimal	§ 6 with loop: + evidence: fields
PHI LOOP	CLAIM→PUSH	§ 7 full 11-step protocol
Amendment	None	§ 8 6-step process + LAWS_HASH
Agent personhood	Implicit	§ 9 soul-name rules + examples
Priority matrix	None	§ 10 P0–P3 with linked issues
Law dashboard	None	§ 11 L1–L20 status table

---

Step 2 — Create laws-guard.yml

# .github/workflows/laws-guard.yml
name: laws-guard
on: [push, pull_request]

jobs:
  validate-laws:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: LAWS.md must exist
        run: test -f LAWS.md || (echo "CONSTITUTIONAL BREACH: LAWS.md missing" && exit 1)

      - name: LAWS.md must have supremacy clause
        run: grep -q "SUPREMACY CLAUSE" LAWS.md || (echo "BREACH: § 0 missing" && exit 1)

      - name: LAWS.md must have schema version
        run: grep -q "LAWS_SCHEMA_VERSION" LAWS.md || (echo "BREACH: schema version missing" && exit 1)

      - name: No .sh files (L1)
        run: |
          COUNT=$(find . -name "*.sh" | grep -v node_modules | grep -v ".git" | wc -l)
          test "$COUNT" -eq 0 || (echo "L1 VIOLATION: $COUNT shell scripts found" && exit 1)

      - name: PR must close an issue (L2)
        if: github.event_name == 'pull_request'
        run: |
          echo "${{ github.event.pull_request.body }}" | \
          grep -iE "(Closes|Fixes|Resolves) #[0-9]+" || \
          (echo "L2 VIOLATION: No 'Closes #N' in PR body" && exit 1)

      - name: No /extension root directory (I5)
        run: test ! -d ./extension || (echo "I5 VIOLATION: /extension root exists" && exit 1)

---

Step 3 — CODEOWNERS

# .github/CODEOWNERS
# LAWS.md — supreme constitutional document
# Any change requires human maintainer approval
LAWS.md @gHashTag

---

Step 4 — Issue Templates

Create .github/ISSUE_TEMPLATE/task_contract.yml:

name: Task Contract
description: Standard task issue following LAWS.md § 5 schema
title: "[TYPE] Short imperative title (≤72 chars)"
labels: ["needs-triage"]
body:
  - type: dropdown
    id: classification
    attributes:
      label: Classification
      options: [P0-CRITICAL, P1-HIGH, P2-MEDIUM, P3-LONG-TERM]
    validations:
      required: true

  - type: dropdown
    id: kingdom
    attributes:
      label: Kingdom (domain)
      options: [Rust, Test, Lint, Network, Structure, Surface, Security, Protocol, Identity, Cross-kingdom]
    validations:
      required: true

  - type: textarea
    id: goal
    attributes:
      label: Goal (what success looks like)
    validations:
      required: true

  - type: textarea
    id: non_goals
    attributes:
      label: Non-goals (explicit scope boundary)
    validations:
      required: true

  - type: textarea
    id: acceptance_criteria
    attributes:
      label: Acceptance criteria (testable, verifiable)
      placeholder: "- [ ] cargo clippy = 0\n- [ ] test X passes\n- [ ] evidence in .trinity/experience/"
    validations:
      required: true

  - type: textarea
    id: evidence_required
    attributes:
      label: Evidence to produce
    validations:
      required: true

  - type: input
    id: closes
    attributes:
      label: Closes / Blocks / Relates to
      placeholder: "Closes #N, Blocks #M"

  - type: input
    id: deadline
    attributes:
      label: Deadline (ISO 8601 or milestone)

Create .github/ISSUE_TEMPLATE/constitutional_amendment.yml:

name: Constitutional Amendment
description: Propose a change to LAWS.md per § 8 procedure
title: "[AMEND] ..."
labels: ["constitutional-amendment"]
body:
  - type: textarea
    id: rationale
    attributes:
      label: Rationale
      description: Why this amendment is needed
    validations:
      required: true

  - type: textarea
    id: affected_laws
    attributes:
      label: Affected laws / sections
    validations:
      required: true

  - type: textarea
    id: migration
    attributes:
      label: Migration notes
      description: What breaks, what agents need to know
    validations:
      required: true

  - type: textarea
    id: risk
    attributes:
      label: Risk statement
    validations:
      required: true

---

Step 5 — LAWS_HASH

After writing the final LAWS.md:

mkdir -p .trinity/state
sha256sum LAWS.md > .trinity/state/LAWS_HASH

---

Step 6 — Experience Record

Write .trinity/experience/laws-v2-amendment.md documenting:

• What was changed
• Why NASA NPR 7150.2D was chosen as the standard
• Lessons from v1 gaps (no CI gate, no CODEOWNERS, no schema)
• How to verify the amendment is working

---

🔒 Protection Mechanism Summary

Mechanism	Enforcement	Location
CODEOWNERS	Human review required on every PR touching LAWS.md	.github/CODEOWNERS
Branch protection on main	No force-push, no deletion	GitHub repo settings (manual)
CI gate validate-laws	File exists + schema valid on every push	.github/workflows/laws-guard.yml
LAWS_HASH	Detects silent mutation, checked on PHI LOOP SEAL step	.trinity/state/LAWS_HASH

---

📐 Nine Kingdoms Invariants (full table)

Invariant	Kingdom	Rule	CI Gate
I1	Rust Kingdom	cargo build exits 0	cargo build --all
I2	Test Kingdom	No merge with failing tests	cargo test --all
I3	Lint Kingdom	clippy 0 warnings	cargo clippy --all-targets
I4	Network Kingdom	No raw WebSocket bypass	grep WebSocket in non-approved paths
I5	Structure Kingdom	No /extension root	test ! -d ./extension
I6	Surface Kingdom	Zero handwritten JS outside bootstrap	surface linter
I7	Security Kingdom	wasm-unsafe-eval declared only	manifest check
I8	Protocol Kingdom	All external calls use Accept: application/json	grep check
I9	Identity Kingdom	Exactly one #[wasm_bindgen(start)] per WASM module	symbol check

---

📄 Evidence Required

• Link to PR with LAWS.md v2.0 diff
• CI laws-guard run passing (green)
• .trinity/state/LAWS_HASH committed
• .trinity/experience/laws-v2-amendment.md committed
• CODEOWNERS diff showing LAWS.md @gHashTag

---

🔗 References

• NASA NPR 7150.2D Software Engineering Requirements
• NASA Flight Rules (crew status reporting → Heartbeat Protocol)
• GitHub CODEOWNERS documentation
• Existing: CLAUDE.md, AGENTS.md, issue 🎯 IGLA RACE — Distributed Hunt: JEPA-T + NCA + GF16 + ASHA + Coq Invariants (Rust-only, Never-Stopping) #143 (eternal board)

---

Priority

P1-HIGH — constitutional infrastructure. Without this, all other laws are unenforceable suggestions.

Kingdom: Cross-kingdom (affects all 9 kingdoms)

Deadline: Before next agent deployment wave

---