instruction-drift 0.1.0__tar.gz

instruction_drift-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,100 @@
+# 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/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "instruction-drift"
+version = "0.1.0"
+description = "Offline heuristic checks for stale repository instructions"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+
+[project.scripts]
+instruction-drift = "instruction_drift.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

instruction_drift-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

instruction_drift-0.1.0/src/instruction_drift/__init__.py

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

instruction_drift-0.1.0/src/instruction_drift/__main__.py

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

instruction_drift-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/instruction_drift.egg-info/PKG-INFO

@@ -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/src/instruction_drift.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/instruction_drift/__init__.py
+src/instruction_drift/__main__.py
+src/instruction_drift/audit.py
+src/instruction_drift/cli.py
+src/instruction_drift/extract.py
+src/instruction_drift.egg-info/PKG-INFO
+src/instruction_drift.egg-info/SOURCES.txt
+src/instruction_drift.egg-info/dependency_links.txt
+src/instruction_drift.egg-info/entry_points.txt
+src/instruction_drift.egg-info/top_level.txt
+tests/test_audit.py
+tests/test_cli.py
+tests/test_extract.py

instruction_drift-0.1.0/src/instruction_drift.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

instruction_drift-0.1.0/src/instruction_drift.egg-info/entry_points.txt

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

instruction_drift-0.1.0/src/instruction_drift.egg-info/top_level.txt

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

instruction_drift-0.1.0/tests/test_audit.py

