faf-taf-git 2.3.0 → 2.4.0

package/README.md

@@ -5,557 +5,176 @@
 
 [![TAF](./badge.svg)](https://github.com/Wolfe-Jam/faf-taf-git)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-enabled-00D4D4)](https://github.com/anthropics/claude-code-action)
+[![Business card · Get yours →](https://wolfe-jam.github.io/agent-business-card/badge.svg)](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/faf-taf-git)
 
-## Proof Over Time
+**A receipt printer for your tests.**
 
-Anyone can get green **once.** TAF proves it **over time** — an append-only Test Receipt on every CI run, git-anchored and **cannot be gamed.** Solid engineering shows in the timeline; everything else gets exposed.
+Every time your tests run in CI, faf-taf-git writes a small receipt: when they ran, how many passed, failed and were skipped. The receipts are saved in your repo, one after another, on their own branch. Over time they show whether your tests really kept passing.
 
-**TAF — Testing AI Format.** Sibling of FAF, independent. The Test Receipt Printer for git.
+Anyone can get green once. Receipts show it over time.
 
-> **Q: What does TAF do?** A: It prints Receipts.
-> **Q: What sort of Receipts?** A: Test Receipts.
-> **Q: Why do I need Test Receipts?** A: Proof over time.
->
-> *Bonus: Cannot be gamed.*
+`npm: faf-taf-git` · `GitHub Action: Wolfe-Jam/faf-taf-git` · MIT, free
 
-**TAF is a Receipt Printer for git.** Every CI run prints a receipt to `.taf`. The receipts accumulate on a git branch. The history is append-only. The proof is permanent.
+## Why
 
-**Works on any git repo. No FAF required.** TAF is a standalone product — install the action, get receipts. FAF integration is one of TAF's use cases (see below), not a precondition.
+- **Test results usually vanish.** CI shows today's run, then the log expires. Receipts stay.
+- **You can look back.** When did that test start failing? Was main green before the last release?
+- **Other people can check.** Users, reviewers, auditors and AI agents can read the history themselves instead of taking your word for it.
 
-`npm: faf-taf-git` · `action: Wolfe-Jam/faf-taf-git`
+## What a receipt looks like
 
----
+Receipts are saved in a file called `.taf`, on a branch called `taf-receipts`:
 
-## 🎯 WHAT
-
-**A Test Receipt Printer for git.** Every CI run produces one receipt — timestamp, counts, result, trigger — appended to `.taf` on the `taf-receipts` branch. The timeline is the proof.
-
-**Example Test Receipt:**
 ```yaml
-- timestamp: 2026-02-17T19:12:14.810Z
+- timestamp: 2026-10-29T20:28:58.090Z
   result: PASSED
   tests:
-    total: 808
-    passed: 799
+    total: 628
+    passed: 621
     failed: 0
-    skipped: 9
+    skipped: 7
   trigger: github-actions
 ```
 
-**Every field maps to a real receipt:** timestamp = receipt date, tests = itemized lines, result = total, trigger = cashier/register, run_id = receipt number, project = vendor, format_version = receipt template.
-
-📄 **Full receipt schema:** [`RECEIPT-FORMAT.md`](./RECEIPT-FORMAT.md) — the pinned `.taf` format (fields, the cannot-be-gamed mechanism, where it fits vs JUnit/TAP/SLSA).
-
-**What you get:**
-- **Proof over time** — longitudinal evidence, not snapshots
-- **Pattern detection** — pass-rate trends, regression vs new failure
-- **Platform-agnostic** — works in ANY CI/CD (GitHub Actions, GitLab, Jenkins, CircleCI, Bitbucket, Azure, local, pre-commit)
-- **Git-native** — no external services, no SaaS lock-in
-- **Cannot be gamed** — git SHA detects edits, append-only history detects deletions, CI sandbox prevents output forgery
-
----
-
-## 👥 WHO
-
-**For development teams who need:**
-- Proof of testing over time (not just current state)
-- Git-tracked test accountability (visible in PRs, commits, history)
-- AI-readable test context (feeds into `.faf` project DNA)
-- Platform-agnostic testing receipts (works in ANY CI/CD)
-
-**Use cases:**
-- Open source projects (prove your tests pass)
-- Regulated industries (auditable test history)
-- AI-augmented development (give AI your test timeline)
-- Championship engineering (F1-grade accountability)
-
----
-
-## 🤔 WHY
-
-### The Problem
-Tests run, results disappear. No permanent record. No accountability.
-
-**Before:**
-```
-✅ Tests passing (right now)
-❓ Were they passing yesterday?
-❓ When did that flaky test start failing?
-❓ What's the trend over time?
-```
-
-**After (with .taf):**
-```
-✅ Tests passing (tracked in git)
-✅ History shows: 99% pass rate over 30 days
-✅ Flaky test identified: started failing Feb 10
-✅ Trend: improving (was 85%, now 99%)
-```
-
-### The Solution
-**Git-native receipts.** Every test run becomes a permanent, auditable record.
+`result` is `PASSED` or `FAILED`. The full format is in [RECEIPT-FORMAT.md](./RECEIPT-FORMAT.md).
 
-`.taf` is software accountability - proof that your code works, tracked over time, visible to everyone.
+## Set it up (GitHub Actions)
 
----
-
-## 📍 WHERE
-
-Works in **ANY CI/CD** environment that runs Node.js:
-
-| Platform | Status | Example |
-|----------|--------|---------|
-| **GitHub Actions** | ✅ Tested | See Quick Start |
-| **GitLab CI** | ✅ Tested | `npx faf-taf-git --commit` |
-| **Jenkins** | ✅ Compatible | `sh 'npx faf-taf-git --commit'` |
-| **CircleCI** | ✅ Compatible | `run: npx faf-taf-git --commit` |
-| **Bitbucket Pipelines** | ✅ Compatible | `npx faf-taf-git --commit` |
-| **Travis CI** | ✅ Compatible | `npx faf-taf-git --commit` |
-| **Azure Pipelines** | ✅ Compatible | `npx faf-taf-git --commit` |
-| **Local development** | ✅ Works | `npm test && npx faf-taf-git` |
-| **Pre-commit hooks** | ✅ Works | See Examples |
-
-**Architecture:** Platform-agnostic core. No CI-specific dependencies. Pure functions.
-
----
-
-## ⏰ WHEN
-
-**Use faf-taf-git when you need:**
-
-1. **Proof of testing over time**
-   - Regulated industries (SOC 2, ISO, HIPAA)
-   - Open source credibility (show your tests pass)
-   - Client deliverables (prove quality)
-
-2. **AI-augmented development**
-   - Give AI your test history (feeds `.faf` format)
-   - AI can see: "Tests were 85% passing, now 99%"
-   - Better context = better AI assistance
-
-3. **Debugging flaky tests**
-   - Timeline shows when tests started failing
-   - Pattern detection (fails on Windows only, etc.)
-   - Root cause analysis with historical data
-
-4. **Team accountability**
-   - PRs show test impact (IMPROVED, DEGRADED, etc.)
-   - No hiding broken tests
-   - Git history = test history
-
-**Don't use when:**
-- You only need current test status (use a test reporter)
-- You don't commit to git (TAF is git-native)
-- You're not ready for accountability 😉
-
----
-
-## 🧩 Use Cases
-
-TAF works on any git repo. Adoption requires **zero ecosystem buy-in** — install the action, you get receipts. Below are the use cases TAF serves today and tomorrow:
-
-### Standalone (no FAF required)
-
-| Use Case | What TAF gives you |
-|---|---|
-| **Plain JS/TS projects** | Receipt for every Jest or Vitest run, on every CI execution |
-| **Pytest projects** | Receipt for every Python test run *(pending pytest parser — v2.2 roadmap)* |
-| **Open source maintainers** | "This repo has 1,847 receipts going back 14 months, none missing" |
-| **Regulated industries** (SOC 2, ISO, HIPAA) | Append-only longitudinal evidence — auditors get a tamper-evident timeline, not a snapshot |
-| **Supply-chain trust** | "Prove these tests ran before this artifact shipped" |
-| **AI-agent verification** | "Prove this agent's code passed tests consistently over the last 90 days" |
+Add this to a workflow, for example `.github/workflows/tests.yml`. Swap the install and test lines for your own.
 
-### With FAF (optional integration)
-
-| Use Case | What TAF gives you |
-|---|---|
-| **FAF-aware projects** | Receipts include `faf_score`, `faf_associated`, `faf_location` — the receipt tells you not just *did the tests pass*, but *what was the project's AI-readiness when they ran*. Score trends over time become visible. |
-| **Full CAR Framework** | TAF (Receipt) + WJTTC (Audit) + FAF (Claim) — closed-loop attestation: project DNA → testing audit → permanent receipt |
-
-**FAF is one tenant among many.** TAF is the platform. The receipt printer doesn't care what kind of project prints to it.
-
----
-
-## 🚀 HOW
-
-### Quick Start (GitHub Actions)
-
-**Step 1:** Create `.taf` file
-```bash
-npm install -g faf-cli
-faf taf init
-```
-
-**Step 2:** Add to CI workflow
 ```yaml
 name: Tests
 
 on:
   push:
     branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: tests-${{ github.ref }}   # one run at a time per branch, so receipts never collide
 
 jobs:
   test:
     runs-on: ubuntu-latest
     permissions:
-      contents: write  # Required for auto-commit
+      contents: write              # lets the action save receipts
 
     steps:
       - uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: '24.x'
+      - run: npm ci
 
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Tests and Capture Output
-        run: npm test 2>&1 | tee test-output.txt
+      - name: Run tests
+        id: tests
+        continue-on-error: true    # keep going, so a failed run still gets a receipt
+        run: |
+          set -o pipefail
+          npm test 2>&1 | tee test-output.txt
 
-      - name: Generate TAF Receipt
-        uses: Wolfe-Jam/faf-taf-git@v2.3.0
+      - name: Print the receipt
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: Wolfe-Jam/faf-taf-git@v2.4.0
         with:
           test-output-file: test-output.txt
-          auto-commit: 'true'
-          commit-message: 'chore(taf): update .taf receipt [skip ci]'
-```
-
-**Step 3:** Push and watch
-- Tests run automatically
-- `.taf` file updates with new entry
-- Changes committed back to repo
-- History tracked in git
-
-### Standalone CLI (Any Platform)
-
-```bash
-# Run tests and update .taf
-npm test 2>&1 | tee test-output.txt
-npx faf-taf-git --file test-output.txt --commit
-
-# Or in one command (legacy v1.x CLI)
-npx faf-taf-git --command "npm test" --commit
-```
-
-### GitLab CI
-
-```yaml
-test:
-  script:
-    - npm ci
-    - npm test 2>&1 | tee test-output.txt
-    - npx faf-taf-git --file test-output.txt --commit --message "ci: update .taf [skip ci]"
-```
-
-### Jenkins
-
-```groovy
-stage('Test') {
-  steps {
-    sh 'npm ci'
-    sh 'npm test 2>&1 | tee test-output.txt'
-    sh 'npx faf-taf-git --file test-output.txt --commit'
-  }
-}
-```
-
-### Local Development
-
-```bash
-# Run tests and update .taf (no commit)
-npm test 2>&1 | tee test-output.txt
-npx faf-taf-git --file test-output.txt --verbose
+          target-branch: taf-receipts
 
-# Pre-commit hook
-#!/bin/bash
-npm test 2>&1 | tee test-output.txt && npx faf-taf-git --file test-output.txt
+      - name: Fail the job if the tests failed
+        if: steps.tests.outcome == 'failure'
+        run: exit 1
 ```
 
----
+That's it. The first run creates the `taf-receipts` branch for you.
 
-## 🎨 HOW IT WORKS
+**Four things this recipe gets right:**
 
-### v2.0.0+ Architecture (Pre-Capture Pattern)
+1. **Failed runs get a receipt too.** A red run is recorded as `FAILED`, not left out. A history with only green runs proves less.
+2. **Only `main` gets receipts.** Pull requests and other branches still run the tests, but the record is about `main`.
+3. **The job still goes red** when tests fail, so your checks stay honest.
+4. **Tests run once.** The receipt reads the output of the run that just happened.
 
-```
-Step 1: Run Tests              Step 2: Generate Receipt
-┌─────────────────────┐        ┌──────────────────────┐
-│ npm test 2>&1 |     │        │ faf-taf-git reads    │
-│ tee test-output.txt │───────▶│ test-output.txt and  │
-│                     │        │ updates .taf file    │
-└─────────────────────┘        └──────────────────────┘
-```
-
-**Why separate steps?**
-- Avoids GitHub Actions execution context corruption
-- More reliable (tested 19 methods before this breakthrough)
-- Platform-agnostic (works in ANY CI/CD)
-- Simpler architecture (400+ lines removed)
-
-**Process:**
-1. **Capture output** - `npm test 2>&1 | tee test-output.txt`
-2. **Parse results** - Extracts test counts from Jest output
-3. **Update .taf** - Appends new test run to timeline
-4. **Commit** - Optionally commits changes to git
-
----
-
-## 📋 API
-
-### GitHub Action Inputs
-
-| Input | Description | Default | Required |
-|-------|-------------|---------|----------|
-| `test-output-file` | Path to file containing test output | - | ✅ Yes |
-| `auto-commit` | Automatically commit .taf updates | `true` | No |
-| `commit-message` | Custom commit message | `chore(taf): update .taf receipt [skip ci]` | No |
-
-### GitHub Action Outputs
-
-| Output | Description | Example |
-|--------|-------------|---------|
-| `result` | Test result | `PASSED`, `FAILED`, `IMPROVED`, `DEGRADED` |
-| `passed` | Number of tests passed | `799` |
-| `failed` | Number of tests failed | `0` |
-| `total` | Total number of tests | `808` |
-| `skipped` | Number of skipped tests | `9` |
-| `taf-updated` | Whether .taf was updated | `true` or `false` |
-
-### CLI Options
-
-```bash
-npx faf-taf-git [options]
-
-Options:
-  --file <path>       Path to test output file (v2.0.0+)
-  --command <cmd>     Test command to run (legacy v1.x)
-  --commit            Auto-commit .taf changes
-  --message <msg>     Custom commit message
-  --cwd <dir>         Working directory
-  --verbose, -v       Verbose output
-  --help, -h          Show help
-```
-
----
-
-## 🧪 Test Framework Support
-
-| Framework | Status | Notes |
-|-----------|--------|-------|
-| **Jest** | ✅ Fully supported | All output formats |
-| **Vitest** | ✅ Fully supported | Including todo counts |
-| Mocha | ⏳ Planned | - |
-| Pytest | ⏳ Planned | - |
-| Go test | ⏳ Planned | - |
-| Rust cargo test | ⏳ Planned | - |
-
----
+If your tests run on several operating systems, print the receipt from the one that runs the most tests.
 
-## 🎓 Examples
+## Works with your test runner
 
-### Using Outputs
-
-```yaml
-- name: Generate TAF Receipt
-  id: taf
-  uses: Wolfe-Jam/faf-taf-git@v2.3.0
-  with:
-    test-output-file: test-output.txt
-
-- name: Check Results
-  run: |
-    echo "Result: ${{ steps.taf.outputs.result }}"
-    echo "Tests: ${{ steps.taf.outputs.passed }}/${{ steps.taf.outputs.total }} passing"
-    if [ "${{ steps.taf.outputs.result }}" == "DEGRADED" ]; then
-      echo "⚠️ Test quality degraded!"
-      exit 1
-    fi
-```
+| Runner | What to give the action |
+|---|---|
+| **Python (pytest)** | `pytest --junitxml=report.xml`, then `test-output-file: report.xml` |
+| **Any runner that writes JUnit XML** | the XML report file (Rust with `cargo nextest`, Go with `gotestsum --junitfile`, Java with Maven or Gradle, .NET, PHPUnit, Jest with `jest-junit`) |
+| **Jest** | the console output (`npm test 2>&1 \| tee test-output.txt`) |
+| **Vitest** | the console output |
+| **Bun** | the console output of `bun test` |
+| **WJTTC** | the console output |
 
-### CircleCI
+JUnit XML is the common report format most test runners can write. If your runner isn't in the table, check whether it can write JUnit XML.
 
-```yaml
-version: 2.1
-
-jobs:
-  test:
-    docker:
-      - image: node:20
-    steps:
-      - checkout
-      - run: npm ci
-      - run: npm test 2>&1 | tee test-output.txt
-      - run: npx faf-taf-git --file test-output.txt --commit
-```
+## Other CI systems
 
-### Pre-commit Hook
+The command-line tool does the same job anywhere Node.js runs (GitLab, Jenkins, CircleCI, Bitbucket, Azure, your own machine):
 
 ```bash
-#!/bin/bash
-# .git/hooks/pre-commit
-
-# Run tests and capture output
 npm test 2>&1 | tee test-output.txt
-TEST_EXIT=$?
-
-# Update .taf (don't commit yet - that's what the commit is for!)
-npx faf-taf-git --file test-output.txt
-
-# Exit with test status
-exit $TEST_EXIT
-```
-
----
-
-## 🏆 The Golden Triangle
-
-Projects with `.faf` + `repo` + `.taf` are **engineered to succeed**:
-
-```
-       .faf
-     (WHAT IT IS)
-         /    \
-        /      \
-       /        \
-    repo    ←→   .taf
-(IMPLEMENTATION) (PROOF IT WORKS)
+npx faf-taf-git --file test-output.txt --commit
 ```
 
-- **.faf** - Tells AI what the repo is (better than prose)
-- **repo** - The implementation (code doesn't lie)
-- **.taf** - Proves it works (receipts don't negotiate)
-
-**Why this matters:**
-- AI reads `.faf` to understand your project
-- AI reads `.taf` to understand test quality
-- Better context = better AI assistance
-- Accountability built in
-
----
+`--commit` commits the updated `.taf` for you. Leave it off to just update the file.
 
-## 🔧 Development
+## Read your receipts
 
-### Build
 ```bash
-npm run build
+git fetch origin taf-receipts
+git show origin/taf-receipts:.taf
 ```
 
-### Test
-```bash
-npm test
-```
-
-### Package (GitHub Action)
-```bash
-npm run package  # Creates bundled dist/index.js
-```
+Make a badge for your README:
 
-### Test Locally
 ```bash
-npm run build
-node dist/cli.js --help
+npx faf-taf-git badge --output badge.svg
 ```
 
----
-
-## 📖 Migration from v1.x
-
-**v2.0.0 is a breaking change** - the architecture was redesigned for reliability.
+## Settings
 
-### What Changed
+**Action inputs**
 
-**v1.x (test-command):**
-```yaml
-- uses: Wolfe-Jam/faf-taf-git@v1
-  with:
-    test-command: npm test
-```
-
-**v2.x (test-output-file):**
-```yaml
-- run: npm test 2>&1 | tee test-output.txt
-
-- uses: Wolfe-Jam/faf-taf-git@v2.3.0
-  with:
-    test-output-file: test-output.txt
-```
+| Input | What it does | Default |
+|---|---|---|
+| `test-output-file` | The file with your test output or JUnit XML report | required |
+| `target-branch` | The branch receipts are saved to. Use `taf-receipts`. | the current branch |
+| `auto-commit` | Commit and push the receipt | `true` |
+| `commit-message` | The commit message | `chore(taf): update .taf receipt [skip ci]` |
 
-### Why the Change
+**Action outputs:** `result`, `passed`, `failed`, `skipped`, `total`, `taf-updated`. For example, `${{ steps.taf.outputs.passed }}`.
 
-v1.x ran tests inside the action using `@actions/exec`. This caused:
-- GitHub Actions execution context corruption
-- Logging failures (tested 19 different methods)
-- Filesystem operations failing silently
-- Unreliable receipt generation
+**Command-line options:** `--file`, `--commit`, `--message`, `--cwd`, `--verbose`. Run `npx faf-taf-git --help` for the full list.
 
-v2.0.0 uses **pre-capture pattern** - separate test execution from receipt generation. This is:
-- ✅ More reliable (no execution context issues)
-- ✅ Platform-agnostic (works everywhere)
-- ✅ Simpler (400+ lines removed, 11KB smaller)
-- ✅ Production-ready (tested thoroughly)
+## How hard is it to fake?
 
-### Migration Steps
+Receipts are written by CI from the real test output and saved in git. Editing or deleting an old receipt changes the git history, so anyone comparing the history can see it. The `taf-receipts` branch only ever grows: never rewrite, squash or force-push it.
 
-1. Update workflow to use `test-output-file` instead of `test-command`
-2. Add test output capture step: `npm test 2>&1 | tee test-output.txt`
-3. Update version to `@v2.3.0`
+A receipt proves the tests passed on that commit. It does not prove a published package was built from that exact commit.
 
-See [CHANGELOG.md](CHANGELOG.md) for complete version history.
+## With FAF (optional)
 
----
+faf-taf-git works on any git repo; you don't need anything else. If your project also uses [FAF](https://faf.one) (a `project.faf` file describing the project for AI), the two fit together: `project.faf` says what the project is, and `.taf` shows its tests kept passing.
 
-## 🤝 Contributing
+## Upgrading from v1
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+v1 ran your tests inside the action. v2 reads a file your own test step wrote. Replace `test-command:` with a test step that saves its output, and point `test-output-file:` at that file (see the setup above).
 
----
+## Develop
 
-## 📚 Learn More
-
-- [FAF CLI](https://npmjs.com/package/faf-cli) - Create and manage `.faf` files (one of TAF's use cases)
-- [MCP Server](https://npmjs.com/package/claude-faf-mcp) - Claude MCP integration
-- [Website](https://faf.one) - Official FAF website
-- [GitHub Discussions](https://github.com/Wolfe-Jam/faf/discussions) - Ask questions
-
----
-
-## 🛣️ Standards Roadmap
-
-| Format | IANA Status |
-|---|---|
-| `application/vnd.faf+yaml` (FAF) | ✅ **Registered** |
-| `application/vnd.fafm+yaml` (VML) | 🟡 **Under review** |
-| `application/vnd.taf+yaml` (TAF) | ⏳ **Queued** |
-
-`.taf` is filed entirely on its own merits — append-only test provenance, git-tracked, tamper-evident — independent of `.faf`'s registration.
-
----
-
-If `faf-taf-git` has been useful, consider starring the repo — it helps others find it.
-
-## 📄 License
-
-MIT - FREE FOREVER
-
----
-
-## 💎 Philosophy
-
-**Software Accountability**
-
-This tool implements a paradigm shift:
-
-**Before:** Tests run → results disappear → no permanent record
+```bash
+npm ci
+npm test          # the test suite
+npm run build     # rebuilds dist/, which the action runs
+```
 
-**After:** Tests run → `.taf` updated → git-tracked forever
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).
 
-`.taf` is about accountability. Proof that your code works. Tracked over time. Visible to everyone.
+## License
 
-**Built with championship standards. F1-inspired engineering. Methodically tested.**
+MIT. Free forever.
 
-*Platform-agnostic core. Works everywhere. Trust the format.*
+If faf-taf-git is useful to you, a star helps other people find it.

package/action.yml

@@ -1,5 +1,5 @@
 name: 'TAF — Testing AI Format'
-description: 'TAF (Testing AI Format) — the Test Receipt Printer for git. Prints a Test Receipt to .taf on every CI run: append-only, cannot be gamed. Proof over time.'
+description: 'A Test Receipt Printer for git. Every CI run prints a receipt to .taf — append-only, cannot be gamed. Proof over time.'
 author: 'wolfejam'
 
 branding:
@@ -39,6 +39,9 @@ outputs:
   total:
     description: 'Total number of tests'
 
+  skipped:
+    description: 'Number of tests skipped'
+
   taf-updated:
     description: 'Whether .taf file was updated (true/false)'