instruction-drift 0.1.0__py3-none-any.whl

instruction_drift/__init__.py

@@ -0,0 +1,3 @@
+"""Offline repository instruction drift checks."""
+
+__version__ = "0.1.0"

instruction_drift/__main__.py

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

instruction_drift/audit.py

@@ -0,0 +1,118 @@
+"""Deterministic, offline comparison of lexical claims with disk contents."""
+from dataclasses import asdict, dataclass
+from fnmatch import fnmatchcase
+import os
+from pathlib import Path
+import re
+from .extract import extract
+
+DEFAULT_FILES = ('AGENTS.md', 'CLAUDE.md', 'MUSE.md', 'CONTRIBUTING.md')
+SKIP = {'node_modules', 'dist', '__pycache__', 'venv'}
+
+@dataclass(frozen=True)
+class Finding:
+    file: str
+    line: int
+    kind: str
+    claim: str
+    severity: str
+    detail: str
+
+
+def imports(root, excluded):
+    identifiers = set()
+    for directory, dirs, files in os.walk(root):
+        dirs[:] = sorted(d for d in dirs if not d.startswith('.') and d not in SKIP
+                         and not (Path(directory) / d).is_symlink())
+        for name in sorted(files):
+            path = Path(directory) / name
+            if path.resolve() in excluded or path.suffix not in ('.py', '.js', '.ts'):
+                continue
+            try:
+                content = path.read_text(encoding='utf-8')
+            except (OSError, UnicodeError):
+                continue
+            if path.suffix == '.py':
+                for match in re.finditer(r'^\s*(?:from\s+([\w.]+)\s+import\b|import\s+([^\n;#]+))', content, re.M):
+                    if match.group(1):
+                        identifiers.add(match.group(1))
+                    else:
+                        identifiers.update(part.strip().split()[0] for part in
+                                           match.group(2).split(',') if part.strip())
+            else:
+                identifiers.update(re.findall(r'''(?:require\(\s*|\bfrom\s*)['"]([^'"]+)['"]''', content))
+    return identifiers
+
+
+def audit(repo='.', files=None, ignore=(), fail_on='high'):
+    root = Path(repo).resolve()
+    names = list(DEFAULT_FILES if files is None else files)
+    report = dict(files_read=[], findings=[], ignored=0, parse_errors=[], truncated=False)
+    if not root.is_dir():
+        report['parse_errors'].append({'file': str(repo), 'detail': 'Repository is not a directory'})
+    excluded = {(root / name).resolve() for name in names}
+    used = imports(root, excluded) if root.is_dir() else set()
+    targets = None
+    seen = set()
+    threshold_hit = False
+    for name in names if root.is_dir() else []:
+        path = root / name
+        if files is None and not path.exists():
+            continue
+        try:
+            content = path.read_text(encoding='utf-8')
+        except (OSError, UnicodeError) as error:
+            report['parse_errors'].append({'file': name, 'detail': str(error)})
+            continue
+        report['files_read'].append(name)
+        for item in extract(content):
+            key = (name, item.line, item.kind, item.claim)
+            if key in seen:
+                continue
+            seen.add(key)
+            if any(fnmatchcase(item.claim, pattern) for pattern in ignore):
+                report['ignored'] += 1
+                continue
+            severity, detail = 'HIGH', ''
+            if item.kind == 'prohibition-contradiction':
+                if item.claim not in used:
+                    continue
+                severity = 'MEDIUM'
+                detail = 'Identifier appears in source imports; verify manually.'
+            elif item.claim.startswith('make '):
+                makefile = root / 'Makefile'
+                if not makefile.exists():
+                    continue
+                if targets is None:
+                    try:
+                        targets = set(re.findall(r'^([A-Za-z0-9_.-]+)\s*:(?!=)', makefile.read_text(encoding='utf-8'), re.M))
+                    except (OSError, UnicodeError) as error:
+                        report['parse_errors'].append({'file': 'Makefile', 'detail': str(error)})
+                        targets = set()
+                if item.claim[5:] in targets:
+                    continue
+                detail = 'Target not found in root Makefile.'
+            else:
+                candidate = root / item.claim
+                try:
+                    candidate.resolve().relative_to(root)
+                except ValueError:
+                    continue
+                exists = candidate.is_dir() if item.claim.endswith('/') else candidate.exists()
+                if exists:
+                    continue
+                detail = 'Referenced path does not exist' + (' as a directory.' if item.claim.endswith('/') else '.')
+            threshold_hit = threshold_hit or severity == 'HIGH' or fail_on == 'medium'
+            if len(report['findings']) < 500:
+                report['findings'].append(asdict(Finding(name, item.line, item.kind, item.claim, severity, detail)))
+            else:
+                report['truncated'] = True
+    findings = report['findings']
+    report['totals'] = {'kind': {k: sum(f['kind'] == k for f in findings) for k in
+                               ('referenced-file', 'script-in-command', 'prohibition-contradiction')},
+                        'severity': {s: sum(f['severity'] == s for f in findings) for s in ('HIGH', 'MEDIUM')}}
+    failed = report['parse_errors'] or threshold_hit
+    report['exit_code'] = 2 if failed else (1 if findings else 0)
+    report['verdict'] = {0: 'PASS', 1: 'WARN', 2: 'FAIL'}[report['exit_code']]
+    report['parse_error_count'] = len(report['parse_errors'])
+    return report

instruction_drift/cli.py

@@ -0,0 +1,33 @@
+"""Command-line interface; commands mentioned in instructions are never run."""
+import argparse
+import json
+from . import __version__
+from .audit import audit
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='instruction-drift', description='Check repository instruction claims offline.')
+    parser.add_argument('--version', action='version', version='%(prog)s ' + __version__)
+    sub = parser.add_subparsers(dest='command', required=True)
+    check = sub.add_parser('audit', help='Audit instruction claims against repository files')
+    check.add_argument('repo', nargs='?', default='.')
+    check.add_argument('--files', nargs='+', action='extend')
+    check.add_argument('--ignore', nargs='+', action='extend', default=[])
+    check.add_argument('--json', action='store_true')
+    check.add_argument('--fail-on', choices=('high', 'medium'), default='high')
+    args = parser.parse_args(argv)
+    report = audit(args.repo, args.files, args.ignore, args.fail_on)
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print('Instruction files read: ' + (', '.join(report['files_read']) or 'none (no instruction files read)'))
+        for finding in report['findings']:
+            print('{file}:{line}: {severity} {kind}: {claim} — {detail}'.format(**finding))
+        for error in report['parse_errors']:
+            print('{file}: parse error: {detail}'.format(**error))
+        print('Totals: ' + json.dumps(report['totals'], sort_keys=True))
+        print('Ignored: {}; parse errors: {}'.format(report['ignored'], report['parse_error_count']))
+        if report['truncated']:
+            print('Report truncated at 500 findings.')
+        print(report['verdict'])
+    return report['exit_code']

instruction_drift/extract.py

