shockharness 0.1.0a1__tar.gz

shockharness-0.1.0a1/.gitignore

@@ -0,0 +1,20 @@
+# Environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+
+# macOS
+.DS_Store

shockharness-0.1.0a1/.shockharness.toml

@@ -0,0 +1,120 @@
+# ShockHarness analyzing itself. Every exemption below is deliberate and reported.
+# See agent_code_integrity_project_spec.md section 15.5 for the bootstrapping policy.
+
+[tool.shockharness]
+profile = "strict"
+include = ["src/**/*.py", "tests/**/*.py"]
+exclude = ["**/.venv/**", "**/node_modules/**", "**/dist/**", "**/build/**", "tests/fixtures/**"]
+parse_errors = "fail"
+
+[tool.shockharness.rules.magic_numbers]
+enabled = true
+allowed_values = [0, 1]
+allow_unary_negative_one = false
+exclude_configuration_files = false
+
+[tool.shockharness.rules.exceptions]
+enabled = true
+mode = "boundary_whitelist"
+
+# Declared boundaries where the tool meets the outside world. Each converts the
+# named failure into a typed analyzer diagnostic; none may swallow it.
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/config.py"
+language = "python"
+exception = "OSError"
+reason = "Reading a configuration file is I/O; failure becomes a ConfigError (exit 2)"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/config.py"
+language = "python"
+exception = "tomllib.TOMLDecodeError"
+reason = "Config file content is external input; decode failure becomes a ConfigError (exit 2)"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/config.py"
+language = "python"
+exception = "UnicodeDecodeError"
+reason = "Config file bytes are external input; non-UTF-8 becomes a ConfigError (exit 2)"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/analysis.py"
+language = "python"
+exception = "OSError"
+reason = "Reading analyzed files is I/O; failure becomes a per-file read_error status, never a pass"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/analysis.py"
+language = "python"
+exception = "UnicodeDecodeError"
+reason = "Analyzed source is external bytes; undecodable input becomes a decode_error file status"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/ir/python.py"
+language = "python"
+exception = "SyntaxError"
+reason = "ast.parse and tokenize on external source; failure becomes a ParseFailure fact feeding the parse_errors gate"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/ir/python.py"
+language = "python"
+exception = "ValueError"
+reason = "ast.parse raises ValueError for NUL bytes on 3.11 and tokenize raises UnicodeDecodeError (a ValueError) on some CR sequences; both become a ParseFailure"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/ir/python.py"
+language = "python"
+exception = "tokenize.TokenError"
+reason = "Comment extraction tokenizes external source; failure becomes a ParseFailure fact"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/cli.py"
+language = "python"
+exception = "OSError"
+reason = "Writing the report or init file to a user path is I/O; failure becomes a UsageError (exit 2)"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/cli.py"
+language = "python"
+exception = "shockharness.errors.ShockHarnessError"
+reason = "Process boundary: typed configuration and usage errors print one line and exit 2"
+
+[[tool.shockharness.rules.exceptions.boundaries]]
+path = "src/shockharness/cli.py"
+language = "python"
+exception = "Exception"
+reason = "Process boundary: an unexpected internal failure prints its full traceback and exits 3 instead of Python's default 1; nothing is hidden"
+
+[tool.shockharness.rules.defaults]
+enabled = true
+function_parameters = "forbid"
+dataclass_fields = "forbid"
+missing_value_fallbacks = "forbid"
+truthiness_fallbacks = "review"
+nullish_fallbacks = "forbid"
+configuration_fallbacks = "forbid"
+
+[tool.shockharness.rules.magic_strings]
+enabled = true
+mode = "review"
+
+[tool.shockharness.complexity]
+enabled = true
+cognitive_warn = 15
+cyclomatic_warn = 15
+max_nesting_warn = 4
+
+[tool.shockharness.gates]
+new_hard_violations = "fail"
+legacy = "baseline"
+complexity_regressions = "warn"
+
+[[tool.shockharness.overrides]]
+paths = ["src/shockharness/constants.py"]
+disable = ["MAGIC001"]
+reason = "Single designated module holding every numeric constant the tool needs (exit codes, schema version, caps)"
+
+[[tool.shockharness.overrides]]
+paths = ["tests/**"]
+disable = ["MAGIC001", "DEF001"]
+reason = "Test code encodes literal expected outputs and pytest fixture signatures"

