From ab66895b36b8967bae7da4dfc0b529a35bf5ec38 Mon Sep 17 00:00:00 2001
From: CoderDeltaLAN <CoderDeltaLAN@users.noreply.github.com>
Date: Fri, 19 Jun 2026 00:02:02 +0100
Subject: [PATCH] docs: sync output contract test evidence

---
 CHANGELOG.md       |  2 ++
 docs/EXIT-CODES.md | 16 ++++++++++++++++
 docs/OUTPUTS.md    | 17 +++++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index afd38de..9a537c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,8 @@ This project has a published GitHub Release line, but no stable support or API g
 
 - Added v0.3 architecture and roadmap planning documentation.
 - Added initial output and exit-code contract documentation for existing `check` and `init` behavior and planned v0.3 `doctor`, `budget`, and `explain` commands.
+- Added golden output foundation tests for current `check` and `init` console, JSON, Markdown, stdout, stderr, and exit-code behavior.
+- Added a CLI contract regression matrix for current version, help, `check`, and `init` output channels and exit codes.
 
 ## [0.2.3] - 2026-06-18
 
diff --git a/docs/EXIT-CODES.md b/docs/EXIT-CODES.md
index 8a72fd5..419a6a4 100644
--- a/docs/EXIT-CODES.md
+++ b/docs/EXIT-CODES.md
@@ -103,6 +103,22 @@ Planned direction:
 
 Unknown rule IDs should fail predictably. They should not silently produce generic guidance.
 
+## Test evidence
+
+Current implemented exit-code behavior is covered by `tests/test_golden_outputs.py`.
+
+The contract regression matrix currently checks:
+
+- `agent-rules-kit --version` exits `0`;
+- `agent-rules-kit` without a subcommand exits `0` and prints help;
+- `check` exits `0` when supported instruction files are found;
+- `check` exits `1` when no supported instruction files are found;
+- `check --format json` and `check --format markdown` preserve the same success and no-result exit-code behavior;
+- `init --dry-run` exits `0`;
+- `init` without `--dry-run` or `--write` exits `2` and writes the supported error to stderr.
+
+These tests are evidence for current implemented behavior. They do not turn this pre-v1.0 contract into a stable public API guarantee.
+
 ## Maintenance rules
 
 Update this document when:
diff --git a/docs/OUTPUTS.md b/docs/OUTPUTS.md
index c730448..d75a6b4 100644
--- a/docs/OUTPUTS.md
+++ b/docs/OUTPUTS.md
@@ -34,6 +34,23 @@ It is:
 
 A clean report only means the implemented checks completed according to their documented behavior.
 
+## Test evidence
+
+Current output behavior is covered by `tests/test_golden_outputs.py`.
+
+That test module currently pins representative exact output for:
+
+- `check` console output for a clean fixture;
+- `check --format json` output for a clean fixture;
+- `check` console output for an empty repository;
+- `check --format markdown` output for governance findings;
+- `init --dry-run` console output for an existing root `AGENTS.md`;
+- `init` missing-mode stderr behavior.
+
+It also includes a contract regression matrix for current version, no-command help, `check` console/JSON/Markdown success and no-result behavior, `init --dry-run`, and missing-mode `init` behavior.
+
+This is regression evidence for implemented behavior on current `main`. It is not a stable public API guarantee before v1.0.
+
 ## Output channels
 
 Current behavior: