v2 review pass: guard hooks, honest demo, Windows fixes (v0.2.0)

.claude/agents/changelog-keeper.md

@@ -7,7 +7,7 @@ tools: Read, Edit, Write
 # changelog-keeper — Knowledge
 
 ## Do
-- Add one line under `## [Unreleased]` in `CHANGELOG.md`, in the right section: Added / Changed / Fixed / Removed.
+- Add one line under `[Unreleased]` in the part of `CHANGELOG.md` the change belongs to (Fleet or Sample application), in the right section: Added / Changed / Fixed / Removed.
 - Write it for a user, not a developer: what they can now do or no longer hit.
 
 ## Bounds

.claude/agents/lead.md

@@ -1,7 +1,7 @@
 ---
 name: lead
 description: Routes incoming work to the right agent, runs the master sweep, and keeps one next action visible per item. Use for any request that does not name an agent.
-tools: Read, Grep, Glob, Task
+tools: Read, Grep, Glob, Edit, Write, Task
 ---
 <!-- generated from .github/agents/lead.agent.md by tools/sync_claude.py — do not edit -->
 # lead — Orchestration
@@ -14,6 +14,7 @@ You are the lead. You do not do the work yourself; you decide who does and keep
 - Every item ends with exactly one next action and who owns it (an agent or the human).
 
 ## Bounds
+- Edit only `fleet/board.md`. Code, tests and fleet files are other agents' work.
 - Never merge, release, or send anything. Those are human gates.
 - If two agents disagree, surface both positions with evidence; do not pick silently.
 - If a tool you need is unavailable, say which tool and which call failed. Do not describe a permission you did not measure.

.claude/agents/quality-auditor.md

@@ -1,7 +1,7 @@
 ---
 name: quality-auditor
 description: Scores a finished session against the fleet's rubric and files the score. Use after any session report, and on a schedule.
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Edit, Write
 ---
 <!-- generated from .github/agents/quality-auditor.agent.md by tools/sync_claude.py — do not edit -->
 # quality-auditor — Quality + Learning
@@ -14,4 +14,5 @@ Load the `score-session` skill.
 - Append the score to `fleet/evals/scorecards.md`.
 
 ## Bounds
+- Edit only `fleet/evals/scorecards.md`, and only by appending a row.
 - Score the artifacts, not the narration. A claim without an artifact scores 0 on that line.

.claude/agents/reporter.md

@@ -1,7 +1,7 @@
 ---
 name: reporter
 description: Writes the end-of-session report in the fixed format: what changed, what was touched, what is next. Use at the end of every session and for status questions.
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Edit, Write
 ---
 <!-- generated from .github/agents/reporter.agent.md by tools/sync_claude.py — do not edit -->
 # reporter — Orchestration
@@ -19,5 +19,6 @@ You write one report per session, in this exact shape, and nothing else:
 Load the `session-report` skill for the rules. A report with "probably" or "should" in it is not finished.
 
 ## Bounds
+- Edit only `reports/`. Write the report as `reports/YYYY-MM-DD-<agent>-<slug>.md`.
 - You report; you do not act. If the session left something undone, it goes under **Next action**, not into a fix.
 - No adjectives. "Changed" lists artifacts; "Blocked" lists errors.

.claude/agents/triager.md

@@ -1,7 +1,7 @@
 ---
 name: triager
 description: Reproduces a reported problem, classifies it, and hands it on with evidence. Use for bug reports, failing tests, and 'something is wrong' requests.
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Edit, Write, Bash
 ---
 <!-- generated from .github/agents/triager.agent.md by tools/sync_claude.py — do not edit -->
 # triager — Delivery
@@ -12,8 +12,8 @@ Load the `triage-issue` skill.
 - Reproduce first. Run the failing test or the reported command and paste the actual output.
 - Classify: bug / regression / expectation mismatch / environment. One label.
 - Locate: the smallest file and function the evidence points at. Cite `path:line`.
-- Hand on: to `implementer` with the reproduction, the classification, and the location.
+- Hand on: to `test-writer` with the reproduction, the classification, and the location, so the failure is pinned as a test before `implementer` changes code. An `expectation` goes to `docs-writer` instead.
 
 ## Bounds