@@ -0,0 +1,167 @@
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+from instruction_drift.audit import audit
+
+
+class AuditTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+
+    def write(self, name, content=''):
+        path = self.root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding='utf-8')
+        return path
+
+    def check(self, content, **kwargs):
+        self.write('AGENTS.md', content)
+        return audit(self.root, **kwargs)
+
+    def test_empty(self):
+        self.assertEqual(audit(self.root)['exit_code'], 0)
+
+    def test_exists(self):
+        self.write('src/app.py')
+        self.assertEqual(self.check('src/app.py')['findings'], [])
+
+    def test_missing(self):
+        r = self.check('src/missing.py')
+        self.assertEqual((r['exit_code'], r['totals']['severity']['HIGH']), (2, 1))
+
+    def test_directory_exists(self):
+        (self.root / 'tests/unit').mkdir(parents=True)
+        self.assertEqual(self.check('tests/unit/')['exit_code'], 0)
+
+    def test_directory_missing(self):
+        self.assertEqual(self.check('tests/old/')['exit_code'], 2)
+
+    def test_directory_is_file(self):
+        self.write('tests/unit')
+        self.assertEqual(self.check('tests/unit/')['exit_code'], 2)
+
+    def test_url_glob(self):
+        self.assertEqual(self.check('https://site/a.py src/*.py')['findings'], [])
+
+    def test_absolute_outside(self):
+        self.assertEqual(self.check('/outside/missing.py')['findings'], [])
+
+    def test_absolute_inside(self):
+        self.assertEqual(self.check(str(self.root / 'missing.py'))['exit_code'], 2)
+
+    def test_parent_outside(self):
+        self.assertEqual(self.check('../outside/a.py')['exit_code'], 0)
+
+    def test_command_missing(self):
+        r = self.check('`python scripts/run.py`')
+        self.assertEqual(r['totals']['kind']['script-in-command'], 1)
+        self.assertEqual(len(r['findings']), 1)
+
+    def test_command_exists(self):
+        self.write('scripts/run.sh')
+        self.assertEqual(self.check('`./scripts/run.sh`')['exit_code'], 0)
+
+    def test_make_present(self):
+        self.write('Makefile', '# fake:\nNAME := x\ncheck:\n\ttrue\n')
+        self.assertEqual(self.check('`make check`')['exit_code'], 0)
+
+    def test_make_absent(self):
+        self.write('Makefile', '# fake:\nNAME := x\ncheck:\n')
+        self.assertEqual(self.check('`make fake` `make NAME`')['totals']['severity']['HIGH'], 2)
+
+    def test_make_without_makefile(self):
+        self.assertEqual(self.check('`make check`')['exit_code'], 0)
+
+    def test_python_import(self):
+        self.write('src/a.py', 'import legacy\n')
+        self.assertEqual(self.check('Never use legacy')['exit_code'], 1)
+
+    def test_python_from(self):
+        self.write('src/a.py', 'from legacy import client\n')
+        self.assertEqual(self.check('Never use legacy')['exit_code'], 1)
+
+    def test_multiple_python_imports(self):
+        self.write('src/a.py', 'import os, legacy as old\n')
+        self.assertEqual(self.check('Never use legacy')['exit_code'], 1)
+
+    def test_js_ts(self):
+        for suffix, code in [('js', "const x = require('legacy');"), ('ts', "import x from 'legacy';")]:
+            with self.subTest(suffix=suffix):
+                self.write('src/a.' + suffix, code)
+                self.assertEqual(self.check('Never use legacy')['exit_code'], 1)
+
+    def test_fail_medium(self):
+        self.write('src/a.py', 'import legacy')
+        self.assertEqual(self.check('Never use legacy', fail_on='medium')['exit_code'], 2)
+
+    def test_no_self_match(self):
+        self.assertEqual(self.check('Never use legacy\nimport legacy')['exit_code'], 0)
+
+    def test_custom_instruction_excluded(self):
+        self.write('rules.py', 'Never use legacy\nimport legacy')
+        self.assertEqual(audit(self.root, files=['rules.py'])['exit_code'], 0)
+
+    def test_skipped_directories(self):
+        for directory in ('.git', 'node_modules', 'dist', '__pycache__', '.venv', 'venv', '.hidden'):
+            self.write(directory + '/x.py', 'import legacy')
+        self.assertEqual(self.check('Never use legacy')['exit_code'], 0)
+
+    def test_ignore(self):
+        r = self.check('scripts/old.py', ignore=['scripts/*'])
+        self.assertEqual((r['ignored'], r['exit_code']), (1, 0))
+
+    def test_dedup(self):
+        self.assertEqual(len(self.check('src/a.py src/a.py')['findings']), 1)
+
+    def test_distinct_lines(self):
+        self.assertEqual(len(self.check('src/a.py\nsrc/a.py')['findings']), 2)
+
+    def test_default_order(self):
+        for name in ('MUSE.md', 'CLAUDE.md', 'AGENTS.md', 'CONTRIBUTING.md'):
+            self.write(name, 'src/a.py')
+        self.assertEqual(audit(self.root)['files_read'], ['AGENTS.md', 'CLAUDE.md', 'MUSE.md', 'CONTRIBUTING.md'])
+
+    def test_explicit_missing(self):
+        self.assertEqual(audit(self.root, files=['absent.md'])['parse_error_count'], 1)
+
+    def test_invalid_utf8(self):
+        (self.root / 'AGENTS.md').write_bytes(b'\xff')
+        self.assertEqual(audit(self.root)['exit_code'], 2)
+
+    def test_unreadable(self):
+        self.write('AGENTS.md')
+        with patch.object(Path, 'read_text', side_effect=PermissionError('denied')):
+            r = audit(self.root)
+        self.assertEqual((r['parse_error_count'], r['exit_code']), (1, 2))
+
+    def test_cap_order(self):
+        r = self.check('\n'.join('src/missing%d.py' % n for n in range(502)))
+        self.assertEqual(len(r['findings']), 500)
+        self.assertTrue(r['truncated'])
+        self.assertEqual(r['findings'][-1]['line'], 500)
+
+    def test_exact_cap(self):
+        r = self.check('\n'.join('src/missing%d.py' % n for n in range(500)))
+        self.assertFalse(r['truncated'])
+
+    def test_realistic(self):
+        self.write('scripts/new.py')
+        self.write('checks/test_app.py')
+        self.write('src/app.py', 'import legacy')
+        r = self.check('Run `python scripts/old.py`\nTests: tests/old/\nNever use legacy')
+        self.assertEqual(r['totals']['severity'], {'HIGH': 2, 'MEDIUM': 1})
+        self.assertEqual(r['exit_code'], 2)
+        self.assertIn('verify manually', r['findings'][-1]['detail'])
+
+    def test_invalid_repo(self):
+        self.assertEqual(audit(self.root / 'missing')['exit_code'], 2)
+
+    def test_high_after_cap_still_fails(self):
+        self.write('src/a.py', 'import legacy')
+        r = self.check('Never use legacy\n' * 500 + 'src/missing.py')
+        self.assertTrue(r['truncated'])
+        self.assertEqual(r['totals']['severity']['HIGH'], 0)
+        self.assertEqual(r['exit_code'], 2)

instruction_drift-0.1.0/tests/test_cli.py

