docs: sync dedupe and conflicts contracts

CHANGELOG.md

@@ -9,6 +9,7 @@ This project has a published GitHub Release line, but no stable support or API g
 ### Added
 
 - Added a read-only `dedupe` baseline command for deterministic duplicate instruction-line detection across supported instruction files.
+- Added a read-only `conflicts` baseline command for deterministic contradictory-guidance detection across supported instruction files.
 - Added an OpenSSF Scorecard evaluation record with current official workflow constraints and a deferred workflow decision.
 - Added a dependency graph and Dependabot settings record with manual GitHub UI evidence and deferred version-update policy.
 - Added a private vulnerability reporting verification record and documented that GitHub private vulnerability reporting is enabled after manual UI verification.

README.md

@@ -151,6 +151,7 @@ The implemented behavior includes:
 - provides read-only `budget` local size and context-pressure approximation output on `main`;
 - provides read-only `explain` output for known governance rule IDs on `main`;
 - provides read-only `dedupe` duplicate instruction-line detection on `main`;
+- provides read-only `conflicts` contradictory-guidance detection on `main`;
 - redacts supported secret-like values in supported output, including finding messages, paths, and evidence payloads;
 - avoids network calls;
 - avoids LLM calls;
@@ -257,6 +258,8 @@ The v0.3.0 commands can also be tested from the source tree:
 
     PYTHONPATH=src python -m agent_rules_kit.cli doctor tests/fixtures/repositories/multi-agent-overlap
     PYTHONPATH=src python -m agent_rules_kit.cli budget tests/fixtures/repositories/multi-agent-overlap
+    PYTHONPATH=src python -m agent_rules_kit.cli dedupe tests/fixtures/repositories/multi-agent-overlap
+    PYTHONPATH=src python -m agent_rules_kit.cli conflicts tests/fixtures/repositories/multi-agent-overlap
     PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003
 
 These source-tree commands are development checks. Published-package behavior must be verified from a clean PyPI install during release closeout.
@@ -372,14 +375,22 @@ If root `AGENTS.md` already exists, it is backed up before replacement:
 
 The first baseline is conservative: it detects repeated normalized lines across files, not broad semantic duplication.
 
+### Conflicts command
+
+`conflicts` reports contradictory guidance across supported instruction files:
+
+    PYTHONPATH=src python -m agent_rules_kit.cli conflicts tests/fixtures/repositories/multi-agent-overlap
+
+The first baseline is conservative: it detects implemented pattern families for opposite guidance, not broad semantic contradiction.
+
 ### Explain command
 
 `explain` lists or explains known local governance rule IDs:
 
     PYTHONPATH=src python -m agent_rules_kit.cli explain AIRK-GOV003
     PYTHONPATH=src python -m agent_rules_kit.cli explain --list
 
-These commands are part of the v0.3.0 command surface.
+These commands are implemented on current `main`. `doctor`, `budget`, and `explain` are part of the published v0.3.0 command surface. `dedupe` and `conflicts` are post-v0.3.0 `main` additions until the next release is cut and verified.
 
 ---
 
@@ -457,6 +468,8 @@ See:
     │       ├── __init__.py
     │       ├── budget.py
     │       ├── cli.py
+    │       ├── conflicts.py
+    │       ├── dedupe.py
     │       ├── discovery.py
     │       ├── explain.py
     │       ├── findings.py
@@ -521,7 +534,7 @@ Current status:
 - release tag `v0.3.0` points to the verified release SHA;
 - local CLI behavior implemented;
 - governance diagnostics, structured finding evidence, and evidence redaction are implemented;
-- `doctor`, `budget`, and `explain` are implemented as v0.3.0 commands;
+- `doctor`, `budget`, and `explain` are implemented as v0.3.0 commands, while `dedupe` and `conflicts` are implemented on current `main` as post-v0.3.0 read-only command additions;
 - CI active;
 - branch protection is active with the required `local-checks / Python 3.12` status check;
 - the `pypi` GitHub environment exists for the release publishing workflow;

docs/EXIT-CODES.md

@@ -67,6 +67,34 @@ Notes:
 - `budget` does not perform tokenizer-specific counting, remote tokenization, LLM calls, pricing estimates, or optimization claims.
 - `Approximate words` is not a model token count.
 
+### `dedupe`
+
+| Condition | Exit code | Stdout | Stderr |
+| --- | ---: | --- | --- |
+| Supported instruction files found | `0` | Console duplicate-line report | Empty unless lower-level runtime fails unexpectedly |
+| No supported instruction files found | `1` | Console no-result duplicate-line summary | Empty unless lower-level runtime fails unexpectedly |
+| Invalid repository input, unsupported instruction-file input, or command-line usage error | `2` | Empty | Error message or argparse-dependent |
+
+Notes:
+
+- `dedupe` is read-only.
+- `dedupe` uses deterministic local normalization only.
+- `dedupe` detects repeated normalized lines across supported instruction files, not broad semantic duplication.
+
+### `conflicts`
+
+| Condition | Exit code | Stdout | Stderr |
+| --- | ---: | --- | --- |
+| Supported instruction files found | `0` | Console contradictory-guidance report | Empty unless lower-level runtime fails unexpectedly |
+| No supported instruction files found | `1` | Console no-result conflict summary | Empty unless lower-level runtime fails unexpectedly |
+| Invalid repository input, unsupported instruction-file input, or command-line usage error | `2` | Empty | Error message or argparse-dependent |
+
+Notes:
+
+- `conflicts` is read-only.
+- `conflicts` uses deterministic local pattern families only.
+- `conflicts` detects implemented opposite-guidance patterns, not broad semantic contradiction.
+
 ### `explain`
 
 | Condition | Exit code | Stdout | Stderr |