@@ -0,0 +1,52 @@
+"""Small, deliberately lexical instruction-claim extractors."""
+from dataclasses import dataclass
+import re
+
+EXTENSIONS = ('.py', '.js', '.ts', '.md', '.json', '.yaml', '.yml',
+              '.toml', '.sh', '.go', '.rs', '.txt')
+ROOTS = ('src/', 'tests/', 'docs/', 'examples/', 'scripts/', 'bin/')
+TOKEN = re.compile(r"[^\s`\"'<>|;()]+")
+BACKTICK = re.compile(r'`([^`]+)`')
+PROHIBITION = re.compile(
+    r'\b(?:do not use|never use|must not use|avoid using)\s+`?([\w@][\w.\-@]*)',
+    re.IGNORECASE)
+
+@dataclass(frozen=True)
+class Claim:
+    line: int
+    kind: str
+    claim: str
+
+
+def path_token(token):
+    """Return a normalized path claim, or None for unsupported tokens."""
+    token = token.lstrip(',:!?[]{}').rstrip('.,:!?[]{}')
+    if '*' in token or '://' in token:
+        return None
+    bare = token[2:] if token.startswith('./') else token
+    if '/' in bare and (bare.endswith(EXTENSIONS) or bare.startswith(ROOTS)):
+        return token
+    return None
+
+
+def extract(text):
+    """Extract claims in line order; command paths have a single kind."""
+    result = []
+    for number, line in enumerate(text.splitlines(), 1):
+        spans = list(BACKTICK.finditer(line))
+        for match in TOKEN.finditer(line):
+            path = path_token(match.group())
+            if path:
+                command = any(s.start(1) <= match.start() < s.end(1)
+                              and (len(s.group(1).split()) > 1 or s.group(1).startswith('./'))
+                              for s in spans)
+                result.append(Claim(number, 'script-in-command' if command else
+                                    'referenced-file', path))
+        for span in spans:
+            words = span.group(1).split()
+            if len(words) >= 2 and words[0] == 'make' and not words[1].startswith('-'):
+                result.append(Claim(number, 'script-in-command', 'make ' + words[1]))
+        for match in PROHIBITION.finditer(line):
+            result.append(Claim(number, 'prohibition-contradiction',
+                                match.group(1).rstrip('.')))
+    return list(dict.fromkeys(result))

instruction_drift-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: instruction-drift
+Version: 0.1.0
+Summary: Offline heuristic checks for stale repository instructions
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# instruction-drift
+
+An offline, deterministic, stdlib-only Python CLI that checks concrete instruction
+claims against repository files. A finding means **check this claim**. It does
+not establish that an instruction is wrong. No daemon, LLM, network, or keys.
+
+Requires Python 3.9+. Install a locally built wheel with `pip install
+/path/to/instruction_drift-0.1.0-py3-none-any.whl`.
+
+```sh
+instruction-drift audit .
+instruction-drift audit examples/sample-repo --json
+instruction-drift audit . --files AGENTS.md CONTRIBUTING.md --ignore 'docs/*'
+instruction-drift audit . --fail-on medium
+instruction-drift --version
+instruction-drift --help
+```
+
+The repository defaults to the current directory. Default instruction files,
+in order, are root AGENTS.md, CLAUDE.md, MUSE.md, and CONTRIBUTING.md. Missing
+default files are skipped; an empty repository passes with a note. `--files`
+replaces that list with paths relative to the repository. Missing explicitly
+requested files, unreadable files, and invalid UTF-8 produce parse errors.
+`--files` and `--ignore` accept multiple arguments and can be repeated.
+
+Checks are heuristic:
+
+- **referenced-file (HIGH):** missing path tokens containing `/` and ending in
+  .py, .js, .ts, .md, .json, .yaml, .yml, .toml, .sh, .go, .rs, or .txt;
+  also directory references rooted under src/, tests/, docs/, examples/,
+  scripts/, or bin/. Trailing `/` requires a directory. Paths resolve relative
+  to the repository root. URLs, tokens containing `*`, and paths resolving
+  outside the repository are skipped.
+- **script-in-command (HIGH):** missing path tokens in backticked commands;
+  missing `make target` targets when a root Makefile exists. Simple literal
+  target definitions are recognized; Makefile variables and comments are not
+  definitions. A command path is reported once rather than also as a reference.
+- **prohibition-contradiction (MEDIUM):** “do not use”, “never use”, “must not
+  use”, or “avoid using” followed by an identifier also found in a Python
+  import/from import or JS/TS require/from import. Verify manually: exceptions
+  and test fixtures may be intentional. Instruction files are excluded from
+  source search. Hidden directories, .git, node_modules, dist, __pycache__,
+  .venv, and venv are skipped, as are symlinked directories.
+
+The report includes files read, file:line locations, kinds, claims, severities,
+details, totals by kind and severity, ignored count, parse-error count, and a
+PASS/WARN/FAIL verdict. `--json` exposes the same information as valid JSON.
+Claims matching `--ignore` glob patterns are excluded and counted before
+checking their validity. Findings are deduplicated by file, line, kind, and
+claim. At most 500 findings are retained in instruction-file and line order;
+additional findings set the truncation flag. Totals describe retained findings. Failure thresholds still apply to findings
+beyond the display cap.
+
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | PASS: no findings and no parse errors |
+| 1 | WARN: findings exist, but none reach the failure threshold |
+| 2 | FAIL: a finding reaches the threshold, or any parse error occurs |
+
+The default threshold is HIGH; `--fail-on medium` also fails MEDIUM findings.
+For example, the synthetic sample repo cites a renamed script and moved test
+directory, and prohibits an identifier imported in src/app.py. Auditing it
+returns two HIGH findings, one MEDIUM finding, and exit code 2. Its illustrative
+import does not require an installed dependency because commands are never run.
+
+## Limitations
+
+This is pattern matching, not semantic judgement. Paraphrased claims are not
+checked. A MEDIUM contradiction needs human review. Commands are not executed;
+only path tokens and simple Makefile target names are checked. Dynamic imports,
+complex shell syntax, generated paths, multiline imports, Makefile includes and
+computed targets, and language-specific resolution are not interpreted.
+Lexical import patterns may match comments or strings and may miss real imports.
+Source files that cannot be decoded or read are skipped; this can hide import
+matches. Instruction-file read failures always produce parse errors. A truncated
+report is incomplete. Filesystem changes during a scan can affect its results.
+
+## Differentiation
+
+- **startup-trust-guard** audits TRUST: can an attacker plant or rewrite the
+  instruction file? instruction-drift audits TRUTH: is what it says still true
+  about the on-disk repository?
+- **rules-doctor** audits rule-file health and structure. This tool cross-checks
+  instruction claims against the on-disk repo.
+- **edit-guard** blocks edits made on stale reads. This tool finds stale
+  instructions that can cause those edits.
+- **context-mode / heavy runtimes:** this is an offline stdlib CLI with no
+  daemon, no LLM, and no network.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+Building requires setuptools, wheel, and the build frontend already installed
+for offline use. Runtime and tests use only the Python standard library.