shockharness-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to ShockHarness. Format follows Keep a Changelog; versions
+follow Semantic Versioning. The report `schema_version` is tracked separately.
+
+## [Unreleased]
+
+### Added
+- Milestone A: package skeleton, MIT license, configuration schema with full
+  shape and semantic validation, precedence (`--config` > `.shockharness.toml` >
+  `pyproject.toml` > bundled defaults), rule registry with every specified rule
+  ID, diagnostic and report models, `scan`, `config validate`, `config effective`,
+  `rules list`, `rules explain`, `init`, exit-code contract, GitHub Actions matrix.
+- Milestone B: Python (`ast`) and JavaScript (tree-sitter) adapters with
+  byte-to-character column mapping, explicit parse-failure propagation,
+  `MAGIC001` (value-based 0/1, folded unary sign, annotations flagged),
+  `SUPP001`/`SUPP002` inline suppression checks, per-path overrides,
+  configuration-file exemption, JSON report (`schema_version` 1) and text output.
+- Milestone C: catch facts in the IR (exception identities with
+  exact/approximate/unresolved confidence, handler body classification,
+  try-body operation attribution) for Python `except`/`except*` and JavaScript
+  `catch`, `.catch(handler)`, `.then(ok, handler)`; `EXC001` forbidden catch
+  (boundary whitelist, fail-closed on bare/unresolved identities, JavaScript
+  instanceof-guard convention), `EXC002` suppressed or converted exception,
+  `EXC003` broad try scope; `rules.exceptions.transparent_rethrow` (default
+  false); boundary `exception` names validated as dotted class names; every
+  boundary and `transparent_rethrow` reported under `config.deviations`.
+- Milestone D: default facts in the IR (`DefaultFact`: family, kind, subject,
+  fallback, constant-shapedness, syntactic context, confidence) extracted by
+  `ir/python_defaults.py` and `ir/javascript_defaults.py`; `DEF001` parameter
+  and dataclass-field defaults, `DEF002` mapping/attribute/property fallbacks
+  (plus the implicit `None` of `.get(key)` as a review finding), `DEF003`
+  truthiness fallbacks (review by default; Boolean logic excluded), `DEF004`
+  nullish fallbacks, `DEF005` exception-to-default (literal returns and
+  one-step static traces to module constants and one-return helpers), `DEF006`
+  configuration fallbacks (`os.getenv`/`os.environ`/`process.env` in every
+  spelling); new `rules.defaults` keys `dataclass_fields`, `nullish_fallbacks`,
+  `configuration_fallbacks` (all `forbid`); loosened modes reported under
+  `config.deviations`; 13 golden fixtures and 25 unit tests; `safe_autofix` is
+  false for every finding.
+
+### Changed
+- `EXC002` no longer reports the `return_fallback` classification while `DEF005`
+  is active: the handler is reported once, as `DEF005`, with the EXC002
+  classification named in the message. Disabling `DEF005` restores the EXC002
+  finding. Golden expectations for the eleven affected handlers changed rule ID
+  only.
+- The tool's own code was brought under `DEF002`/`DEF004`: three `setdefault`
+  accumulators became explicit membership checks, the report's
+  `discovery`/`explicit_targets_excluded` fields are built with an explicit
+  branch, and nineteen `x if x is not None else v` expressions on parser fields
+  became either explicit branches (genuinely optional values: import aliases,
+  `from . import`, source segments) or assertions of grammar invariants (fields
+  tree-sitter and `ast` always populate). A Python `SyntaxError` position is now
+  recorded only when the interpreter reports both a line and a column; before,
+  a missing column was silently replaced by column 1.
+- The arities that distinguish `getattr(o, a, v)` and `m.get(k, v)` from plain
+  lookups are named in `constants.py`.
+- The tool's own boundaries were narrowed to satisfy `EXC003`: config decoding
+  and TOML parsing are two `try` blocks, analyzed-file decoding is bound before
+  the result is returned, and comment tokenization materializes the token list
+  in the one protected call. Behaviour is unchanged.
+
+### Dependencies
+- `tree-sitter` 0.25.x (MIT) and `tree-sitter-javascript` 0.25.x (MIT). Pinned
+  as a tested pair; language ABI 15. `tree-sitter` 0.26.0 is excluded: with
+  CPython 3.14 it segfaults when walking trees nested deeper than about 200
+  levels (CPython 3.13 with 0.26.0 and CPython 3.14 with 0.25.2 are both fine).
+  The 300-deep nesting test in `tests/unit/test_javascript_adapter.py` guards this.

