feat: science projects inherit the PyAuto* API code-gate via refer-back

[Jammy2211]

Overview

The assistant protects generated code with a PreToolUse hook (.claude/hooks/validate_pyauto_code.py, backed by autoassistant/audit_skill_apis.py) that blocks PyAuto* symbols written from memory. A spun-off science project deliberately does not copy the copilot machinery — but users generate and run PyAutoLens code inside projects too, so the project should get the same gate. Lean design: refer-back, not vendoring — the validator stays in one place (the assistant) and the project's hook resolves it at runtime.

Directly strengthens the fork-and-continue story shipped in #45: a collaborator who clones the project inherits the same code-grounding protection.

Plan

• start-new-project.md Create §5 scaffolds a thin .claude/settings.json whose PreToolUse(Bash) hook resolves the assistant at runtime ($AUTOLENS_ASSISTANT → sibling ../autolens_assistant → sources/autolens_assistant) and execs the assistant's validate_pyauto_code.py; assistant absent → exit 0 (fail-open, matching the gate's own philosophy). On by default (user decision 2026-07-10): fail-open means it can never block a collaborator who lacks the assistant clone.
• Generated project AGENTS.md template gains the cross-tool caveat: only Claude Code runs .claude/ hooks; other harnesses self-enforce by running the resolved assistant's audit_skill_apis.py --code/--file before executing generated PyAuto* code.
• No copy of autoassistant/ or hook code into the project; no baked absolute paths.

Detailed implementation plan

Affected Repositories

• autolens_assistant (primary, only)

Branch Survey

Repository	Current Branch	Dirty?
./autolens_assistant	main (post-#46)	clean (untracked personal james.bib, untouched)

Suggested branch: feature/science-project-api-gate (in-place, no worktree)

Implementation Steps

1. skills/start-new-project.md Create §5: add .claude/settings.json to the generated lean project tree listing; add a template block after the project.yaml block:
   • hook command (single-line POSIX sh): iterate "$AUTOLENS_ASSISTANT", "$CLAUDE_PROJECT_DIR/../autolens_assistant", "$CLAUDE_PROJECT_DIR/sources/autolens_assistant"; on first hit exec python3 "<hit>/.claude/hooks/validate_pyauto_code.py" (stdin JSON passes through); else exit 0.
   • validate_pyauto_code.py resolves audit_skill_apis.py relative to itself, so the assistant's validator backs the project hook with zero copies.
2. Thin AGENTS.md template (same file): add a short "Code gate" bullet under "## The assistant": the hook fires only on harnesses with hook support (Claude Code); on Codex/Gemini/other harnesses, self-enforce by running python <resolved-assistant>/autoassistant/audit_skill_apis.py --code "<snippet>" before executing generated PyAuto* code — never guess symbols from memory.
3. Note the gate in the Create §5 "Generate the lean project tree" comment line.

Validation

• Scaffold a scratch project dir (session scratchpad) with the generated .claude/settings.json; pipe a fake PreToolUse tool_input JSON containing a dead symbol (e.g. al.FitImagingPlotter) through the hook command with the assistant resolvable → expect deny report; unset/point away the assistant → expect silent allow (exit 0).
• autoassistant/audit_skill_apis.py --check-citations clean.

Key Files

• skills/start-new-project.md — scaffold template additions
• (read-only reference) .claude/hooks/validate_pyauto_code.py, .claude/settings.json

Original Prompt

Click to expand starting prompt

The assistant protects generated code with a PreToolUse hook that blocks PyAuto* symbols written from memory that don't exist in the installed stack — autolens_assistant/.claude/hooks/validate_pyauto_code.py, backed by autolens_assistant/autoassistant/audit_skill_apis.py and wired in autolens_assistant/.claude/settings.json.

A spun-off science project (created by autolens_assistant/skills/start-new-project.md) refers back to the assistant and deliberately does not copy autoassistant/ or the rest of the copilot machinery. But a user will still generate and run PyAutoLens code inside the project, so the project should get the same API code-gate.

Decision + implementation (lean: do it via refer-back, don't copy autoassistant/): start-new-project generates a thin .claude/settings.json in the project that wires the PreToolUse code-gate to the referenced assistant's audit_skill_apis.py, resolved through the same assistant-ref mechanism the project already uses. The hook command must resolve the assistant path at runtime (env var -> sibling -> cloned sources/autolens_assistant/), not bake in an absolute path. Cross-tool caveat: only Claude Code runs .claude/ hooks. Codex/Gemini in the project rely on the prose "ground against the live API, don't guess" rule inherited from the assistant's AGENTS.md via refer-back — state this in the generated project docs so it isn't a silent gap. Decide whether the gate is on by default in generated projects or opt-in during setup. [Decided 2026-07-10: on by default, fail-open.]

[Jammy2211]

Shipped and merged: PR #48 (squash). Generated projects now carry the code-gate by default (fail-open). Validation matrix on the PR. Next in batch: per-project literature (core hybrid).