lanekeeper 0.6.0__tar.gz

lanekeeper-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lanekeeper Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lanekeeper-0.6.0/PKG-INFO

@@ -0,0 +1,669 @@
+Metadata-Version: 2.4
+Name: lanekeeper
+Version: 0.6.0
+Summary: Mechanical Safety & Coordination Tool for Running Parallel AI Coding Agents
+Author: Lanekeeper Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/kish21/parallel-agents
+Project-URL: Repository, https://github.com/kish21/parallel-agents
+Project-URL: Changelog, https://github.com/kish21/parallel-agents/blob/main/CHANGELOG.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# Lanekeeper ⚡
+
+[![Version](https://img.shields.io/badge/version-v0.6.0-blue.svg)](https://github.com/kish21/parallel-agents/blob/main/CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kish21/parallel-agents/blob/main/LICENSE)
+
+**Run multiple AI coding agents safely in the same repository.**
+
+Lanekeeper gives each coding agent its own Git worktree, branch, ports, environment, and code boundaries, so agents can work at the same time without accidentally interfering with each other.
+
+```
+                    Your Repository
+                          │
+             ┌────────────┼────────────┐
+             │            │            │
+             ▼            ▼            ▼
+          Agent 1      Agent 2      Agent 3
+          Backend      Frontend     Tests
+             │            │            │
+          Worktree     Worktree     Worktree
+          Branch       Branch       Branch
+          Port 8001    Port 8002    Port 8003
+             │            │            │
+             └────────────┼────────────┘
+                          ▼
+                      Validate
+                          │
+                          ▼
+                         PRs
+```
+
+---
+
+## Why Lanekeeper?
+
+AI coding agents are powerful, but running several agents in the same repository creates real operational problems:
+
+* **File Overwrites**: One agent can modify files another agent is actively working on.
+* **Port Clashes**: Two agents can accidentally claim the same development port.
+* **Cross-Talk**: Frontends can connect to another agent's uncommitted backend code.
+* **Migration Conflicts**: Shared database migrations can clash or create duplicate counters.
+* **Out-of-Scope Changes**: An agent can modify central configs, auth, or infrastructure outside its assigned task.
+* **Resource Leaks**: Failed agents can leave behind orphaned processes, blocked ports, or stale git state.
+
+Lanekeeper adds a mechanical coordination and safety layer around your coding agents to prevent these problems.
+
+---
+
+## The Basic Idea
+
+There are four fundamental concepts:
+
+### 1. Agent
+An agent is an isolated worker session assigned to a specific task.
+```
+agent-001 → "Implement user authentication"
+```
+
+### 2. Worktree
+Each agent gets its own physical Git working directory.
+```
+Agent 1 → .lanekeeper/worktrees/agent-001
+Agent 2 → .lanekeeper/worktrees/agent-002
+Agent 3 → .lanekeeper/worktrees/agent-003
+```
+Agents never edit the same physical files simultaneously.
+
+### 3. Lane
+A lane defines which part of the codebase an agent is permitted to touch.
+```yaml
+lane: backend
+
+allow:
+  - src/api/**
+  - src/services/**
+  - tests/api/**
+
+deny:
+  - src/frontend/**
+  - infrastructure/**
+```
+If the backend agent modifies `src/api/users.py`, that is allowed. If it touches `src/frontend/App.tsx`, validation reports a violation.
+
+### 4. Resources
+Each agent receives its own dedicated runtime resources:
+```
+Agent 1 → backend port 8001, frontend port 3001
+Agent 2 → backend port 8002, frontend port 3002
+Agent 3 → backend port 8003, frontend port 3003
+```
+This prevents agents from talking to the wrong development server.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+pip install lanekeeper
+```
+
+This installs the `lanekeeper` command. Check which build you have with:
+
+```bash
+lanekeeper --version
+```
+
+From a clone:
+
+```bash
+pip install -e .
+```
+
+### 2. Initialize the Repository
+
+`init` reads your repository and generates lanes that match its actual structure, then
+reports how much of the tree they cover:
+
+```
+$ lanekeeper init
+🧭 Detected 3 lanes from the repository layout: backend, frontend, platform
+   Coverage: 100% of 412 tracked files fall inside a lane.
+```
+
+If coverage is low it says so, rather than letting you discover it when validation reports
+legitimate work as out-of-lane. Use `--generic` to keep the starter lanes instead.
+
+From your project root:
+```bash
+lanekeeper init
+```
+This creates the `.lanekeeper/` configuration and state directories.
+
+Lanekeeper keeps its own files in one directory. To put them somewhere else,
+set `LANEKEEPER_HOME` to a directory name relative to the repository root
+before running any command:
+
+```bash
+export LANEKEEPER_HOME=.agents
+```
+
+Everything lanekeeper writes moves with it — config, state, logs, capability
+cards, the default worktree location, and the rules `init` adds to
+`.gitignore`. Absolute paths and paths containing `..` are rejected, so the
+directory always stays inside the repository.
+
+### 3. Create an Agent
+```bash
+lanekeeper spawn \
+  --name backend-1 \
+  --lane backend \
+  --task "Implement user authentication"
+```
+Lanekeeper provisions the isolated worktree, branch, `.env`, and dedicated ports automatically (and optionally starts an agent execution process when `--command` is supplied).
+
+### 4. Create Another Agent
+```bash
+lanekeeper spawn \
+  --name frontend-1 \
+  --lane frontend \
+  --task "Build the login interface"
+```
+Now both agents can work simultaneously without collision.
+
+### 5. Check Agents
+```bash
+$ lanekeeper status
+
+📋 LANEKEEPER — MY-PROJECT
+
+Agent ID     Name           Seat   Lane         Status     Ports            Task
+----------------------------------------------------------------------------------------------------
+agent-001    backend-1      SR1    backend      RUNNING    8001/3001        Implement user authentication
+agent-002    frontend-1     JR1    frontend     RUNNING    8002/3002        Build the login interface
+```
+
+### 6. Validate an Agent's Work
+```bash
+$ lanekeeper validate agent-001
+
+🛡️ VALIDATION REPORT: backend-1 (agent-001)
+Lane: backend
+
+  [Lane Compliance]
+    ✓ All 4 changed files are within allowed lane paths.
+
+==================================================
+✅ VALIDATION PASSED: PR is safe to submit and merge.
+```
+
+### 7. Inspect Changed Files
+```bash
+lanekeeper diff agent-001
+```
+
+### 8. Stop an Agent
+```bash
+lanekeeper stop agent-001
+```
+
+### 9. Clean Up Safely
+```bash
+lanekeeper cleanup agent-001
+```
+
+---
+
+## How It Works
+
+```
+WITHOUT LANEKEEPER:                           WITH LANEKEEPER:
+
+Agent A ─────┐                                      Git Repository
+             │                                            │
+Agent B ─────┼── Same working directory     ┌─────────────┼─────────────┐
+             │                              │             │             │
+Agent C ─────┘                              ▼             ▼             ▼
+                                         Agent A       Agent B       Agent C
+             ↓                              │             │             │
+      Conflicts & Leaks                Worktree A    Worktree B    Worktree C
+                                       Branch A      Branch B      Branch C
+                                       Port 8001     Port 8002     Port 8003
+                                            │             │             │
+                                            ▼             ▼             ▼
+                                         Backend       Frontend       Tests
+```
+
+The core difference is **physical isolation**. Agents are not merely prompted to avoid collisions; the tooling physically isolates their files, branches, and ports, and mechanically validates their boundaries.
+
+---
+
+## Lanes
+
+Lanes are how you define architectural ownership boundaries:
+
+```yaml
+lanes:
+  backend:
+    allow:
+      - src/api/**
+      - src/services/**
+      - tests/api/**
+    deny:
+      - src/frontend/**
+
+  frontend:
+    allow:
+      - src/frontend/**
+      - tests/frontend/**
+    deny:
+      - src/api/**
+
+  infrastructure:
+    allow:
+      - infrastructure/**
+      - deployment/**
+```
+
+```
+backend agent        frontend agent        infrastructure agent
+      ↓                     ↓                       ↓
+backend files         frontend files        infrastructure files
+```
+
+The goal is not to isolate every single file—it is to make parallel execution predictable.
+
+---
+
+### Lane enforcement fails closed
+
+Lane policy is only meaningful if it cannot be switched off by accident, so every lane
+lookup is strict:
+
+* `spawn --lane <name>` **rejects** a lane that is not declared in `config.yaml`, listing
+  the valid lanes. Nothing is provisioned — no branch, no worktree, no port reservation.
+* `validate` and `diff` **refuse** an agent whose lane is no longer declared (for example,
+  the lane was renamed or removed after the agent was spawned). They report a failure
+  rather than checking the agent against an empty policy.
+
+There is deliberately no permissive fallback. An unrecognised lane is a configuration
+error, never a lane that happens to allow every path.
+
+> **Commit `.lanekeeper/config.yaml`.** It is the policy every agent is validated
+> against — the team's shared contract. `lanekeeper init` adds ignore rules that keep
+> runtime state and worktrees out of git while leaving the config tracked. Without those
+> rules an agent running `git add -A` would sweep every other agent's worktree into its own
+> commit.
+
+
+## Capability Gates
+
+A lane answers **where** a seat may work. A capability card answers **what kind of work it
+is competent to do there**.
+
+Each seat has a card declaring its capabilities in three states:
+
+| State | Meaning | Effect |
+|---|---|---|
+| `native` | The harness does this reliably. | Proceeds. |
+| `author-required` | It can, but only by running a procedure written for it. | Proceeds **only** if a quality command declaring `satisfies: <capability>` passed. |
+| `unavailable` | It cannot do this safely. | **Hard stop.** Non-zero exit; must escalate. |
+
+`config.yaml` maps paths to the capability they require:
+
+```yaml
+capability_gates:
+  security_review:
+    paths: ["**/auth/**", "**/payments/**", "**/tenant/**", "secrets/**"]
+  database_migrations:
+    paths: ["database/migrations/**", "migrations/**"]
+```
+
+So a junior seat rated `security_review: unavailable` cannot get a green validation on an
+auth file — **even when that file is inside its lane**:
+
+```
+  [Lane Compliance]
+    ✓ All 1 changed files are within allowed lane paths.
+
+  [Capability Gates] seat JR1 — evaluated: database_migrations, security_review
+    ✗ src/backend/auth/login.py
+        requires 'security_review' — seat is 'unavailable'
+        seat 'JR1' cannot perform 'security_review'. This change must be escalated
+        to a seat rated native for it.
+
+❌ VALIDATION FAILED: Must resolve errors before merging.
+```
+
+This is the mechanical form of the rule in `01-working-agreement.md`: stop when the change
+touches money, auth, tenant isolation, or a migration.
+
+### It fails closed, in four ways
+
+An unrecognised seat, a seat with no card, a capability the card does not rate, and a
+green-but-untagged quality command are **all denials**. Absence is never permission.
+
+### Generating the gate declaration
+
+`lanekeeper declare <agent>` produces the PR template's mandatory Gate Declaration
+from recorded state — the seat, its ratings, the gates triggered, and each quality command
+with its real exit code — rather than asking an author to type it from memory.
+
+> **What this does not do.** It does not verify that a `native` rating is *honest*. A
+> rating is a claim by the seat's owner; the tool holds the claim in one place, refuses
+> work the claim says the seat cannot do, and makes the declaration an artefact.
+> Rating honesty stays a human review question.
+
+
+## Ports
+
+Parallel development servers need independent ports. Instead of hardcoding `8000`:
+
+```
+Agent 1 → Port 8001 / 3001
+Agent 2 → Port 8002 / 3002
+Agent 3 → Port 8003 / 3003
+```
+
+Allocations are deterministic, checked against the host OS socket state, injected into `.env`, and released upon cleanup.
+
+### Service URLs
+
+A port number on its own does not connect anything. Browser build tools expose only their
+own prefixed variables to client code — Vite reads `VITE_*`, Next.js reads
+`NEXT_PUBLIC_*` — so a frontend handed `API_PORT=8002` cannot see it, and falls back to
+whatever server is compiled into its source. That is usually another agent's backend.
+
+`lanekeeper init` therefore reads the dependencies your repository declares and writes
+the matching URL variables into `.lanekeeper/config.yaml`:
+
+```yaml
+environment:
+  host: 127.0.0.1
+  url_templates:
+    API_URL: http://${HOST}:${BACKEND_PORT}
+    VITE_API_URL: http://${HOST}:${BACKEND_PORT}
+    FRONTEND_URL: http://${HOST}:${FRONTEND_PORT}
+```
+
+Each agent's `.env` then resolves them against its own ports:
+
+```bash
+# .lanekeeper/worktrees/agent-002/.env
+BACKEND_PORT='8002'
+VITE_API_URL='http://127.0.0.1:8002'   # agent-002's own backend, never agent-001's
+```
+
+Add, remove, or rename templates to suit your stack; a template naming a port category
+your project does not define is dropped rather than written half-expanded.
+
+Lanekeeper does **not** install dependencies. A fresh worktree has no `node_modules` or
+virtualenv, so run your usual install command in it before starting a dev server.
+
+---
+
+## Agent Lifecycle
+
+Agents follow an explicit state machine:
+
+```
+CREATED ──► STARTING ──► RUNNING ──┬──► COMPLETED ──► REVIEW
+                            │      │
+                            │      └──► FAILED ──► REPAIR ──► RUNNING
+                            ▼
+                         STOPPED
+```
+
+Useful commands:
+```bash
+lanekeeper status
+lanekeeper logs backend-1
+lanekeeper stop backend-1
+lanekeeper restart backend-1
+lanekeeper repair backend-1
+lanekeeper cleanup backend-1
+```
+
+---
+
+## Mechanical Validation
+
+Never rely on an AI agent's word that its work is complete. Lanekeeper independently validates:
+
+```bash
+$ lanekeeper validate backend-1
+
+Validation: backend-1
+
+Git
+  ✓ Correct branch
+  ✓ Correct worktree
+
+Policy
+  ✓ All changed files allowed in lane 'backend'
+
+Quality
+  ✓ Tests passed
+  ✓ Lint passed
+  ✓ Typecheck passed
+
+Result: PASS
+```
+
+If an agent touches a forbidden file:
+```
+Validation: backend-1
+
+Policy
+  ✗ Forbidden file modified: src/frontend/App.tsx (Reason: denied)
+
+Result: FAIL (Exit code 2)
+```
+
+---
+
+## Recovery & Diagnostics
+
+If an agent process crashes or an orphaned port is left behind:
+
+```bash
+$ lanekeeper doctor
+
+🩺 LANEKEEPER DOCTOR
+
+  ✓ Git repository: Valid Git repository detected.
+  ✓ Configuration: Valid config (Project: demo, Max agents: 4).
+  ✓ Worktrees: All 1 agent worktrees are intact.
+  ✗ Port allocations: 2 port allocation issue(s) detected.
+      ↳ Port 3001 still reserved by stopped agent 'agent-001'.
+      ↳ Port 8001 still reserved by stopped agent 'agent-001'.
+  ✓ Agent processes: All active agent process states are consistent.
+
+⚠️ 1 problem(s) detected. Run 'lanekeeper repair' to fix.
+```
+
+`doctor` reports three classes of problem:
+
+| Class | Meaning |
+|---|---|
+| **Orphaned** | A port is still reserved by an agent that has stopped, failed, completed, or no longer exists. If a process is *still listening* on it, it is reported as a leaked server. |
+| **Conflict** | The port ledger and an agent's own recorded ports disagree — the dangerous case, because the ledger could hand the same port to a second agent. |
+| **Stale process** | An agent is marked `RUNNING` but its PID is dead. |
+
+Run repair to automatically clean up orphaned resources:
+```bash
+lanekeeper repair
+```
+
+---
+
+## Database Isolation
+
+Projects that interact with databases can configure an isolation strategy:
+
+```yaml
+database:
+  strategy: per-agent
+  name_template: "app_${AGENT_ID}"
+```
+
+Resulting databases:
+```
+agent-001 → app_agent_001
+agent-002 → app_agent_002
+agent-003 → app_agent_003
+```
+
+---
+
+## Agent Providers & Adapters
+
+Lanekeeper is provider-independent. It uses a pluggable `AgentAdapter` abstraction:
+
+```
+              Lanekeeper
+                    │
+              Agent Adapter
+                    │
+       ┌────────────┼────────────┐
+       ▼            ▼            ▼
+   CLI harness   IDE session   Custom adapter
+```
+
+The orchestration layer handles isolation, ports, and validation; the adapter handles
+execution. No vendor is named anywhere in the tooling or the configuration schema: which
+harness fills a seat is recorded in that seat's capability card (`vendor_harness`), so
+swapping vendors edits one field and changes nothing else.
+
+---
+
+## 🛠️ CLI Reference
+
+| Command | Purpose |
+| :--- | :--- |
+| **`lanekeeper init`** | Initializes repository and creates configuration. |
+| **`lanekeeper doctor`** | Diagnoses repository, worktree, and port health. |
+| **`lanekeeper spawn`** | Provisions an isolated worktree, branch, `.env`, and allocated ports. |
+| **`lanekeeper status`** | Shows active agents, lanes, and allocated ports (`--json` supported). |
+| **`lanekeeper validate`** | Mechanically validates lane compliance and runs test suites. |
+| **`lanekeeper diff`** | Displays changed files classified as `[LANE OK]` vs. `[OUT-OF-LANE]`. |
+| **`lanekeeper inspect`** | Shows detailed agent metadata and environment variables. |
+| **`lanekeeper logs`** | Tails structured execution logs for an agent session. |
+| **`lanekeeper stop`** | Stops an active agent process. |
+| **`lanekeeper restart`** | Restarts an agent in its worktree. |
+| **`lanekeeper repair`** | Repairs stale states and releases orphaned ports. |
+| **`lanekeeper declare`** | Generates the PR gate declaration from recorded state. |
+| **`lanekeeper cleanup`** | Safely removes worktrees and releases port allocations. |
+
+---
+
+## 💡 Design Philosophy
+
+1. **Isolation Over Instructions**: Do not merely instruct agents to avoid collisions; provide physically isolated environments.
+2. **Mechanical Validation Over Trust**: Never assume an agent followed the rules; mechanically verify diffs against lane policies.
+3. **Simple Over Clever**: Coordinate coding agents with clarity; do not build an autonomous swarm or bloated web UI.
+4. **Developer in Control**: Agents propose changes; humans review and merge them.
+5. **Safe Cleanup**: Never sacrifice uncommitted developer work for aggressive cleanup.
+
+---
+
+## 🚫 What Lanekeeper Is Not
+
+* ❌ Not an autonomous AI software company.
+* ❌ Not an AI project manager.
+* ❌ Not a replacement for Git or CI/CD.
+* ❌ Not tied to any single AI vendor or model.
+
+It is a **lightweight coordination and safety layer** for parallel AI coding agents.
+
+---
+
+## 🧪 Automated Testing & Reliability Benchmarks
+
+Lanekeeper includes a **tracked 36-test unit, integration, concurrency stress, and failure recovery suite** and an automated reproducibility benchmark runner.
+
+### 1. Run the Full Test Suite
+```bash
+python -m unittest discover tests
+```
+```
+....................................
+----------------------------------------------------------------------
+Ran 139 tests in 16.3s
+
+OK
+```
+
+#### What Is Tested & Proven:
+* **StateLock Integration (`test_state_lock.py`)**: Validates StateLock mutual exclusion under heavy contention (20 simultaneous threads) with zero state lost or overwritten.
+* **Atomic Concurrency & Stress (`test_concurrency.py`, `test_e2e_concurrent.py`)**: Spawns up to 10 agents in parallel threads simultaneously across separate CPU workers to mechanically prove that re-entrant file locking (`StateLock`) assigns unique sequential IDs, dedicated Git worktrees, unique branches, and non-colliding ports atomically with zero lost state.
+* **Failure Modes & Transactional Rollbacks (`test_failure_modes.py`)**: Validates clean port rollback on port exhaustion, clean rollback when worktree creation fails (simulated disk/git failure), dead process diagnosis and recovery in `repair`, and protection of uncommitted developer code during cleanup.
+* **3-Agent Multi-Lane Workflow (`test_e2e_3agents.py`)**: Concurrently spawns Agent A (Backend), Agent B (Frontend), and Agent C (Service), verifies distinct physical worktrees, dedicated branches, and unique ports (`8001/3001`, `8002/3002`, `8003/3003`), validates in-lane edits (pass), proves deliberate cross-lane violations fail with exit code `2`, and cleanly reclaims all resources.
+* **Port Audit & Conflict Detection (`test_ports.py`, `test_port_audit.py`, `test_port_conflicts.py`)**: Validates real OS socket probing (a bound socket is detected and skipped by the allocator), ledger/agent-state drift detection, leaked-server reporting on orphaned ports, and that a failed re-allocation never releases the agent's existing reservations.
+* **Fail-Closed Lane Enforcement (`test_lane_fail_closed.py`)**: Proves that an undeclared lane — a typo at spawn, or a lane deleted from the config afterwards — is rejected outright rather than validating as safe, and that a rejected spawn leaves behind no branch, worktree, or port reservation.
+* **Environment Injection (`test_env_injection.py`)**: Round-trips hostile task strings (quotes, newlines, `$VAR`, backticks, `$(...)`) through a real `/bin/sh` to prove generated `.env` and `.lane` files cannot be escaped or executed.
+* **Capability Gates (`test_capability_gates.py`)**: Proves an `unavailable` capability hard-stops an in-lane file, `native` passes the same file, `author-required` passes only when its verified script exits 0, `forbidden_paths` overrides the lane allow, and four separate fail-closed paths (unknown seat, missing card, unrated capability, untagged command).
+* **Glob Matching (`test_glob_matching.py`)**: Pins segment-aware `**` semantics, including that `**/auth/**` must not match `src/authentic/`, and that a recursive deny pattern actually denies.
+* **Repository Hygiene (`test_init_gitignore.py`)**: Proves `git add -A` cannot stage agent worktrees or runtime state, while the shared lane policy stays tracked.
+* **Diagnostics & Recovery (`test_doctor.py`, `test_cleanup.py`)**: Validates automatic detection of missing worktrees, orphaned port reclamation, and uncommitted developer code protection.
+
+---
+
+### 2. Run Reproducibility Benchmarks
+```bash
+python benchmarks/benchmark_parallel.py --cycles 5
+```
+```
+======================================================================
+📈 LANEKEEPER: BENCHMARK RESULTS & SYSTEM RELIABILITY METRICS
+======================================================================
+  • Total Cycles Executed:        5 / 5
+  • Total Agents Spawned:         15
+  • Total Execution Time:         7.02s
+----------------------------------------------------------------------
+  • Worktree Collision Rate:      0.0% (0 collisions)
+  • Port Race Condition Rate:     0.0% (0 collisions)
+  • Lane Violation Accuracy:      100.0% (5/5 caught)
+  • Worktree Leaks Post-Cleanup:  0
+======================================================================
+✅ PASSED: 5 cycles / 15 agents with 0 observed worktree or port collisions, 5/5 injected lane violations detected, and no leaked resources.
+======================================================================
+```
+
+Every number above is measured at run time. The benchmark exits non-zero on any collision,
+leak, or undetected violation, so CI fails rather than printing a clean summary over a bad
+run.
+
+---
+
+## 📚 Deep-Dive Documentation & Guides
+
+| Document | Description |
+| :--- | :--- |
+| **[🎬 End-to-End Walkthrough](https://github.com/kish21/parallel-agents/blob/main/EXAMPLES.md)** | Step-by-step lifecycle of Ticket #102 from assignment to merge. |
+| **[01. Working Agreement](https://github.com/kish21/parallel-agents/blob/main/01-working-agreement.md)** | Definition-of-Done, path boundary contracts, and merge discipline. |
+| **[02. Conflict Management](https://github.com/kish21/parallel-agents/blob/main/02-conflict-management.md)** | Worktree deep-dive, port tables, and Disaster Recovery Runbook. |
+| **[03. Orchestration](https://github.com/kish21/parallel-agents/blob/main/03-orchestration.md)** | Capability cards, scaling 2→4→6 seats, and ROI metrics. |
+| **[04. Agent Setup](https://github.com/kish21/parallel-agents/blob/main/04-agent-setup.md)** | Prompts for Senior/Junior agents and token cost hygiene. |
+| **[05. GitHub Mechanics](https://github.com/kish21/parallel-agents/blob/main/05-github-mechanics.md)** | Board custom fields, disjoint milestones, and single-account routing. |
+| **[06. Free-Tier Operations](https://github.com/kish21/parallel-agents/blob/main/06-free-tier-ops.md)** | CI minute optimization, public vs private repo trade-offs, and verified mirrors. |
+
+---
+
+## 🤝 Community & Contributing
+
+Contributions are welcome! See our community guidelines:
+* **[Contributing Guide](https://github.com/kish21/parallel-agents/blob/main/CONTRIBUTING.md)**
+* **[Security Policy](https://github.com/kish21/parallel-agents/blob/main/SECURITY.md)**
+* **[Code of Conduct](https://github.com/kish21/parallel-agents/blob/main/CODE_OF_CONDUCT.md)**
+
+---
+
+## License
+[MIT](https://github.com/kish21/parallel-agents/blob/main/LICENSE)