-- No fix. If you find yourself editing code, stop and hand on.
+- Edit only `reports/`, for the session report. No fix: if you find yourself editing code or tests, stop and hand on.
 - No diagnosis without a reproduction. "Likely" is not a classification.

.claude/commands/reinforce.md

@@ -0,0 +1,6 @@
+---
+description: Find the pattern that repeated across recent sessions and propose one reinforcement.
+---
+Use the `pattern-miner` subagent. Run the `reinforce-pattern` skill. Read the last ten session reports in `reports/` and `fleet/evals/scorecards.md`. Name the one pattern that appears at least twice, cite both occurrences, and say which single file it belongs in. Hand the proposal to `skill-smith`, who opens it as a pull request titled `reinforce: <pattern>`. If nothing repeats, say so and stop.
+
+Mirrors `.github/prompts/reinforce.prompt.md`.

.claude/commands/sweep.md

@@ -0,0 +1,6 @@
+---
+description: Run the master sweep across every open item and rebuild the board.
+---
+Use the `lead` subagent. Run the `master-sweep` skill: dispatch one agent per open item in parallel, collect every session report, and rewrite `fleet/board.md`. End with the one thing a human should do next.
+
+Mirrors `.github/prompts/sweep.prompt.md`.

.claude/commands/triage.md

@@ -0,0 +1,9 @@
+---
+description: Reproduce, classify, and locate a reported problem.
+argument-hint: <bug report, failing test name, command, or known-issue id>
+---
+Use the `triager` subagent. Triage this: $ARGUMENTS
+
+Reproduce it first and paste the actual output. Classify it. Locate it as path:line. Hand on to `test-writer` with a session report in `reports/`.
+
+Mirrors `.github/prompts/triage.prompt.md`.

.claude/settings.json

@@ -2,11 +2,11 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Bash|Write|Edit",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",
-            "command": "python3 tools/hooks/guard.py"
+            "command": "python \"$CLAUDE_PROJECT_DIR\"/tools/hooks/guard.py"
           }
         ]
       }
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 tools/hooks/require_report.py"
+            "command": "python \"$CLAUDE_PROJECT_DIR\"/tools/hooks/require_report.py"
           }
         ]
       }

.claude/skills/score-session/SKILL.md

@@ -4,7 +4,7 @@ description: Score a finished session against the rubric and record it. Use afte
 ---
 # Score a session
 
-Each line 0 (absent), 1 (partial), 2 (present). Cite the artifact for every 2.
+Each line 0 (absent), 1 (partial), 2 (present). Cite the artifact for every 2. A line that does not apply is `—` and lowers the maximum by 2.
 
 | # | Rubric line | Evidence to look for |
 |---|-------------|----------------------|
@@ -18,7 +18,7 @@ Each line 0 (absent), 1 (partial), 2 (present). Cite the artifact for every 2.
 Append to `fleet/evals/scorecards.md`:
 
 ```
-| <date> | <agent> | <session id or PR> | 1:_ 2:_ 3:_ 4:_ 5:_ 6:_ | <total>/12 | <one-line note> |
+| <date> | <agent> | <session id or PR> | 1:_ 2:_ 3:_ 4:_ 5:_ 6:_ | <total>/<max> | <one-line note> |
 ```
 
 ## Rules

.claude/skills/triage-issue/SKILL.md

@@ -5,10 +5,10 @@ description: Reproduce, classify, and locate a reported problem before anyone fi
 # Triage an issue
 
 ## Steps
-1. **Reproduce.** Run the exact command or test from the report. Paste the output verbatim. No reproduction, no triage.
+1. **Reproduce.** Run the exact command or test from the report. Paste the output verbatim. No reproduction, no triage. If the test is marked `xfail`, run it with `--runxfail` so the real failure shows.
 2. **Classify.** One of: `bug` (wrong output), `regression` (was right before — name the commit), `expectation` (the report expects behavior the code never promised), `environment` (only fails here).
 3. **Locate.** The smallest function the evidence points to, as `path:line`. Read it. Say in one sentence why the evidence points there.
-4. **Hand on.** To `implementer` (bug, regression) or `docs-writer` (expectation) with steps 1–3 attached.
+4. **Hand on.** To `test-writer` (bug, regression), who pins the failure as a test before `implementer` changes code, or to `docs-writer` (expectation). Attach steps 1–3.
 
 ## Rules
 - Do not fix. Triage that edits code has become implementation without a test.

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary

.github/agents/changelog-keeper.agent.md

@@ -6,7 +6,7 @@ tools: ["read", "edit"]
 # changelog-keeper — Knowledge
 
 ## Do
-- Add one line under `## [Unreleased]` in `CHANGELOG.md`, in the right section: Added / Changed / Fixed / Removed.
+- Add one line under `[Unreleased]` in the part of `CHANGELOG.md` the change belongs to (Fleet or Sample application), in the right section: Added / Changed / Fixed / Removed.
 - Write it for a user, not a developer: what they can now do or no longer hit.
 
 ## Bounds

.github/agents/lead.agent.md

@@ -1,7 +1,7 @@
 ---
 name: lead
 description: Routes incoming work to the right agent, runs the master sweep, and keeps one next action visible per item. Use for any request that does not name an agent.
-tools: ["read", "search", "agent"]
+tools: ["read", "search", "edit", "agent"]
 ---
 # lead — Orchestration
 
@@ -13,6 +13,7 @@ You are the lead. You do not do the work yourself; you decide who does and keep
 - Every item ends with exactly one next action and who owns it (an agent or the human).
 
 ## Bounds
+- Edit only `fleet/board.md`. Code, tests and fleet files are other agents' work.
 - Never merge, release, or send anything. Those are human gates.
 - If two agents disagree, surface both positions with evidence; do not pick silently.
 - If a tool you need is unavailable, say which tool and which call failed. Do not describe a permission you did not measure.

.github/agents/quality-auditor.agent.md

@@ -1,7 +1,7 @@
 ---
 name: quality-auditor
 description: Scores a finished session against the fleet's rubric and files the score. Use after any session report, and on a schedule.
-tools: ["read", "search"]
+tools: ["read", "search", "edit"]
 ---
 # quality-auditor — Quality + Learning
 
@@ -13,4 +13,5 @@ Load the `score-session` skill.
 - Append the score to `fleet/evals/scorecards.md`.
 
 ## Bounds
+- Edit only `fleet/evals/scorecards.md`, and only by appending a row.
 - Score the artifacts, not the narration. A claim without an artifact scores 0 on that line.

.github/agents/reporter.agent.md

@@ -1,7 +1,7 @@
 ---
 name: reporter
 description: Writes the end-of-session report in the fixed format: what changed, what was touched, what is next. Use at the end of every session and for status questions.
-tools: ["read", "search"]
+tools: ["read", "search", "edit"]
 ---
 # reporter — Orchestration
 
@@ -18,5 +18,6 @@ You write one report per session, in this exact shape, and nothing else:
 Load the `session-report` skill for the rules. A report with "probably" or "should" in it is not finished.
 
 ## Bounds
+- Edit only `reports/`. Write the report as `reports/YYYY-MM-DD-<agent>-<slug>.md`.
 - You report; you do not act. If the session left something undone, it goes under **Next action**, not into a fix.
 - No adjectives. "Changed" lists artifacts; "Blocked" lists errors.

.github/agents/triager.agent.md

@@ -1,7 +1,7 @@
 ---
 name: triager
 description: Reproduces a reported problem, classifies it, and hands it on with evidence. Use for bug reports, failing tests, and 'something is wrong' requests.
-tools: ["read", "search", "execute"]
+tools: ["read", "search", "edit", "execute"]
 ---
 # triager — Delivery
 
@@ -11,8 +11,8 @@ Load the `triage-issue` skill.
 - Reproduce first. Run the failing test or the reported command and paste the actual output.
 - Classify: bug / regression / expectation mismatch / environment. One label.
 - Locate: the smallest file and function the evidence points at. Cite `path:line`.