@@ -0,0 +1,87 @@
+from contextlib import redirect_stdout
+import io
+import json
+from pathlib import Path
+import tempfile
+import unittest
+from instruction_drift.cli import main
+
+
+class CliTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+
+    def run_cli(self, *args):
+        out = io.StringIO()
+        with redirect_stdout(out):
+            code = main(['audit', str(self.root), *args])
+        return code, out.getvalue()
+
+    def test_empty_note(self):
+        code, out = self.run_cli()
+        self.assertEqual(code, 0)
+        self.assertIn('no instruction files', out)
+        self.assertIn('PASS', out)
+
+    def test_json(self):
+        code, out = self.run_cli('--json')
+        r = json.loads(out)
+        self.assertEqual(r['exit_code'], code)
+        self.assertEqual(r['parse_error_count'], 0)
+
+    def test_high(self):
+        (self.root / 'AGENTS.md').write_text('src/missing.py')
+        code, out = self.run_cli()
+        self.assertEqual(code, 2)
+        self.assertIn('AGENTS.md:1: HIGH', out)
+
+    def test_warn_and_threshold(self):
+        (self.root / 'AGENTS.md').write_text('Never use legacy')
+        (self.root / 'app.py').write_text('import legacy')
+        self.assertEqual(self.run_cli()[0], 1)
+        self.assertEqual(self.run_cli('--fail-on', 'medium')[0], 2)
+
+    def test_parse_error(self):
+        (self.root / 'AGENTS.md').write_bytes(b'\xff')
+        code, out = self.run_cli('--json')
+        self.assertEqual(code, 2)
+        self.assertEqual(json.loads(out)['parse_error_count'], 1)
+
+    def test_repeat_files_ignore(self):
+        (self.root / 'one.md').write_text('src/a.py')
+        (self.root / 'two.md').write_text('docs/b.md scripts/a.sh')
+        code, out = self.run_cli('--files', 'one.md', '--files', 'two.md', '--ignore', 'src/*', 'docs/*', '--ignore', 'scripts/*', '--json')
+        self.assertEqual(code, 0)
+        self.assertEqual(json.loads(out)['ignored'], 3)
+
+    def test_help(self):
+        out = io.StringIO()
+        with redirect_stdout(out), self.assertRaises(SystemExit) as context:
+            main(['--help'])
+        self.assertEqual(context.exception.code, 0)
+        self.assertIn('audit', out.getvalue())
+
+    def test_version(self):
+        out = io.StringIO()
+        with redirect_stdout(out), self.assertRaises(SystemExit) as context:
+            main(['--version'])
+        self.assertEqual(context.exception.code, 0)
+        self.assertIn('0.1.0', out.getvalue())
+
+    def test_realistic_json(self):
+        (self.root / 'AGENTS.md').write_text('`python scripts/old.py`\ntests/old/\nNever use legacy')
+        (self.root / 'app.py').write_text('import legacy')
+        (self.root / 'scripts').mkdir()
+        (self.root / 'scripts/new.py').write_text('')
+        (self.root / 'checks').mkdir()
+        code, out = self.run_cli('--json')
+        self.assertEqual(code, 2)
+        self.assertEqual(json.loads(out)['totals']['severity'], {'HIGH': 2, 'MEDIUM': 1})
+
+    def test_human_json_totals(self):
+        (self.root / 'AGENTS.md').write_text('src/a.py')
+        _, human = self.run_cli()
+        _, encoded = self.run_cli('--json')
+        self.assertIn(json.dumps(json.loads(encoded)['totals'], sort_keys=True), human)

instruction_drift-0.1.0/tests/test_extract.py

@@ -0,0 +1,57 @@
+import unittest
+from instruction_drift.extract import extract, path_token
+
+
+class ExtractTests(unittest.TestCase):
+    def test_bare_path(self):
+        self.assertEqual(extract('See src/app.py')[0].claim, 'src/app.py')
+
+    def test_backtick_path(self):
+        self.assertEqual(extract('See `docs/help.md`.')[0].kind, 'referenced-file')
+
+    def test_directory(self):
+        self.assertEqual(path_token('tests/old/'), 'tests/old/')
+
+    def test_url(self):
+        self.assertIsNone(path_token('https://example.org/src/a.py'))
+
+    def test_http_url(self):
+        self.assertIsNone(path_token('http://example.org/a.py'))
+
+    def test_glob(self):
+        self.assertIsNone(path_token('src/*.py'))
+
+    def test_unknown_extension(self):
+        self.assertIsNone(path_token('other/a.xyz'))
+
+    def test_all_extensions(self):
+        for ext in ('py', 'js', 'ts', 'md', 'json', 'yaml', 'yml', 'toml', 'sh', 'go', 'rs', 'txt'):
+            self.assertEqual(path_token('other/a.' + ext), 'other/a.' + ext)
+
+    def test_directory_roots(self):
+        for root in ('src', 'tests', 'docs', 'examples', 'scripts', 'bin'):
+            self.assertEqual(path_token(root + '/sub/'), root + '/sub/')
+
+    def test_command(self):
+        self.assertEqual(extract('Run `python scripts/run.py`')[0].kind, 'script-in-command')
+
+    def test_dot_script(self):
+        item = extract('Run `./scripts/run.sh`')[0]
+        self.assertEqual(item.claim, './scripts/run.sh')
+        self.assertEqual(item.kind, 'script-in-command')
+
+    def test_make(self):
+        self.assertEqual(extract('Run `make check`')[0].claim, 'make check')
+
+    def test_prohibition_forms(self):
+        for prefix in ('Do not use', 'never use', 'must not use', 'avoid using'):
+            self.assertEqual(extract(prefix + ' `legacy`.')[0].claim, 'legacy')
+
+    def test_line_number(self):
+        self.assertEqual(extract('\n\nsrc/a.py')[0].line, 3)
+
+    def test_dedup(self):
+        self.assertEqual(len(extract('src/a.py src/a.py')), 1)
+
+    def test_no_plain_filename(self):
+        self.assertEqual(extract('Read README.md'), [])