shockharness-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Lahore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shockharness-0.1.0a1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: shockharness
+Version: 0.1.0a1
+Summary: Strict static-analysis quality gate for Python and JavaScript: no silent failures, no implicit defaults, no magic numbers.
+Project-URL: Homepage, https://github.com/evolvingstuff/ShockHarness
+Project-URL: Repository, https://github.com/evolvingstuff/ShockHarness
+Project-URL: Issues, https://github.com/evolvingstuff/ShockHarness/issues
+Project-URL: Changelog, https://github.com/evolvingstuff/ShockHarness/blob/main/CHANGELOG.md
+Author: Thomas Lahore
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,exceptions,linter,magic-numbers,quality-gate,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: tree-sitter-javascript<0.26,>=0.25
+Requires-Dist: tree-sitter<0.26,>=0.25.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ShockHarness
+
+A strict, deterministic static-analysis quality gate for Python and JavaScript.
+Its one idea: unexpected failures, missing information, and unexplained
+decisions must not silently become apparently valid program behavior.
+
+Three default-on hard policies:
+
+1. **Exception transparency.** No catch except at narrow, explicitly approved
+   external boundaries. No catch-and-continue, no success-shaped fallbacks.
+2. **No implicit defaults.** No fallback values for missing required data, no
+   function-parameter defaults in strict mode.
+3. **No magic numbers.** Every numeric literal in executable code must be
+   exactly `0` or `1`. `range(2)` is a violation. The tool invents no exemptions.
+
+Plus a separate, advisory complexity family (cyclomatic, cognitive, nesting,
+NPath, call graph, churn). Hard violations are never averaged into a score.
+
+ShockHarness complements Ruff and ESLint; it is not a formatter or a general
+linter. It runs offline, needs no LLM, and never uploads source.
+
+## Status
+
+Pre-release. Milestones A (skeleton and contracts), B (parsers and
+`MAGIC001`), C (exception rules `EXC001`-`EXC003`) and D (default and fallback
+rules `DEF001`-`DEF006`) are implemented. `MAGIC002`, complexity, baselines,
+SARIF, and agent skills are registered but **not yet implemented**; every
+report lists them under `rules_not_implemented` so a clean run never implies
+coverage the tool does not have. See `STATUS.md` for exact evidence.
+
+Implemented rules:
+
+| ID | What it reports | Default |
+|---|---|---|
+| `MAGIC001` | numeric literal other than `0`/`1` in executable code | error |
+| `EXC001` | catch outside an approved boundary (bare, broad, unresolved, untyped) | error |
+| `EXC002` | handler that swallows, only logs, or replaces the exception without its cause | error |
+| `EXC003` | approved `try` wrapping more than the one sanctioned operation | error |
+| `DEF001` | parameter default, dataclass field default / `default_factory` | error |
+| `DEF002` | `m.get(k, v)`, `getattr(o, a, v)`, `o?.x ?? v`, `const {x = v} = o`; `.get(k)` implicit `None` as review | error |
+| `DEF003` | `x or v`, `x || v` outside Boolean logic | review |
+| `DEF004` | `x ?? v`, `x if x is not None else v` | error |
+| `DEF005` | handler that returns a default (literal, module constant, one-return helper) | error |
+| `DEF006` | `os.getenv("X", v)`, `process.env.X || v`, `const { X = v } = process.env` | error |
+| `SUPP001` / `SUPP002` | malformed / unused suppression comment | error / warning |
+
+## Install
+
+Requires Python 3.11+. Runtime dependencies are `tree-sitter` and
+`tree-sitter-javascript` only.
+
+```bash
+pip install shockharness
+```
+
+From a checkout:
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Use
+
+```bash
+shockharness init                       # writes .shockharness.toml (strict profile)
+shockharness config validate            # exit 0 if the configuration is valid
+shockharness config effective           # merged config with per-key origins
+shockharness scan src/                  # human-readable report, exit = gate status
+shockharness scan src/ --format json --output report.json
+shockharness rules list
+shockharness rules explain MAGIC001
+```
+
+Exit codes: `0` gates pass, `1` policy violations, `2` invalid configuration or
+invocation, `3` internal error or (with `parse_errors = "fail"`) a file that
+could not be parsed. A report is still produced when the gate fails.
+
+Example:
+
+```text
+src/client.py:12:11: MAGIC001 error: Numeric literal 30 has no permitted justification in executable code  [timeout = 30]
+src/client.py:15:24: DEF001 error: parameter 'port' of connect() has a default value: 5432  [def connect(host, port=5432):]
+src/client.py:18:15: DEF006 error: environment variable "RETRIES" falls back to "3"; os.getenv(...) substitutes a fallback when environment variable "RETRIES" is unset (getenv)  [retries = os.getenv("RETRIES", "3")]
+src/client.py:24:5: DEF005 error: except handler converts the exception into a fallback value: return None (EXC002 classification return_fallback; the handler is reported once, here)  [except OSError:]
+src/client.py:24:5: EXC001 error: except handler of 'OSError' is forbidden: catch of 'OSError' is not approved by any boundary for this file  [except OSError:]
+
+shockharness 0.1.0: 1 file(s), 1 analyzed, 0 failed; 5 finding(s), 0 suppressed
+  by severity: error=5
+  rules applied: MAGIC001, EXC001, EXC002, EXC003, DEF001, DEF002, DEF003, DEF004, DEF005, DEF006, SUPP001, SUPP002
+  rules not implemented (not analyzed): MAGIC002, CPLX001, CPLX002, CPLX003, CPLX004, CPLX005
+gate: FAIL (exit 1)
+  5 hard violation(s) and gates.new_hard_violations = "fail"
+```
+
+## Configuration
+
+Either `.shockharness.toml` or a `[tool.shockharness]` table in
+`pyproject.toml` (the dedicated file wins and the shadowed table is reported).
+Unknown keys, bad types, unknown rule IDs, and invalid globs are errors, never
+ignored. Every rule can be disabled; every disable is listed in the report.
+
+```toml
+[tool.shockharness]
+profile = "strict"
+include = ["src/**/*.py", "src/**/*.js"]
+exclude = ["**/node_modules/**", "**/.venv/**"]
+parse_errors = "fail"
+
+[tool.shockharness.rules.magic_numbers]
+enabled = true
+allowed_values = [0, 1]
+allow_unary_negative_one = false
+
+[[tool.shockharness.overrides]]
+paths = ["tests/**"]
+disable = ["MAGIC001"]
+reason = "Fixtures encode literal expected outputs"
+```
+
+Inline suppressions need an exact rule ID and a reason, on the same line:
+
+```python
+status = 404  # shockharness: ignore[MAGIC001] reason="RFC 9110 section 15.5.5"
+```
+
+A malformed suppression is a `SUPP001` error; one that silences nothing is a
+`SUPP002` warning. `--no-inline-suppressions` disables them for centrally
+governed policies.
+
+See `docs/` for configuration, rules, architecture, and limitations.
+
+## Library
+
+```python
+from pathlib import Path
+from shockharness import analyze_paths
+from shockharness.analysis import AnalysisOptions
+from shockharness.config import load_config
+
+config = load_config(Path("."), None)
+report = analyze_paths([Path("src")], Path("."), config, AnalysisOptions(inline_suppressions=True))
+print(report.gate.status, len(report.findings))
+```
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+pytest -q
+ruff check src tests && ruff format --check src tests
+shockharness scan src tests     # the tool gates its own source
+```
+
+ShockHarness runs on itself as a hard CI gate. Its one `MAGIC001` exemption is
+`src/shockharness/constants.py`; its declared exception boundaries are listed in
+`.shockharness.toml` with reasons and enforced by `EXC001`-`EXC003`: every
+`try` in the tool wraps exactly one external call and converts the failure into
+a typed diagnostic. `DEF001`-`DEF006` hold too: the tool has no parameter
+defaults outside tests, no mapping fallbacks, and no `or`/`is None` defaults.
+
+## License
+
+MIT. See `LICENSE`.

shockharness-0.1.0a1/README.md

@@ -0,0 +1,163 @@
+# ShockHarness
+
+A strict, deterministic static-analysis quality gate for Python and JavaScript.
+Its one idea: unexpected failures, missing information, and unexplained
+decisions must not silently become apparently valid program behavior.
+
+Three default-on hard policies:
+
+1. **Exception transparency.** No catch except at narrow, explicitly approved
+   external boundaries. No catch-and-continue, no success-shaped fallbacks.
+2. **No implicit defaults.** No fallback values for missing required data, no
+   function-parameter defaults in strict mode.
+3. **No magic numbers.** Every numeric literal in executable code must be
+   exactly `0` or `1`. `range(2)` is a violation. The tool invents no exemptions.
+
+Plus a separate, advisory complexity family (cyclomatic, cognitive, nesting,
+NPath, call graph, churn). Hard violations are never averaged into a score.
+
+ShockHarness complements Ruff and ESLint; it is not a formatter or a general
+linter. It runs offline, needs no LLM, and never uploads source.
+
+## Status
+
+Pre-release. Milestones A (skeleton and contracts), B (parsers and
+`MAGIC001`), C (exception rules `EXC001`-`EXC003`) and D (default and fallback
+rules `DEF001`-`DEF006`) are implemented. `MAGIC002`, complexity, baselines,
+SARIF, and agent skills are registered but **not yet implemented**; every
+report lists them under `rules_not_implemented` so a clean run never implies
+coverage the tool does not have. See `STATUS.md` for exact evidence.
+
+Implemented rules:
+
+| ID | What it reports | Default |
+|---|---|---|
+| `MAGIC001` | numeric literal other than `0`/`1` in executable code | error |
+| `EXC001` | catch outside an approved boundary (bare, broad, unresolved, untyped) | error |
+| `EXC002` | handler that swallows, only logs, or replaces the exception without its cause | error |
+| `EXC003` | approved `try` wrapping more than the one sanctioned operation | error |
+| `DEF001` | parameter default, dataclass field default / `default_factory` | error |
+| `DEF002` | `m.get(k, v)`, `getattr(o, a, v)`, `o?.x ?? v`, `const {x = v} = o`; `.get(k)` implicit `None` as review | error |
+| `DEF003` | `x or v`, `x || v` outside Boolean logic | review |
+| `DEF004` | `x ?? v`, `x if x is not None else v` | error |
+| `DEF005` | handler that returns a default (literal, module constant, one-return helper) | error |
+| `DEF006` | `os.getenv("X", v)`, `process.env.X || v`, `const { X = v } = process.env` | error |
+| `SUPP001` / `SUPP002` | malformed / unused suppression comment | error / warning |
+
+## Install
+
+Requires Python 3.11+. Runtime dependencies are `tree-sitter` and
+`tree-sitter-javascript` only.
+
+```bash
+pip install shockharness
+```
+
+From a checkout:
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Use
+
+```bash
+shockharness init                       # writes .shockharness.toml (strict profile)
+shockharness config validate            # exit 0 if the configuration is valid
+shockharness config effective           # merged config with per-key origins
+shockharness scan src/                  # human-readable report, exit = gate status
+shockharness scan src/ --format json --output report.json
+shockharness rules list
+shockharness rules explain MAGIC001
+```
+
+Exit codes: `0` gates pass, `1` policy violations, `2` invalid configuration or
+invocation, `3` internal error or (with `parse_errors = "fail"`) a file that
+could not be parsed. A report is still produced when the gate fails.
+
+Example:
+
+```text
+src/client.py:12:11: MAGIC001 error: Numeric literal 30 has no permitted justification in executable code  [timeout = 30]
+src/client.py:15:24: DEF001 error: parameter 'port' of connect() has a default value: 5432  [def connect(host, port=5432):]
+src/client.py:18:15: DEF006 error: environment variable "RETRIES" falls back to "3"; os.getenv(...) substitutes a fallback when environment variable "RETRIES" is unset (getenv)  [retries = os.getenv("RETRIES", "3")]
+src/client.py:24:5: DEF005 error: except handler converts the exception into a fallback value: return None (EXC002 classification return_fallback; the handler is reported once, here)  [except OSError:]
+src/client.py:24:5: EXC001 error: except handler of 'OSError' is forbidden: catch of 'OSError' is not approved by any boundary for this file  [except OSError:]
+
+shockharness 0.1.0: 1 file(s), 1 analyzed, 0 failed; 5 finding(s), 0 suppressed
+  by severity: error=5
+  rules applied: MAGIC001, EXC001, EXC002, EXC003, DEF001, DEF002, DEF003, DEF004, DEF005, DEF006, SUPP001, SUPP002
+  rules not implemented (not analyzed): MAGIC002, CPLX001, CPLX002, CPLX003, CPLX004, CPLX005
+gate: FAIL (exit 1)
+  5 hard violation(s) and gates.new_hard_violations = "fail"
+```
+
+## Configuration
+
+Either `.shockharness.toml` or a `[tool.shockharness]` table in
+`pyproject.toml` (the dedicated file wins and the shadowed table is reported).
+Unknown keys, bad types, unknown rule IDs, and invalid globs are errors, never
+ignored. Every rule can be disabled; every disable is listed in the report.
+
+```toml
+[tool.shockharness]
+profile = "strict"
+include = ["src/**/*.py", "src/**/*.js"]
+exclude = ["**/node_modules/**", "**/.venv/**"]
+parse_errors = "fail"
+
+[tool.shockharness.rules.magic_numbers]
+enabled = true
+allowed_values = [0, 1]
+allow_unary_negative_one = false
+
+[[tool.shockharness.overrides]]
+paths = ["tests/**"]
+disable = ["MAGIC001"]
+reason = "Fixtures encode literal expected outputs"
+```
+
+Inline suppressions need an exact rule ID and a reason, on the same line:
+
+```python
+status = 404  # shockharness: ignore[MAGIC001] reason="RFC 9110 section 15.5.5"
+```
+
+A malformed suppression is a `SUPP001` error; one that silences nothing is a
+`SUPP002` warning. `--no-inline-suppressions` disables them for centrally
+governed policies.
+
+See `docs/` for configuration, rules, architecture, and limitations.
+
+## Library
+
+```python
+from pathlib import Path
+from shockharness import analyze_paths
+from shockharness.analysis import AnalysisOptions
+from shockharness.config import load_config
+
+config = load_config(Path("."), None)
+report = analyze_paths([Path("src")], Path("."), config, AnalysisOptions(inline_suppressions=True))
+print(report.gate.status, len(report.findings))
+```
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+pytest -q
+ruff check src tests && ruff format --check src tests
+shockharness scan src tests     # the tool gates its own source
+```
+
+ShockHarness runs on itself as a hard CI gate. Its one `MAGIC001` exemption is
+`src/shockharness/constants.py`; its declared exception boundaries are listed in
+`.shockharness.toml` with reasons and enforced by `EXC001`-`EXC003`: every
+`try` in the tool wraps exactly one external call and converts the failure into
+a typed diagnostic. `DEF001`-`DEF006` hold too: the tool has no parameter
+defaults outside tests, no mapping fallbacks, and no `or`/`is None` defaults.
+
+## License
+
+MIT. See `LICENSE`.