compact-audit 0.1.0__py3-none-any.whl

compact_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Offline, deterministic compaction summary auditing."""
+__version__ = '0.1.0'

compact_audit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

compact_audit/audit.py

@@ -0,0 +1,33 @@
+"""Audit literal normalized surfaces, never semantic equivalence."""
+from dataclasses import asdict
+import re
+from .extract import CATEGORIES, normalize
+
+LIMITATION = 'Surface matching only. DROPPED means not found by surface matching — verify manually. Paraphrase is not detected; severity is a triage signal, not a verdict about meaning.'
+
+
+def audit(extraction, summary, min_severity='high'):
+    if min_severity not in ('high', 'medium'):
+        raise ValueError('min_severity must be high or medium')
+    normalized = normalize(summary)
+    error_summary = normalize(re.sub(r'\d+', '', summary))
+    totals = {category: {'kept': 0, 'dropped': 0} for category in CATEGORIES}
+    dropped = []
+    for item in extraction.items:
+        target = error_summary if item.category == 'error' else normalized
+        kept = bool(item.key and item.key in target)
+        if item.category == 'file_edit':
+            kept = kept or bool(item.basename and item.basename in target)
+        totals[item.category]['kept' if kept else 'dropped'] += 1
+        if not kept:
+            dropped.append(asdict(item))
+    severe = any(item['severity'] == 'HIGH' or min_severity == 'medium' for item in dropped)
+    exit_code = 2 if extraction.parse_errors or severe else (1 if dropped else 0)
+    return {
+        'totals': totals, 'total_items': len(extraction.items),
+        'kept': len(extraction.items) - len(dropped), 'dropped_count': len(dropped),
+        'dropped': dropped, 'parse_errors': extraction.parse_errors,
+        'truncated': extraction.truncated, 'min_severity': min_severity,
+        'verdict': {0: 'PASS', 1: 'WARN', 2: 'FAIL'}[exit_code],
+        'exit_code': exit_code, 'limitation': LIMITATION,
+    }

compact_audit/cli.py

@@ -0,0 +1,36 @@
+"""Command-line interface."""
+import argparse
+import json
+from pathlib import Path
+from . import __version__
+from .audit import audit
+from .extract import extract, read_transcript
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='compact-audit', description='Offline surface audit of compaction context loss.')
+    parser.add_argument('--version', action='version', version='%(prog)s ' + __version__)
+    commands = parser.add_subparsers(dest='command', required=True)
+    command = commands.add_parser('audit', help='compare a transcript with its summary')
+    command.add_argument('transcript', type=Path)
+    command.add_argument('summary', type=Path)
+    command.add_argument('--json', action='store_true', dest='json_output')
+    command.add_argument('--min-severity', choices=('high', 'medium'), default='high')
+    args = parser.parse_args(argv)
+    try:
+        lines, errors = read_transcript(args.transcript)
+        report = audit(extract(lines, errors), args.summary.read_text(encoding='utf-8'), args.min_severity)
+    except (OSError, UnicodeError) as exc:
+        parser.error(str(exc))
+    if args.json_output:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print('{verdict}: {kept} kept, {dropped_count} dropped / {total_items} items'.format(**report))
+        for category, counts in report['totals'].items():
+            print('{}: {} kept, {} dropped'.format(category, counts['kept'], counts['dropped']))
+        print('Parse errors: {}'.format(report['parse_errors']))
+        print('Truncated: {} (maximum 500 items)'.format(report['truncated']))
+        for item in report['dropped']:
+            print('DROPPED [{severity}] {category}: {key}\n  {text}'.format(**item))
+        print(report['limitation'])
+    return report['exit_code']

compact_audit/extract.py

@@ -0,0 +1,88 @@
+"""Deterministic, deliberately conservative surface-pattern extraction."""
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+CATEGORIES = ('decision', 'constraint', 'error', 'file_edit', 'todo')
+MAX_ITEMS = 500
+SOURCE_LIMIT = 500
+
+
+def normalize(text):
+    return re.sub(r'[\W_]+', ' ', text.lower()).strip()
+
+
+@dataclass(frozen=True)
+class Item:
+    category: str
+    key: str
+    text: str
+    severity: str
+    basename: str = ''
+
+
+@dataclass
+class Extraction:
+    items: list
+    parse_errors: int = 0
+    truncated: bool = False
+
+
+DECISION = re.compile(r'\b(?:decision\s*:|decided to\b|we will use\b|chosen\b|agreed to\b|going with\b)', re.I)
+CONSTRAINT = re.compile(r'\b(?:must not\b|never\s+\S|do not\b|must always\b|only\s+\S|required\b)', re.I)
+ERROR = re.compile(r'\b(?:error\b|traceback\b|failed\b|failed with\b|exit code\s*[:=]?\s*-?0*[1-9]\d*\b)', re.I)
+EDIT = re.compile(r'\b(?:edited|changed|created|deleted|modified|wrote|rewrote|updated)\b', re.I)
+PATH = re.compile(r'(?<![\w/.-])(?:[\w.-]+/)*[\w.-]+\.(?:py|js|ts|md|json|yaml|toml|go|rs)\b|(?<![\w/.-])(?:[\w.-]+/)*(?:src|tests|docs)/[\w./-]+', re.I)
+TODO = re.compile(r'\b(?:todo|fixme|not done|remaining|next step|still need)\b', re.I)
+
+
+def read_transcript(path):
+    """Return source lines and errors; JSONL must contain objects with text."""
+    path = Path(path)
+    lines, errors = [], 0
+    for raw in path.read_text(encoding='utf-8').splitlines():
+        if not raw.strip():
+            continue
+        if path.suffix.lower() == '.jsonl':
+            try:
+                obj = json.loads(raw)
+                if not isinstance(obj, dict):
+                    raise ValueError('expected object')
+                value = next((obj[k] for k in ('content', 'text', 'message') if k in obj), '')
+                if not isinstance(value, str):
+                    raise ValueError('expected text')
+            except (ValueError, TypeError):
+                errors += 1
+                continue
+            lines.extend(line for line in value.splitlines() if line.strip())
+        else:
+            lines.append(raw)
+    return lines, errors
+
+
+def extract(lines, parse_errors=0):
+    items, seen = [], set()
+    truncated = False
+    for line in lines:
+        candidates = []
+        for category, pattern in (('decision', DECISION), ('constraint', CONSTRAINT), ('error', ERROR)):
+            if pattern.search(line):
+                key = normalize(re.sub(r'\d+', '', line) if category == 'error' else line)
+                candidates.append(Item(category, key, line[:SOURCE_LIMIT], 'HIGH'))
+        if EDIT.search(line):
+            for match in PATH.finditer(line):
+                path = match.group().rstrip('./')
+                candidates.append(Item('file_edit', normalize(path), line[:SOURCE_LIMIT], 'MEDIUM', normalize(path.rsplit('/', 1)[-1])))
+        if TODO.search(line):
+            candidates.append(Item('todo', normalize(line), line[:SOURCE_LIMIT], 'MEDIUM'))
+        for item in candidates:
+            identity = (item.category, item.key)
+            if identity in seen:
+                continue
+            seen.add(identity)
+            if len(items) < MAX_ITEMS:
+                items.append(item)
+            else:
+                truncated = True
+    return Extraction(items, parse_errors, truncated)

compact_audit-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 compact-audit contributors
+
+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.

compact_audit-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.1
+Name: compact-audit
+Version: 0.1.0
+Summary: Offline surface matching audit of compaction summaries
+License: MIT License
+        
+        Copyright (c) 2026 compact-audit contributors
+        
+        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.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# compact-audit
+
+An offline, deterministic Python CLI that compares a pre-compaction transcript
+with the summary or handover note that replaced it. It extracts critical items
+and reports which surfaces were kept or dropped, with category totals and
+severity for triage. No LLM, network calls, keys, or runtime dependencies.
+Python 3.9+; MIT licensed.
+
+## Usage
+
+Install the locally built wheel with `python -m pip install --no-index dist/compact_audit-0.1.0-py3-none-any.whl`.
+
+```sh
+compact-audit --version
+compact-audit audit examples/sample-transcript.jsonl examples/sample-summary.md
+compact-audit audit examples/sample-transcript.jsonl examples/sample-summary.md --json
+compact-audit audit transcript.txt summary.md --min-severity medium
+python -m compact_audit --help
+```
+
+The included examples are entirely synthetic. Their full-coverage summary
+returns PASS (exit 0). Removing its migration decision makes the audit FAIL
+(exit 2). JSON reports contain the same totals, dropped items, parse-error count,
+truncation indicator, verdict, and limitation as human reports.
+
+## Inputs and extraction
+
+Transcripts are UTF-8 JSONL (`.jsonl`, case insensitive) or plain text (`.txt` or
+`.md`). Plain text is split into non-empty lines. JSONL requires one object per
+non-empty line; fields use `content`, then `text`, then `message` when the earlier
+field is absent. Other fields are ignored. Missing text fields yield no items;
+non-string selected fields, non-objects, and malformed JSON count as parse
+errors. Multiline strings are split into source lines. Blank lines are ignored.
+The summary is a UTF-8 text or Markdown file. Empty transcripts yield zero items;
+empty summaries drop every extracted item.
+
+These short, case-insensitive pattern lists are heuristic:
+
+| Category | Triggers | Severity if dropped |
+| --- | --- | --- |
+| decision | `Decision:`, `decided to`, `we will use`, `chosen`, `agreed to`, `going with` | HIGH |
+| constraint | `must not`, `never `, `do not`, `must always`, `only ` followed by a non-empty clause, `required` | HIGH |
+| error | word `Error`, `Traceback`, `FAILED`, `failed with`, or `exit code` followed by a non-zero integer | HIGH |
+| file_edit | `edited`, `changed`, `created`, `deleted`, `modified`, `wrote`, `rewrote`, `updated` plus a recognized path | MEDIUM |
+| todo | `TODO`, `FIXME`, `not done`, `remaining`, `next step`, `still need` | MEDIUM |
+
+Recognized file paths end in `.py`, `.js`, `.ts`, `.md`, `.json`, `.yaml`,
+`.toml`, `.go`, or `.rs`, or are under `src/`, `tests/`, or `docs/`.
+Each matched path becomes a separate item. A line can produce several categories.
+Items deduplicate by category and normalized key. The first 500 unique items in
+transcript order are retained; additional unique items set `truncated` to true.
+Within a line, category order is decision, constraint, error, file_edit, todo.
+Source text is truncated to 500 characters; matching keys retain the full line.
+
+Matching lowercases text and collapses punctuation, underscores, and whitespace
+to single spaces. Whole normalized line keys must occur as substrings of the
+normalized summary. Error keys strip digits; the summary also strips digits for
+error matching. File edits match either their normalized full path or basename.
+
+## Exit codes
+
+| Code | Verdict | Meaning |
+| --- | --- | --- |
+| 0 | PASS | No dropped items |
+| 1 | WARN | Dropped items exist, but none reach the selected threshold |
+| 2 | FAIL | A dropped item reaches the threshold, or any parse error occurred |
+
+The default threshold is `high`: MEDIUM-only drops warn with exit 1. With
+`--min-severity medium`, any drop fails with exit 2. Thus an audit with no
+threshold-level drops can still warn; PASS is reserved for no drops. Input I/O,
+encoding, and CLI usage errors also return 2 with an explanatory diagnostic.
+
+## Honest limitations
+
+This is surface matching, not semantic judgement. Paraphrase is not detected
+and causes false DROPPED results. DROPPED means **not found by surface matching —
+verify manually**, rather than certainty that meaning was lost. Severity and
+thresholds are triage signals, not evidence that a summary is safe or complete.
+
+Heuristic patterns can miss implicit decisions or overmatch incidental language
+(such as unrestricted uses of “only”). Basename matches may conflate different
+files; substring matches can accept negated statements. Digit stripping can
+conflate distinct errors. A PASS covers only extracted surfaces, and truncation
+leaves later items unaudited. Review truncation and the original context manually.
+The tool does not inspect repositories, execute transcript content, validate
+claims, or recover missing context.
+
+## Differentiation
+
+- **Succession** is a Claude-Code-only plugin with git-pointer claim checks;
+  compact-audit is an offline cross-harness CLI over transcript and summary text.
+- **session-handover** generates a handover pack; compact-audit audits any summary,
+  including auto-compaction output, for loss.
+- **catnap** prevents mid-task compaction; compact-audit measures surface items a
+  completed compaction left out.
+- **model-canary** probes model drift; compact-audit audits context loss.
+
+## Development
+
+Runtime and tests use only the Python standard library. Packaging uses setuptools
+and wheel through `pyproject.toml`, with the standard `build` frontend.
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+```
+
+For an offline environment with build, setuptools, and wheel already installed,
+use `python -m build --no-isolation` to avoid dependency downloads. Build outputs
+are artifacts under `dist/`, not source files.

compact_audit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+compact_audit/__init__.py,sha256=315WeNzsOHfv_sRYTZH7pnFyUyp1PyLNkLnZdtQvrQo,80
+compact_audit/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+compact_audit/audit.py,sha256=bu5hB1kCZtLF90SA9qVfXXppZYIV9WO625Q04X-iVgs,1713
+compact_audit/cli.py,sha256=MIZjZvvs_SxWhqEGpaPdBTUoOabWzKgoeOa_jg5gmAE,1810
+compact_audit/extract.py,sha256=WYNo2ar7XtI0qBwo7VOdztb_qF5sMkbnZheKvn8YoHE,3333
+compact_audit-0.1.0.dist-info/LICENSE,sha256=6FF-SpUjQEStFXE1nIYXbJ7ZFJex4M3T8xrJygLVAEM,1083
+compact_audit-0.1.0.dist-info/METADATA,sha256=mgIvlTIp7Da2_9uAUZ7O8U--7tlOHOCrP-oBMj7D9yA,7104
+compact_audit-0.1.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+compact_audit-0.1.0.dist-info/entry_points.txt,sha256=SG58MUyofG2r_pMyZNe-26y-28xi_NhtGo_eNvjX6Ts,57
+compact_audit-0.1.0.dist-info/top_level.txt,sha256=nr9HvYv80YGr9CPeWKKzh1R9frSKamMuUgyBwCQUzcI,14
+compact_audit-0.1.0.dist-info/RECORD,,

compact_audit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

compact_audit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+compact-audit = compact_audit.cli:main

compact_audit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+compact_audit