feat: project provenance-drift warning + re-pin for assistant refer-back

[Jammy2211]

Overview

Finish the science-project → assistant refer-back mechanics locked in skills/start-new-project.md. A project created by start-new-project refers back to the autolens_assistant clone for skills/ + wiki/ rather than vendoring a copy; the resolution order ($AUTOLENS_ASSISTANT → sibling ../autolens_assistant → clone-on-demand into gitignored sources/autolens_assistant/), the env-var name, and the project.yaml assistant_ref provenance pin are already specified in the skill. The audit against current main shows one mechanic from the Mind prompt genuinely missing: the non-blocking provenance-drift warning — compare the resolved clone's commit against assistant_ref.commit, warn on mismatch, offer to re-pin, never hard-block or force a checkout.

Filed under --auto (effective level: safe = min(header safe, feature/small cap safe)); this plan is written to the issue per the autonomy contract — no Plan-Mode hold.

Plan

• Add the provenance-drift check to the skill's "Locating the assistant from a project" section: after resolution, compare the clone's HEAD to project.yaml's assistant_ref.commit; on mismatch warn (never block, never checkout) and offer a re-pin that updates assistant_ref.commit.
• Mirror a one-line instruction in the generated thin AGENTS.md template so a copilot invoked inside a project performs the check without reading this skill first.
• Note the re-pin act in the journal convention (a drift decision is a project decision — one line, no new machinery).
• Gate with the repo's own audit (autoassistant/audit_skill_apis.py incl. --check-citations) + pytest; markdown-only change, no library surface.

Detailed implementation plan

Affected Repositories

• autolens_assistant (primary, only; public generic template — no personal content)

Branch Survey

Repository	Current Branch	Dirty?
./autolens_assistant	main	clean (one untracked personal file, james.bib — must not be committed)

Suggested branch: feature/assistant-ref-mechanics (in-place; repo develops in-place, no worktree claim conflict)

Implementation Steps

1. skills/start-new-project.md § "Locating the assistant from a project" — append the drift-check paragraph: resolved-clone commit vs assistant_ref.commit; mismatch → non-blocking warning stating both commits + what drift means (toolchain provenance, not correctness); offer re-pin (project.yaml update + journal line); explicitly never force a checkout (the manifest records what was actually used — that stays the operative record).
2. Same file, thin AGENTS.md template ("## The assistant" block) — add one line: "After resolving, compare the clone's commit to project.yaml assistant_ref.commit; if they differ, note the drift and offer to re-pin — never block on it."
3. Same file, Phase 2 (Work) — one clarifying clause tying the re-pin offer to the existing journal convention (dated entry references the re-pin; no second log).
4. Verify no stale cross-references: wiki/core/external/*.md + modes/maintainer.md mentions of the locate rule stay consistent.

Key Files

• skills/start-new-project.md — all edits land here (the locked design doc + generated templates)

Verification

1. python -m pytest autoassistant/tests -q green.
2. python autoassistant/audit_skill_apis.py and --check-citations pass (no new Project:path citations, no symbol drift).
3. Grep: resolution rule + drift check consistent between the skill body and the generated AGENTS.md template.

Original Prompt

Click to expand starting prompt

A science project created by start-new-project is a separate, self-contained

Type: feature / Target: autolens_assistant / Difficulty: small / Autonomy: safe / Priority: high

A science project created by start-new-project is a separate, self-contained repo that refers back to the autolens_assistant copilot for its skills/ and wiki/ rather than vendoring a copy. The model is already locked and partly implemented in autolens_assistant/skills/start-new-project.md (see the "Locating the assistant from a project" section and the Create scaffold). This task finishes the resolution + provenance mechanics — it is implementation detail, not a fresh decision.

What to implement:

• Resolution order when the copilot is invoked inside a project: an environment variable pointing at a local assistant clone -> a sibling directory (../autolens_assistant) -> clone-on-demand of the recorded URL into a gitignored path (sources/autolens_assistant/), mirroring the source-of-truth sources/ clone pattern in autolens_assistant/AGENTS.md.
• Pick the env var name (proposed: AUTOLENS_ASSISTANT) and document it in the thin AGENTS.md that start-new-project generates for each project.
• Provenance pin (record, not enforced checkout). The project records the assistant repo URL + commit in project.yaml (assistant_ref), and every run manifest already records assistant: {repo, commit}. Day-to-day operation uses the resolved current clone; the manifest captures what was actually used.
• Mismatch warning (non-blocking). If the resolved assistant clone's commit differs from project.yaml's assistant_ref.commit, warn the user about provenance drift and offer to re-pin; never hard-block or force a checkout.

(Audit at start_dev 2026-07-09: the first three bullets already shipped in the skill on main; this task implements the fourth + mirrors the check into the generated project docs.)

[Jammy2211]

PR open — run complete at PR-open per the autonomy contract

PR: #44 (feature/assistant-ref-mechanics, 1 file, +14)

What shipped: the provenance-drift check in "Locating the assistant from a project" (compare resolved clone commit vs assistant_ref.commit; warn once per session; offer re-pin recorded as one journal line; never block, never checkout), a one-line mirror in the generated thin AGENTS.md, and the Phase-2 journal tie-in.

Start_dev audit finding: the prompt's first three bullets (resolution order, AUTOLENS_ASSISTANT env var, assistant_ref pin + manifest provenance) were already on main — the task narrowed to this fourth mechanic.

Gate (all four legs): tests 39 pass + symbol audit 0/117 + citations 0/388 · smoke n/a (markdown-only, no downstream script surface) · review faculty CLEAN · Heart YELLOW with the reason set exactly contained in the launch acknowledgement (recorded in the task's active.md entry).

Workspace impact: none — leaf template repo, nothing imports it.

Merge stays human (validation checklist on the PR). Calibration row appended to autonomy_log.md.