@@ -108,9 +136,9 @@ Notes:
 - It backs up an existing root `AGENTS.md` before replacement.
 - It must remain explicit and separate from read-only diagnosis commands.
 
-## Planned v0.3 exit-code direction
+## Planned command exit-code direction
 
-No remaining v0.3 command exit-code target is documented here after the `explain` baseline. Future release or documentation phases must update this file only from verified behavior.
+No remaining planned command exit-code target is documented here. Future release or documentation phases must update this file only from verified behavior.
 
 ## Test evidence
 
@@ -127,6 +155,10 @@ The contract regression matrix currently checks:
 - `doctor` exits `1` when no supported instruction files are found;
 - `budget` exits `0` when supported instruction files are found;
 - `budget` exits `1` when no supported instruction files are found;
+- `dedupe` exits `0` when supported instruction files are found;
+- `dedupe` exits `1` when no supported instruction files are found;
+- `conflicts` exits `0` when supported instruction files are found;
+- `conflicts` exits `1` when no supported instruction files are found;
 - `explain --list` exits `0`;
 - `explain RULE_ID` exits `0` for known rule IDs;
 - `explain RULE_ID` exits `2` for unknown rule IDs;

docs/OUTPUTS.md

@@ -2,7 +2,7 @@
 
 This document describes the current `agent-rules-kit` CLI output contract and representative output examples.
 
-The contract is intentionally narrow. It documents implemented behavior on current `main` and the planned v0.3 command direction without promising a stable public API before v1.0.
+The contract is intentionally narrow. It documents implemented behavior on current `main` without promising a stable public API before v1.0.
 
 ## Scope
 
@@ -14,9 +14,11 @@ Implemented command surface:
 - `agent-rules-kit init --write`;
 - `agent-rules-kit doctor`;
 - `agent-rules-kit budget`;
+- `agent-rules-kit dedupe`;
+- `agent-rules-kit conflicts`;
 - `agent-rules-kit explain`.
 
-`doctor`, `budget`, and `explain` are implemented as v0.3.0 command baselines. Release publication is verified by the dedicated GitHub Release and PyPI workflow evidence, not by this output contract alone.
+`doctor`, `budget`, and `explain` are implemented as v0.3.0 command baselines. `dedupe` and `conflicts` are implemented on current `main` after v0.3.0 and must not be described as published package behavior until the next release is cut and verified. Release publication is verified by the dedicated GitHub Release and PyPI workflow evidence, not by this output contract alone.
 
 ## Contract status
 
@@ -71,6 +73,8 @@ Future behavior should preserve that distinction unless a dedicated phase change
 | `init --write` | console | yes | Explicit write mode with backup behavior for existing root `AGENTS.md`. |
 | `doctor` | console | yes | Read-only repository-level diagnosis summary. |
 | `budget` | console | yes | Read-only local size and context-pressure approximation. |
+| `dedupe` | console | yes | Read-only duplicate instruction-line detection. |
+| `conflicts` | console | yes | Read-only contradictory-guidance detection. |
 | `explain` | console | yes | Read-only local governance rule explanation command. |
 
 ## Exit codes
@@ -92,6 +96,12 @@ Summary for current implemented commands:
 | `budget` | `0` | Budget approximation completed for supported instruction files. |
 | `budget` | `1` | No supported instruction files were found. |
 | `budget` | `2` | Invalid repository input, unsupported instruction-file input, or command-line usage error. |
+| `dedupe` | `0` | Duplicate-line detection completed for supported instruction files. |
+| `dedupe` | `1` | No supported instruction files were found. |
+| `dedupe` | `2` | Invalid repository input, unsupported instruction-file input, or command-line usage error. |
+| `conflicts` | `0` | Contradictory-guidance detection completed for supported instruction files. |
+| `conflicts` | `1` | No supported instruction files were found. |
+| `conflicts` | `2` | Invalid repository input, unsupported instruction-file input, or command-line usage error. |
 | `explain` | `0` | Known rule listed or explained. |
 | `explain` | `2` | Unknown rule ID, conflicting input, missing input, or command-line usage error. |
 
@@ -245,6 +255,46 @@ Current `budget` exit-code behavior:
 
 `Approximate words` is a local whitespace-based approximation, not a model token count.
 
+## Dedupe output contract
+
+Current `dedupe` console output includes:
+
+- command header;
+- status line;
+- supported instruction file count;
+- duplicate group count;
+- duplicate line count;
+- duplicate groups with locations when repeated normalized lines are detected;
+- short next-step guidance.
+
+Current `dedupe` exit-code behavior:
+
+- `0`: duplicate-line detection completed and supported instruction files were found;
+- `1`: no supported instruction files were found;
+- `2`: invalid repository input, unsupported instruction-file input, or command-line usage error.
+
+`dedupe` is read-only. It detects repeated normalized lines across supported instruction files. It does not perform semantic duplication analysis.
+
+## Conflicts output contract
+
+Current `conflicts` console output includes:
+
+- command header;
+- status line;
+- supported instruction file count;
+- conflict group count;
+- conflict line count;
+- conflict groups with allowing and blocking guidance locations when implemented opposite-guidance patterns are detected;
+- short next-step guidance.
+
+Current `conflicts` exit-code behavior:
+
+- `0`: contradictory-guidance detection completed and supported instruction files were found;
+- `1`: no supported instruction files were found;
+- `2`: invalid repository input, unsupported instruction-file input, or command-line usage error.
+
+`conflicts` is read-only. It detects implemented deterministic pattern families for opposite guidance. It does not perform broad semantic contradiction analysis.
+
 ## Explain output contract
 
 Current `explain` console output includes either: