Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
387a647
fix(docs): harden G01 evidence packet for issue 79
jjangg96 Sep 26, 2026
24c1253
Harden issue 79 evidence scanner review findings
jjangg96 Sep 27, 2026
00fc5c4
docs: record scoped Python evidence harness exception
jjangg96 Sep 27, 2026
9548096
fix evidence scanner review gaps
jjangg96 Sep 27, 2026
8b5f35b
fix launcher iterable scanner bypasses
jjangg96 Sep 27, 2026
184701d
Harden issue 79 evidence scanner
jjangg96 Sep 27, 2026
9e92128
fix: harden issue 79 evidence scanner flows
jjangg96 Sep 27, 2026
dac58b4
fix: close issue 79 review boundary gaps
jjangg96 Sep 28, 2026
b79709b
Harden issue 79 evidence scanner against reviewed alias bypasses
jjangg96 Sep 28, 2026
9233241
Close issue 79 review gaps in scanner and evidence parity
jjangg96 Sep 28, 2026
a61c35f
fix(evidence): close issue 79 review bypasses
jjangg96 Sep 28, 2026
2c755af
fix(evidence): close reviewed AST provenance gaps
jjangg96 Sep 28, 2026
1f5f89b
fix(evidence): harden output and launcher provenance
jjangg96 Sep 28, 2026
1784c15
fix(evidence): close output and path alias gaps
jjangg96 Sep 28, 2026
bda0eed
fix(evidence): track scoped aliases and callable taint
jjangg96 Sep 28, 2026
db8faba
Harden issue 79 evidence scanner and worktree root guard
jjangg96 Sep 28, 2026
7e277ab
Close issue 79 review taint and config gaps
jjangg96 Sep 28, 2026
a55fb9d
Close issue 79 final evidence scanner review gaps
jjangg96 Sep 28, 2026
b3c335b
Harden issue 79 scanner and evidence parity gates
jjangg96 Sep 28, 2026
6f3f8c8
Close reviewed evidence scanner bypasses
jjangg96 Sep 28, 2026
31c2e60
Harden G01 evidence scanner against indirect aliases and mutators
jjangg96 Sep 28, 2026
b902f7d
Close exact-head G01 scanner review findings
jjangg96 Sep 28, 2026
9a31f99
Close module dictionary, shutil alias, and AWK review gaps
jjangg96 Sep 28, 2026
86d90df
Close reader, signal, assertion, and jq review gaps
jjangg96 Sep 28, 2026
f24c73a
Close independent G01 scanner bypasses
jjangg96 Sep 28, 2026
cf4ae9e
Close recursive reader and nested alias review gaps
jjangg96 Sep 28, 2026
415e551
Close remaining grep and exception alias gaps
jjangg96 Sep 28, 2026
2390a54
Close abbreviated grep and warning alias gaps
jjangg96 Sep 28, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions docs/decisions/0004-offline-python-ast-regression-tooling.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# ADR 0004: Narrow Python exception for offline Python-AST evidence tests

Status: accepted for the issue #79 evidence-tooling scope upon merge of PR #103;
the candidate remains subject to independent review and exact-head Codex review.

## Context and evidence

[ADR 0001](0001-language-and-boundaries.md) selects Go for the CLI, background
service, scheduler and state reconciliation. That product decision is unchanged.
The [G01 evidence packet](../evidence/g01-recovery-packet.md) already contains a
Python AST-based audit of Python and shell prescriptions. Issue #79 needs tests
of that existing implementation, including Python loop/comprehension targets,
call aliases and definition-time expressions.

At candidate `387a647355e48d44333954fadf48d5b02335290c`, the standard-library
Python harness reproduced the seven recorded finding classes and passed eight
focused cases after their initial corrections. Independent review then found
additional reader/iterator gaps; [Codex review of that exact candidate](https://github.com/1XP-AI/gh-runnerd/pull/103#pullrequestreview-5325780932)
also identified loader and language-policy gaps. Those findings remain blockers
until their correction or evidence-based disposition is reviewed; the eight-test
result is not comprehensive safety proof. The local interpreter used for this
evidence is CPython 3.14.3; no other interpreter/platform coverage is implied.

The harness uses Python's standard-library `ast`, `unittest` and local Git
fixtures, without third-party Python packages. Implementing a separate Python
parser in Go would duplicate the language semantics under test or introduce a
parser dependency. A Go wrapper that invokes the same Python checks would not
remove the interpreter dependency. No comparative maintenance or performance
benchmark has been run; this decision rests on testing the existing AST audit
directly and keeping the exception bounded.

## Decision

Permit Python only for
`scripts/evidence_packet/issue79_regression_test.py` and its offline regression
fixtures for the existing packet audit. This is not permission to implement
product behavior or general repository tooling in Python. Any broader use needs
a separately reviewed decision. The CLI, daemon and production adapters remain
Go; no Python interpreter or package is bundled into release artifacts.

The harness must use only the standard library and explicitly selected local
Git fixture operations. Invoke it with `python3 -I -B`: isolated mode ignores
the current directory, `PYTHONPATH` and user-site imports, while `-B` avoids
bytecode artifacts. Record the actual interpreter and test results. Adding
dependencies, automatic hosted execution, or a broader supported interpreter
matrix requires separate review; this ADR does not claim those checks have run.

## Trust and execution boundaries

- Python/shell regression specimens remain data for AST/token inspection; they
must not be evaluated or launched.
- The scanner functions are the reviewed implementation under test, not
untrusted executable test data. This harness is not a Python sandbox or a
replacement for source review and runner trust policy.
- Loading packet definitions must reject unreviewed imports, decorators and
non-reviewed definition-time expressions before evaluation. A modified packet
must not acquire an import/decorator/default-expression execution path merely
because it contains a matching scanner fence.
- Local Git fixtures use task-owned temporary repositories and synthetic values.
The harness must not contact GitHub, dispatch workflows, access credentials,
or operate existing runners, Docker, Keychain or launchd.
- Repository/PR review, exact-head identity and live-operation authorization
gates still apply. Neither this exception nor green synthetic tests complete
G01/G02 or establish hostile-code isolation.

## Consequences and rollback

Maintainers now have one explicitly scoped interpreter-dependent evidence test.
Its manual focused results must be reported separately from Go/hosted checks;
passing Public CI does not imply this Python harness ran. Reconsider the exception
if the packet audit is extracted or replaced by a reviewed implementation with
equivalent regression coverage.

Rollback is a reviewed revert of the harness and this exception, retaining Go
product code and unrelated evidence. Do not remove an existing safety check
without an explicit replacement or a documented reopening of the affected gate.
Loading