instruction_drift-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+instruction_drift/__init__.py,sha256=U81StD9LNclhgLJ9bgtdeFUzA4XVRYGOmqgLTpxL3S0,74
+instruction_drift/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+instruction_drift/audit.py,sha256=QYPE3oOOA0NTXto2cdOvoJJ3hxLMrmIulc1bV_v5Vkk,5316
+instruction_drift/cli.py,sha256=4LsT_OHgZjO3fB4ddp_Upj6h95QA7BKAB0TXtRVCJTA,1745
+instruction_drift/extract.py,sha256=TgMFTf_rQk_AQziMb47Yjwv0zJ-6yjgxnu1a8jqKLJQ,2105
+instruction_drift-0.1.0.dist-info/licenses/LICENSE,sha256=BHibCVQHNQhBYTj-25q7SphGxQHnM5-dmo37W0YLcm8,1087
+instruction_drift-0.1.0.dist-info/METADATA,sha256=FBT_t2D87L80K4EuwvgAJ5IpWexU8kzqch9rmjzFBiM,5338
+instruction_drift-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+instruction_drift-0.1.0.dist-info/entry_points.txt,sha256=21cQWcFwc_6LI_eRPGTqjBD2lRcw2zvFdMVOuODEy2I,65
+instruction_drift-0.1.0.dist-info/top_level.txt,sha256=Am-FIfrhTWa7BaRGUmYqhcgYx8SQa1FoGBsaa-4sAZs,18
+instruction_drift-0.1.0.dist-info/RECORD,,

instruction_drift-0.1.0.dist-info/WHEEL

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

instruction_drift-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+instruction-drift = instruction_drift.cli:main

instruction_drift-0.1.0.dist-info/licenses/LICENSE

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

instruction_drift-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+instruction_drift