Skip to content

refactor(python): simplify backends and guide future conversions - #194

Merged
BjRo merged 4 commits into
mainfrom
refactor/simplify-python-plugin-mechanics
Sep 18, 2026
Merged

BjRo merged 4 commits into
mainfrom
refactor/simplify-python-plugin-mechanics

Conversation

@BjRo

@BjRo BjRo commented Sep 18, 2026 •

Copy link
Copy Markdown
Owner

Why

Follow up the Python conversions in #175, #176, and #177 by simplifying their internals and removing unused entrypoint machinery while preserving the documented console interfaces.

What changed

  • Skill authoring: replace mutual recursion with iterative argument consumption, use native path containment, and simplify parent canonicalization. Remove unused module-execution aliases and stale launcher documentation; move the three shell regression suites under backend tests and update their callers.
  • Discovery: simplify flag/value parsing and terminal-period handling; remove the unused command-name override.
  • Verification: use an explicit translation table for destination escaping and one error-handling boundary for validation and rendering.
  • Keep each plugin self-contained, update its invariant, and bump both manifests and its locked package. The three plugins have separate commits.
  • Make future conversions follow the same approach: repository guidance (shared by Codex and Claude), Python quality rules, and the portable authoring checklist require idiomatic Python, focused reuse, and removal of unnecessary shims and compatibility branches. Preserve required public behavior rather than translating Bash structure verbatim.

Verification

  • bun run check:python: passed repository-wide; reran the discovery package gate after its final entrypoint cleanup. Changed packages: skill authoring 75 tests, 98.29% statements / 96.72% branches; discovery 32 tests, 96.91% / 100%; verification 33 tests, 100% / 100%.
  • Before/after comparison: 55,987 shell-parser outcomes, 66,430 frontier-parser outcomes, 10,000 escaping inputs, and four terminal-period boundaries matched. Five new public-boundary argument tests passed before and after refactoring.
  • Fresh copied-plugin installation and public commands passed locally for all three plugins. Three shell regression suites passed under observed Bash 3.2.57; Bash 5 is unavailable locally and remains unverified there.
  • bun run lint, lint:shell, lint:ts, typecheck, check:decisions, and check:docs: passed. All five skills passed the inspector; all three Claude manifests passed native validation.
  • Skill-authoring audit eval: Claude passed task and activation. Codex passed the task in both candidate trials; activation failed once because only part of the skill body was read, then passed on an unchanged repeat. The unchanged main control also passed. This is mixed activation evidence, not a clean reliability result.
  • Discovery migration-frontier eval: task checks passed on both hosts, but activation failed. Codex read only part of the primary skill; Claude lacked evidence of the required supporting grilling read. The unchanged main Codex control also passed the task and failed activation order (it completed the primary read after the supporting skill). The planning skill body is unchanged in this PR. These activation limitations remain visible; this PR does not claim all live evals pass.
  • Final CI passed on 262cbdf: all 73 Python/platform jobs plus documentation, including Python 3.10–3.13 and fresh copied-artifact execution on Linux, macOS, and Windows. The conversion-guidance delta also passed local formatting, documentation, inspector, native manifest validation, and independent review.
  • Verification retained-report eval: Codex passed task and activation. Claude passed activation, candidate-preservation, provider-report validation/accessibility, and the renderer's final-link check, but the integration case failed because the unchanged code-review provider returned blocked with missing reader-route evidence instead of a validated finding. The provider reported a project-directory slug problem; this PR does not change that provider or claim that failure is repaired.
  • Live samples used Codex gpt-5.6-terra/medium and Claude claude-sonnet-5/medium, one trial per invocation, 80% threshold. Candidate totals: seven trials (three cases per host, plus one authoring repeat); two additional Codex main controls. Dry preparation is not behavioral evidence, and these samples are not a reliability estimate. The later migration-guidance prose was checked by documentation/manifest tools and independent review, not a new live conversion trial.
  • One fresh-context source review found no material issues.

Review notes

No runtime shell launcher remains in these plugins. Shell files retained in this change are regression tests and native fresh-install tests. Frozen UV console names, arguments, diagnostic text/order, output streams, exit statuses, symlink handling, and assessment bytes remain the supported contract. Removed Python module-execution aliases and the unused internal program-name override are intentionally not retained for compatibility.

Checklist

  • I have read and followed CONTRIBUTING.md, including the contribution
    licensing terms.
  • I added or updated the applicable invariant before implementation, or
    this change does not affect a capability invariant.
  • I added or updated colocated evals, or this change does not affect skill
    behavior.
  • I confirmed that each changed plugin remains self-contained, or this
    change does not affect plugin content.
  • I ran bun run check:python, or this change does not affect registered
    Python packages or their repository quality infrastructure.

@BjRo BjRo changed the title refactor(python): simplify three plugin backends refactor(python): simplify backends and guide future conversions Sep 18, 2026
@BjRo
BjRo merged commit 72b89fd into main Sep 18, 2026
75 checks passed
@BjRo
BjRo deleted the refactor/simplify-python-plugin-mechanics branch September 18, 2026 07:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant