Contract System v2: core contracts, enforcement, and CI gates

.evidence/README.md

@@ -0,0 +1,10 @@
+# Evidence Directory
+
+Use this directory when a task requires a repository-tracked evidence packet.
+
+Recommended file:
+
+- `.evidence/EVIDENCE_PACKET.md` (copied from `templates/EVIDENCE_PACKET_TEMPLATE.md`)
+
+For pull requests, evidence may also be provided directly in PR body using
+`.github/pull_request_template.md`.

.github/pull_request_template.md

@@ -0,0 +1,79 @@
+## Objective
+
+- Problem solved:
+- Intended outcome:
+
+## Risk Tier
+
+- Tier: `0 | 1 | 2 | 3`
+- Rationale:
+
+## Scope
+
+- Files/components changed:
+- Explicit exclusions:
+
+## Red
+
+- Failing test(s):
+- Command(s):
+- Expected failure summary:
+
+## Green
+
+- Minimal implementation summary:
+- Command(s):
+- Passing summary:
+
+## Refactor
+
+- Structural improvements:
+- Why behavior is unchanged:
+- Confirmation commands:
+
+## Invariants
+
+- Invariants added/updated:
+- Boundary checks added/updated:
+
+## Security Impact
+
+- Threats considered:
+- Mitigations:
+- Residual risk:
+
+## Performance Impact
+
+- Baseline:
+- Post-change:
+- Delta explanation:
+
+## Assumptions
+
+1. Assumption 1
+
+## Open Questions
+
+1. Question 1
+
+## Rollback Plan
+
+- Trigger conditions:
+- Rollback steps:
+
+## Validation Commands
+
+```bash
+# red
+
+# green
+
+# full validation
+```
+
+## Checklist
+
+- [ ] I followed strict Red -> Green -> Refactor.
+- [ ] I completed `checklists/PR_CONTRACT_CHECKLIST.md`.
+- [ ] I completed `checklists/ADVERSARIAL_REVIEW_CHECKLIST.md` if Tier 2/Tier 3.
+- [ ] I documented any exceptions and obtained explicit approval.

.github/workflows/contract-gates.yml

@@ -0,0 +1,65 @@
+name: contract-gates
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  contract-gates:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout pull request head
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Checkout push branch
+        if: github.event_name != 'pull_request'
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Ensure scripts are executable
+        run: chmod +x scripts/*.sh
+
+      - name: Lint shell scripts
+        run: |
+          bash -n scripts/validate_tdd_cycle.sh
+          bash -n scripts/validate_evidence_packet.sh
+
+      - name: Validate TDD commit sequence
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_SHA="$(jq -r '.pull_request.base.sha' "$GITHUB_EVENT_PATH")"
+          elif [ "${{ github.event_name }}" = "push" ]; then
+            BASE_SHA="$(jq -r '.before // ""' "$GITHUB_EVENT_PATH")"
+            if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+              BASE_SHA="$(git rev-list --max-parents=0 HEAD | tail -n 1)"
+            fi
+          else
+            BASE_SHA="$(git rev-list --max-parents=0 HEAD | tail -n 1)"
+          fi
+
+          if ! git rev-parse --verify --quiet "${BASE_SHA}^{commit}" >/dev/null; then
+            BASE_SHA="$(git rev-list --max-parents=0 HEAD | tail -n 1)"
+          fi
+
+          scripts/validate_tdd_cycle.sh --base "$BASE_SHA"
+
+      - name: Validate evidence packet in PR body
+        if: github.event_name == 'pull_request'
+        run: |
+          jq -r '.pull_request.body // ""' "$GITHUB_EVENT_PATH" > /tmp/pr_body.md
+          scripts/validate_evidence_packet.sh --pr-body /tmp/pr_body.md
+
+      - name: Validate repository evidence packet on push (optional)
+        if: github.event_name == 'push' && hashFiles('.evidence/EVIDENCE_PACKET.md') != ''
+        run: scripts/validate_evidence_packet.sh --file .evidence/EVIDENCE_PACKET.md

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+*.swp

CONTRACT_SYSTEM_V2.md

@@ -0,0 +1,35 @@
+# Contract System v2
+
+## Objective
+
+Provide an executable, auditable contract system for high-quality AI-assisted coding.
+
+## What v2 Adds
+
+1. Cross-language core contracts in `contracts/core/`.
+2. Mandatory Red -> Green -> Refactor enforcement.
+3. Risk-tier policy to scale rigor by blast radius.
+4. Evidence packet requirements for every meaningful change.
+5. Adversarial review model for high-risk work.
+6. CI automation for TDD/evidence validation.
+
+## Enforcement Path
+
+1. PR template collects structured evidence.
+2. `scripts/validate_tdd_cycle.sh` checks commit history sequence.
+3. `scripts/validate_evidence_packet.sh` checks required evidence sections.
+4. `.github/workflows/contract-gates.yml` runs checks on pull requests.
+
+## Adoption Sequence
+
+1. Require task packets and test plans for all Tier 1+ work.
+2. Require evidence packets for all Tier 1+ PRs.
+3. Enforce adversarial review for Tier 2/Tier 3.
+4. Monitor defects and update contracts based on escaped failures.
+
+## Success Criteria
+
+1. Lower escaped defect rate.
+2. Lower change failure rate.
+3. Higher confidence in AI-generated code.
+4. Better review quality through structured evidence.

README.md

@@ -1,68 +1,103 @@
 # programming_tiger_style
 
-Standards-first repository for writing code with humans and AI agents.
+Standards-first repository for high-rigor coding with humans and AI agents.
 
-This repo captures a safety-focused engineering philosophy and turns it into enforceable coding
-contracts for Rust, TypeScript, and Python, with mandatory TDD.
+This project translates TigerBeetle style and NASA/JPL Power of Ten ideas into an executable
+Contract System v2 for AI-assisted software development.
 
-## Why this exists
+## Source Foundations
 
-These documents are built on two source references:
+1. `resources/TIGER_STYLE.md`
+2. `resources/P10.pdf`
 
-- `TIGER_STYLE.md` (TigerBeetle style philosophy)
-- `P10.pdf` (NASA/JPL Power of Ten)
+## Contract System v2
 
-The contracts in this repo adapt those ideas into practical rules for modern language stacks and
-agent-assisted development.
+Contract System v2 has four layers:
 
-## Core principles
+1. Core contracts (cross-language): `contracts/core/`
+2. Language contracts:
+- `contracts/languages/RUST_CODING_CONTRACT.md`
+- `contracts/languages/TYPESCRIPT_CODING_CONTRACT.md`
+- `contracts/languages/PYTHON_CODING_CONTRACT.md`
+3. Delivery templates: `templates/`
+4. Validation and governance:
+- `checklists/`
+- `scripts/`
+- `.github/workflows/contract-gates.yml`
 
-- Priority order is fixed: Safety -> Performance -> Developer Experience.
-- Keep control flow simple and bounded.
-- Handle errors explicitly.
-- Use assertions/invariants deliberately.
-- Prefer explicit limits (timeouts, retries, queue depth, batch size, memory growth).
-- Enforce strict TDD with Red -> Green -> Refactor for every code change.
+In conflicts, apply the stricter rule.
 
-## Contracts
+## Mandatory Development Model
 
-- Rust: `RUST_CODING_CONTRACT.md`
-- TypeScript: `TYPESCRIPT_CODING_CONTRACT.md`
-- Python: `PYTHON_CODING_CONTRACT.md`
+All code changes must follow strict TDD:
 
-Each contract includes:
+1. Red: write/modify a failing test.
+2. Green: implement the minimum code to pass.
+3. Refactor: improve structure without changing behavior.
 
-- Non-negotiable rules
-- Language-specific style/API constraints
-- AI agent workflow requirements
-- Required CI gates
-- PR compliance checklist
-- Exception process
+No Red -> Green -> Refactor evidence means no merge.
 
-## Mandatory TDD cycle
+## Key Files
 
-All contracts require strict TDD in this order:
+### Core Contracts
 
-1. Red: write/modify a test that fails for the expected reason.
-2. Green: implement the minimum change to make the test pass.
-3. Refactor: improve structure with behavior unchanged and tests still green.
+- `contracts/core/AI_AGENT_CORE_CONTRACT.md`
+- `contracts/core/TDD_ENFORCEMENT_CONTRACT.md`
+- `contracts/core/RISK_TIER_POLICY.md`
+- `contracts/core/EVIDENCE_REQUIREMENTS.md`
+- `contracts/core/ARCHITECTURE_CONTRACT.md`
+- `contracts/core/SECURITY_CONTRACT.md`
+- `contracts/core/PERFORMANCE_CONTRACT.md`
+- `contracts/core/DEPENDENCY_POLICY.md`
+- `contracts/core/REVIEW_CONTRACT.md`
+- `contracts/core/INTERACTION_CONTRACT_FOR_CODEX.md`
 
-Bug fixes must start with a failing regression test.
+### Templates
 
-## How to use this repo
+- `templates/TASK_PACKET_TEMPLATE.md`
+- `templates/TEST_PLAN_TEMPLATE.md`
+- `templates/EVIDENCE_PACKET_TEMPLATE.md`
+- `templates/ADR_TEMPLATE.md`
+- `templates/SESSION_HANDOFF_TEMPLATE.md`
 
-1. Pick the language contract that matches the code you are writing.
-2. Start with the contract's AI/human workflow and define invariants, bounds, and error model.
-3. Execute work in strict Red -> Green -> Refactor cycles.
-4. Run the contract's CI gate commands.
-5. Complete the PR checklist and include TDD evidence.
+### Checklists
 
-## Intended use with AI agents
+- `checklists/PR_CONTRACT_CHECKLIST.md`
+- `checklists/ADVERSARIAL_REVIEW_CHECKLIST.md`
 
-- Load the relevant contract before generating or editing code.
-- Treat contract rules as hard constraints, not suggestions.
-- Reject outputs that skip Red/Green or bypass required checks.
+### Automation
 
-## Repository status
+- `scripts/validate_tdd_cycle.sh`
+- `scripts/validate_evidence_packet.sh`
+- `.github/pull_request_template.md`
+- `.github/workflows/contract-gates.yml`
 
-This repository currently stores standards and contracts only.
+### References
+
+- `resources/RESOURCES.md`
+
+## Operating Workflow
+
+1. Create a task packet.
+2. Assign risk tier.
+3. Create a test plan.
+4. Execute Red -> Green -> Refactor in small cycles.
+5. Produce evidence packet.
+6. Complete PR and adversarial checklists.
+7. Pass CI contract gates.
+
+## For Codex Users
+
+Before implementation, provide:
+
+1. Objective and non-goals.
+2. Constraints and forbidden approaches.
+3. Interfaces/files in scope.
+4. Acceptance criteria.
+5. Risk tier.
+
+Then require explicit evidence in PR output.
+
+## Repository Status
+
+This repository stores contract definitions, templates, and enforcement automation.

checklists/ADVERSARIAL_REVIEW_CHECKLIST.md

@@ -0,0 +1,39 @@
+# Adversarial Review Checklist
+
+Use this checklist to intentionally search for failure modes, not to confirm intent.
+
+## Correctness Attacks
+
+- [ ] Try invalid, malformed, and boundary inputs.
+- [ ] Test state transition edge cases and illegal transitions.
+- [ ] Verify behavior under retries, duplicate requests, and partial failures.
+
+## Concurrency And Ordering
+
+- [ ] Probe race conditions and ordering assumptions.
+- [ ] Verify idempotency where operations may be replayed.
+- [ ] Check for deadlock/starvation/resource contention patterns.
+
+## Security Attacks
+
+- [ ] Attempt authorization bypass and privilege escalation paths.
+- [ ] Probe injection vectors (query, shell, template, deserialization).
+- [ ] Check for sensitive data leaks in logs/errors.
+
+## Performance Attacks
+
+- [ ] Evaluate worst-case input sizes and pathological patterns.
+- [ ] Verify queue, retry, and batch bounds under stress.
+- [ ] Check for unbounded memory/CPU growth.
+
+## Failure Recovery
+
+- [ ] Validate rollback/fallback behavior.
+- [ ] Ensure errors are actionable and preserve context.
+- [ ] Confirm observability signals are sufficient for diagnosis.
+
+## Evidence Quality
+
+- [ ] Evidence packet includes concrete command outputs and rationale.
+- [ ] Assumptions and unresolved questions are explicitly listed.
+- [ ] Residual risks are documented and accepted by reviewers.