Skip to content

docs: sync output contract test evidence #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CoderDeltaLAN merged 1 commit into from
Jun 18, 2026
Merged

docs: sync output contract test evidence #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 16 additions & 0 deletions docs/EXIT-CODES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
17 changes: 17 additions & 0 deletions docs/OUTPUTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down