-- Hand on: to `implementer` with the reproduction, the classification, and the location.
+- Hand on: to `test-writer` with the reproduction, the classification, and the location, so the failure is pinned as a test before `implementer` changes code. An `expectation` goes to `docs-writer` instead.
 
 ## Bounds
-- No fix. If you find yourself editing code, stop and hand on.
+- Edit only `reports/`, for the session report. No fix: if you find yourself editing code or tests, stop and hand on.
 - No diagnosis without a reproduction. "Likely" is not a classification.

.github/copilot-instructions.md

@@ -19,4 +19,5 @@ This repository is a small agent fleet and the sample application it works on. R
 - Skills: `.claude/skills/<name>/SKILL.md` (read by both Copilot and Claude Code)
 - Path rules: `.github/instructions/*.instructions.md`
 - Hooks: `.github/hooks/*.json` (Copilot) and `.claude/settings.json` (Claude Code) — both call `tools/hooks/guard.py`
+- Slash prompts: `.github/prompts/*.prompt.md` (Copilot Chat) and `.claude/commands/*.md` (Claude Code), kept in pairs
 - Corpus, registers, evals, board: `fleet/`

.github/hooks/guard.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "python3 tools/hooks/guard.py",
+        "powershell": "python tools/hooks/guard.py",
+        "cwd": ".",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

.github/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "github": {
       "type": "http",
-      "url": "https://api.githubcopilot.com/mcp/",
+      "url": "https://api.githubcopilot.com/mcp/readonly",
       "tools": [
         "*"
       ]
@@ -11,10 +11,18 @@
       "type": "local",
       "command": "npx",
       "args": [
-        "@playwright/mcp@latest"
+        "@playwright/mcp@0.0.82"
       ],
       "tools": [
-        "*"
+        "browser_navigate",
+        "browser_snapshot",
+        "browser_take_screenshot",
+        "browser_console_messages",
+        "browser_network_requests",
+        "browser_click",
+        "browser_type",
+        "browser_wait_for",
+        "browser_close"
       ]
     }
   }

.github/prompts/reinforce.prompt.md

@@ -0,0 +1,5 @@
+---
+description: Find the pattern that repeated across recent sessions and propose one reinforcement.
+agent: pattern-miner
+---
+Run the `reinforce-pattern` skill. Read the last ten session reports in `reports/` and `fleet/evals/scorecards.md`. Name the one pattern that appears at least twice, cite both occurrences, and say which single file it belongs in. Hand the proposal to `skill-smith`, who opens it as a pull request titled `reinforce: <pattern>`. If nothing repeats, say so and stop.

.github/prompts/triage.prompt.md

@@ -2,4 +2,4 @@
 description: Reproduce, classify, and locate a reported problem.
 agent: triager
 ---
-Triage this: ${input:report:Paste the bug report, failing test name, or command}. Reproduce it first and paste the actual output. Classify it. Locate it as path:line. Hand on with a session report.
+Triage this: ${input:report:Paste the bug report, failing test name, or command}. Reproduce it first and paste the actual output. Classify it. Locate it as path:line. Hand on to `test-writer` with a session report in `reports/`.

CHANGELOG.md

@@ -1,12 +1,49 @@
 # Changelog
 
-All notable changes to the sample application. Format: Keep a Changelog. Versioning: semantic.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: semantic.
 
-## [Unreleased]
-### Fixed
-- (pending) KI-1 — percent discounts were applied as flat amounts.
+Two things are versioned here: the **fleet** (the agents, skills, flows, hooks and tools in this repository) and the **sample application** the fleet works on. Each has its own `[Unreleased]` block.
 
-## [0.1.0] — 2026-09-21
-### Added
+## Fleet
+
+### [Unreleased]
+
+### [0.2.0] — 2026-09-26
+#### Added
+- `tools/hooks/guard.py`, the PreToolUse guard the README describes: denies force-push (DENY[0]), `reset --hard` (DENY[1]), test deselection (DENY[2]) and outbound sends (DENY[3]). Reads both Claude Code and GitHub Copilot hook input.
+- `.github/hooks/guard.json`, the Copilot hook configuration that calls it.
+- `tests/test_guard.py` and `tests/test_require_report.py`.
+- `tools/runner.py`, the container entry point. It prints the plan for one run and exits 2, because the image has no agent CLI yet.
+- Claude Code commands `/sweep`, `/triage` and `/reinforce` in `.claude/commands/`, and the Copilot prompt `.github/prompts/reinforce.prompt.md`.
+- Validator checks: agent name matches filename, loaded skills exist, flow steps and handoffs resolve, `.claude/settings.json` hook scripts exist, each prompt has a matching command, README agent and skill counts match the tree.
+- `.gitattributes`, `llms.txt`, `CITATION.cff`, `SECURITY.md`, `CONTRIBUTING.md`.
+#### Changed
+- Handoff order is `triager` → `test-writer` → `implementer` everywhere (agent, skill, eval case, report, board).
+- `lead`, `quality-auditor`, `reporter` and `triager` have the `edit` tool, each bounded to the one file or folder it writes.
+- The Stop hook uses the Claude Code contract: blocks once with a reason when no report is dated today, otherwise silent.
+- `.claude/settings.json` calls `python "$CLAUDE_PROJECT_DIR"/tools/hooks/...`, so hooks run from any working directory on Windows and Linux.
+- `.github/mcp.json`: GitHub server uses the read-only endpoint; `@playwright/mcp` pinned to 0.0.82 with a named tool list.
+- `deploy/run-once.sh` runs from the repo root, names runs like `reports/`, and refuses to run with unset or `REPLACE_ME` values.
+- The KI-1 demo tells the truth about the `xfail` marker: triage uses `--runxfail` to see the failure.
+- The worked reinforcement example and the seed scorecard rows are labelled as illustrations.
+#### Fixed
+- CI failed on `main`: the validator required `.github/hooks/` files and `guard.py`, which were missing.
+- `tools/validate_fleet.py` crashed on Windows paths; `tools/sync_claude.py --check` reported drift on Windows because of CRLF and the default code page.
+
+### [0.1.0] — 2026-09-21
+- `3be9cac` Reference layout: agents, skills, instructions, corpus, evals, sample app.
+- `aa62079` Flows, the fourth part of the model.
+- `3ae380f` The deploy template and the hosted-runners design.
+- `1367a65` README rewritten around agents, skills, flows and the orchestrator.
+- `d6a2100` The validator fails when the hook files are missing.
+
+## Sample application
+
+### [Unreleased]
+
+### [0.1.0] — 2026-09-21
+#### Added
 - Pricing with flat and percent discounts.
 - Inventory with reservations.
+
+Known issue KI-1 (percent discounts applied as flat amounts) is open on purpose for the triage demo; see `fleet/corpus/known-issues.md`.

CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If you use or adapt this layout, please cite it as below."
+title: "fleet-kit: a reference layout for a bounded agent fleet for Claude Code and GitHub Copilot"
+type: software
+authors:
+  - given-names: Zachary
+    family-names: Allen
+    alias: zacha0dev
+version: 0.2.0
+date-released: 2026-09-26
+license: MIT
+repository-code: "https://github.com/zacha0dev/fleet-kit"
+keywords:
+  - agents
+  - claude-code
+  - github-copilot
+  - mcp
+  - hooks

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Issues and pull requests are welcome.
+
+Before opening a pull request, run the same three checks CI runs:
+
+```bash
+python tools/validate_fleet.py
+python tools/sync_claude.py --check
+python -m pytest -q
+```
+
+- **Agents** are edited in `.github/agents/`. Run `python tools/sync_claude.py` afterwards; never edit `.claude/agents/` by hand.
+- **Fleet changes** (agents, skills, instructions, hooks, flows) use a title starting `fleet:` or `reinforce:`, as `.github/copilot-instructions.md` asks.
+- **Tests first.** A change to `sample_app/` or `tools/` comes with a test in `tests/`. Do not skip or deselect tests to get green.
+- **Claims.** Say what you ran. A statement about behavior outside the repo names the command that shows it.
+- **KI-1** is a seeded bug kept open for the triage demo. Please do not send a fix for it.
+
+By contributing you agree your contribution is released under the MIT license in `LICENSE`.