agent2learn

# Agent2Learn — implementation context

Agent2Learn is a local-first, open-source tool for University of Waterloo students. It turns the
courses available through a student's own LEARN (D2L Brightspace) account into a durable,
revision-safe, Markdown-twinned vault that coding agents can navigate and cite. Its product promise
is inspectability: course sources remain local, citations resolve to ordinary files, missing
coverage is explicit, and lexical similarity is never presented as proof that coursework is
correct.

## Read first

These documents are authoritative, in this order:

1. [`docs/superpowers/specs/2026-08-24-agent2learn-public-release-design.md`](docs/superpowers/specs/2026-08-24-agent2learn-public-release-design.md)
   — product, safety, data, UX, and architecture contract.
2. [`docs/superpowers/plans/2026-08-24-agent2learn-public-release.md`](docs/superpowers/plans/2026-08-24-agent2learn-public-release.md)
   — executable TDD implementation sequence and definition of done.
3. [`docs/superpowers/specs/2026-08-25-algorithm-reference.md`](docs/superpowers/specs/2026-08-25-algorithm-reference.md)
   — the tokeniser, `GENERIC` stopwords, lecture ranking, download routes, and HTTP constants that
   the design spec references but does not define. **Required for Tasks 8, 10, 11, 18, and 19**; a
   cold-read audit put those tasks at 30–70% buildable without it.
4. [`docs/LAUNCH.md`](docs/LAUNCH.md) — release gates and truthful public positioning.

If prose here conflicts with the design spec, the spec wins. If implementation evidence invalidates
the spec, stop, preserve the evidence, and update the spec and plan together before changing the
architecture.

## Historical state — 2026-09-02

- Public Git repository on `main`. **Not** a package release: nothing is published to PyPI.
- **Tasks 0 through 23 are complete as automated implementations. The v0.1 command surface is
  finished; what remains is manual and publication gating, not coding.** Task 9's real-browser
  same-device validation and the supervised upload test remain release gates.
  - **Tasks 18–23 landed on the `v0-1-completion` branch** (`89848b3`, `b9a2aa0`, `5de52c4`,
    `5290a8b`, `8405cbc`, `5b24796`), taking the suite from 637 to 832 passing tests.
  - **Task 18** — `ground.py` and `a2l ground`. A file becomes citable only when the manifest and
    the course content map agree it came from a LEARN source ID **and** both the archived original
    and its Markdown twin still hash to their recorded digests. Drafts, downloaded solutions,
    untracked siblings, and generated reports are therefore unreachable. Lecture ranking sorts
    `(-score, path)`, not `rglob` order, so packs are byte-identical across platforms. `--solve`
    does not exist.
  - **Task 19** — `check.py` and `a2l check`. Reuses Task 18's source set, so a claim can never
    cite the draft itself or another student-authored answer. Scores are exact integer basis
    points; `score_bp` is provably the floored rational form and a parametrised test pins it to
    `exact_score`. `possible_conflict` fires only for two allowlisted templates whose token
    sequences are otherwise identical, and a differing number never qualifies.
    **The mandated benchmark caught a real defect:** the first implementation took 19.95 s for 100
    claims over 50,000 lines against a 2 s target, because it built a `Citation` per scored line
    and used `Fraction` in the hot loop. Counting overlap off the postings lists and materialising
    only kept spans brought it to 1.77 s.
  - **Task 20** — `submit.py`, `_release.py`, `a2l enable-submit`, `a2l submit`.
    `SUBMISSION_AVAILABLE` is **False**, so this build refuses uploads; tests reach the path only
    through an injected `SubmissionCapability`, never by monkeypatching the production check. Two
    independent gates precede any POST, the exact bytes are staged before the preview so replacing
    the original cannot change what is sent, only the documented `mysubmissions` route is used with
    no fallback, a group Dropbox is named then refused, and read-back must match folder, filename,
    size, and a timestamp after confirmation or the outcome is reported as unknown. The
    confirmation code is consumed whether the POST succeeds or fails, so nothing can be retried by
    re-confirming.
  - **Task 21** — `install.sh` and `install.ps1`. One reviewed constants block pins uv 0.12.5 and
    agent2learn 0.1.0; an equal-or-newer uv is reused, an older one is replaced after disclosure,
    and an unparseable version is a hard refusal rather than a guess. Neither script accepts a
    package, index, or URL override, needs administrator rights, or writes agent or browser state.
    CI smokes both against the candidate build staged as a `UV_FIND_LINKS` source.
  - **Task 22** — public documentation, written **after** Task 23 so it describes the final command
    surface. `tests/test_docs.py` enforces the claims rather than trusting them: forbidden phrases,
    the evidence scan never described as verification, exactly three advertised install options,
    every documented command *and flag* existing, every implemented command documented, and no link
    to a file that does not exist.
  - **Task 23** — `upgrade.py`, `a2l upgrade`, `a2l completions`, and `.github/workflows/release.yml`.
    `upgrade` is the only command that contacts the network on its own behalf; a network-sourced
    version is validated against a narrow PEP 440 subset before becoming a subprocess argument, and
    no call uses a shell string. The release workflow runs only on a `v*` tag, refuses a tag that
    disagrees with the packaged version, refuses to publish a build with uploads enabled unless the
    supervised gate was recorded, builds exactly once, and promotes those same bytes through
    attestation, TestPyPI, and a protected PyPI environment using Trusted Publishing.
- **Post-merge PR #4 audit/remediation — 2026-09-01:** the pre-remediation exact merge `bc62d101`
  passed its remote 17-job CI run, but a fresh local review found and fixed five boundary issues: oversized
  download refusals no longer fall through to another route; unknown-size topics no longer consume
  a byte-bounded priority plan as zero bytes; any metadata error keeps `a2l init` before the file
  phase and leaves `metadata_complete` false; saved sessions are reused only for the selected LEARN
  origin; and source-less `conversion_gap` rows reconcile to `metadata_only`. The detect-secrets
  exclusion regex and stale contract documentation were corrected at the same time. That
  remediation is **committed and pushed to `main` as `77fafbe`**, so `main` no longer ships the
  five defects; the complete evidence is in
  [`docs/PR4_POST_MERGE_AUDIT.md`](docs/PR4_POST_MERGE_AUDIT.md).
- **Fresh whole-repository audit — 2026-09-01.** Every automated gate was re-run from scratch on
  `3372ba4` and passed, and then the real production pipeline's output (via
  `golden_support.run_full_pipeline`) was driven through the actual CLI. **That step found three
  defects the 912-test suite had missed, because the Task 18/19 unit fixtures were hand-built and
  did not match what `ingest.py` actually writes.** All three are fixed with red-green tests:
  1. **`a2l ground COURSE "Problem Set 1"` failed with "grounding item was not found".** The
     pipeline names assignment folders `{title} {dropbox id}` (e.g. `Problem Set 1 700001`) so
     same-titled assignments cannot collide, but `resolve_item` compared the typed title against
     the folder name only. The documented usage did not work on a real vault. `ground.py` now
     joins each folder to its `assignments.json` row and accepts the title, the bare id, or the
     folder name; two same-titled assignments make the bare title ambiguous and the error names
     the id forms. Prompt lookup matches by id, and ranking uses the title's words rather than the
     selector, so a folder id can no longer inflate or poison retrieval.
  2. **Two false next actions.** An assignment whose title matched no lecture produced
     "no current course material was verified for this item; run: a2l sync" from `ground`, and
     "no verified course material was found to scan; run: a2l sync" from a scoped `check` — while
     ten verified twins existed. Sync would have changed nothing. Both now distinguish "this course
     has nothing verified" (a sync problem) from "nothing verified matched this assignment" (not
     one), and the scoped `check` message says to scan the whole course instead. Scoped reports
     now name the assignment title, not the raw folder name.
  3. **A markdown image was scored as a claim.** `check` cited a 100-character base64 data-URI as
     `evidence_found` because the identical blob appeared in the source twin. Images are now
     stripped before segmentation and an image-only line is structure, not a claim.
  Also refreshed `docs/COVERAGE.md`, which the PR #4 remediation had left stale. The lesson is
  recorded here because it is the general one: **a fixture the implementer wrote to match their
  own assumptions cannot catch the assumption being wrong; drive the production pipeline's real
  output through the CLI at least once per feature.** That check is now permanent as
  `tests/test_cli_over_pipeline.py`.
  **Evidence:** the fixes landed as `a315a97` and `48e0672`; run
  [33581973166](https://github.com/ManagementMO/agent2learn/actions/runs/33581973166) on `48e0672`
  is 17/17 green. The first attempt (`a315a97`) had the new test run the pipeline five times and
  **all four Windows matrix jobs hit the 20-minute timeout** (cancelled at the Tests step; the other
  13 jobs passed). Measured: Windows takes 15 min without the test, ~20.2 min with five pipeline
  runs, 16.5 min with one — so each full-pipeline test costs Windows ~1.3 min. The test now runs
  the pipeline once, and the matrix job's `timeout-minutes` is 30, documented in `ci.yml` as a
  hang guard rather than a performance budget. Windows CI is the slowest gate by a factor of 4–8
  and is the one to watch when adding pipeline-backed tests.
- **Assignment-prompt follow-up — 2026-09-02.** The synthetic Dropbox corpus now carries one
  canonical D2L `CustomInstructions` RichText record, and the real metadata → file → conversion →
  index → grounding path proves that `assignments.json` records `instructions_md`. Fresh prompt
  folders use `{title} {dropbox id}` consistently, the specialized `richtext-sanitizer` twin is
  not re-converted as generic HTML, and a locally modified prompt twin is preserved with a
  `local-modification` history marker before refresh. The deliberate golden-vault update adds the
  two prompt files and changes only the related manifest, assignment metadata, and README hashes;
  the golden tree now contains 53 files. Focused ingest/converter regressions and the permanent
  CLI-over-real-pipeline test cover the behavior.
- **Release-gate correction — 2026-09-02.** The only `v0.1.0` tag run
  ([33587301177](https://github.com/ManagementMO/agent2learn/actions/runs/33587301177)) failed
  closed before build because the release job ran Python 3.12 while mypy defaulted to the project
  3.11 target. `b1288da` corrects that target; its exact-tip CI run
  ([33587798217](https://github.com/ManagementMO/agent2learn/actions/runs/33587798217)) is green
  across all 17 jobs, and the local release-compatible gate passes. The tag still points at the
  older commit and no package or GitHub release exists, so a fresh matching tag is still required
  after this follow-up lands.
- **The review-remediation checkpoint is committed and pushed to `main` as `276bda3`.** A fresh
  local run on that exact tree reports 858 passing tests and 4 skipped. The exact-SHA remote
  acceptance run is [33291418755](https://github.com/ManagementMO/agent2learn/actions/runs/33291418755);
  it passed all 17 jobs across Windows, macOS, and Linux.
- **Release-promotion hardening is committed and pushed to `main` as `a2a8333`.** The protected
  PyPI publication job now precedes public GitHub-release creation, and every TestPyPI smoke job
  compares the published version's exact filename/SHA-256 set with the one-build artifact before
  installing it. The focused release guard suite is 55 passing, the full local suite is 860
  passing / 4 skipped, and the exact-SHA remote acceptance run is
  [33294678005](https://github.com/ManagementMO/agent2learn/actions/runs/33294678005) with all
  17 jobs green.
- **Same-device CDP authentication hardening is committed and pushed to `main` as `a39239b`, with
  its type-portability follow-up `9876c57`.** A fresh local run on `9876c57` reports 898 passing
  tests and 4 skipped, and the exact-SHA remote acceptance run is
  [33357788896](https://github.com/ManagementMO/agent2learn/actions/runs/33357788896) with all 17
  jobs green. Note that the intermediate commit `a39239b` failed four jobs on a typing error and
  was fixed before the branch settled; only `9876c57` is green.
  - **The interactive egress policy changed and the spec and plan were updated with it.** An
    undeclared **document or iframe** still stops sign-in and reports only the sanitized hostname
    plus the `--paste` fallback. An undeclared **optional subresource** is now failed locally
    instead of aborting the command, so an analytics beacon cannot kill an otherwise valid
    sign-in. Nothing egresses either way, an unknown resource type is treated as fatal, and the
    authoritative `whoami` check still decides whether a session is saved.
  - **`UWaterloo.auth_hosts()` is now populated** — see Task 6 above for the exact list and the
    gate that applies to it.
  - **Evidence still owed.** `docs/AUTHENTICATION.md` calls `adfs.uwaterloo.ca` the *observed*
    hand-off, but this repository contains no recorded redacted host evidence for either entry,
    and the removed docstring previously argued an empty list beat guessing at a redirect target.
    Before release, either record the redacted same-device host observation or restate the list as
    provider-boundary reasoning. Populating it was almost certainly right — an empty list blocks
    Duo and forces everyone onto `--paste` — but the justification belongs in the repository.
    `duosecurity.com` is also a whole-provider boundary covering every Duo tenant, not only
    Waterloo's; that is a deliberate, documented trade for tenant-subdomain churn.
- **ATTENTION: CI grew from 14 to 17 jobs** (`installer · ubuntu-latest|macos-latest|windows-latest`).
  Branch protection on `main` now requires all 17 named checks. The existing `strict: false` and
  `enforce_admins: false` settings are unchanged; the three installer contexts were added to the
  required-checks list after the release review.
- **Real CI found three Windows defects that a green macOS run could not.** Worth reading before
  trusting a local pass on this repository again:
  1. `tests/test_installers.py` was **uncollectable on Windows** (`import pty` →
     `ModuleNotFoundError: No module named 'termios'`). Pytest exited 2 during collection, so all
     five Windows matrix jobs and the Windows installer job failed and **not one installer test ran
     there**. `pty` is now imported inside the single test that needs a terminal, the bash-driven
     behaviour tests are gated on a POSIX shell, and the nine platform-independent contract tests
     run on Windows for the first time.
  2. The release guards were **not CRLF-safe**: `uv run python` returns CRLF under git-bash, so
     `declared="0.1.0\r"` never equalled `tag="0.1.0"`. Both guards failed *closed*, so it was never
     a security hole, but a correct tag would have been refused. Both command substitutions now
     strip carriage returns.
  3. Two of my own tests were **over-generalised**: they execute step scripts from `release.yml`,
     whose job is `runs-on: ubuntu-latest`, so running them under git-bash tested an environment the
     workflow never sees. They are now gated to a POSIX shell while the text assertions that pin
     each guard's decision still run everywhere.
- **Tasks 18–23 were implemented by the controller directly, without reviewer subagents**, at the
  user's instruction. Reviews are controller self-reviews plus scripted perturbation harnesses in
  [`tools/perturb/`](tools/perturb/); the four tracked scripts now mutate and prove all 34
  submission, installer, and upgrade/release guards load-bearing. This is still weaker than an
  independent fresh-context review and is recorded as such in `progress.md`.
- **Task 20 deviated from TDD:** `submit.py` was written before its tests. Compensated with a
  14-gate perturbation harness plus two one-shot transport perturbations, but recorded as a
  deviation rather than presented as compliance.
- **The golden vault now exists and is the repository's regression tripwire.**
  `tests/fixtures/golden_vault.json` pins 53 files by SHA-256 after one full production
  metadata → explicit outline state → download → convert → index → snapshot → audit run against the
  synthetic API.
  **Never regenerate it to make an unexplained diff green** — a changed hash is either an
  output change you can state a reason for, or a regression that was just caught.
  Regenerate deliberately with `A2L_REGENERATE_GOLDEN=1 uv run pytest tests/test_golden_vault.py`,
  then confirm the same map on all three operating systems.
  - **Task 0** — packaging, licence, safety baseline. `pyproject.toml` declares the full runtime
    stack; `uv.lock` is committed; `a2l --version` works; Apache-2.0 is proven present in the built
    wheel and sdist as a PEP 639 `License-Expression`.
  - **Task 1** — 20 synthetic fixtures (13 JSON, 3 non-JSON, 4 binary) plus an offline
    `synthetic_api` harness over `pytest-httpserver`. `tools/generate_fixtures.py --check` enforces
    byte-exact reproducibility.
  - **Task 2** — CI across Windows/macOS/Linux × Python 3.11–3.14, plus the three installer jobs,
    17 jobs total, all green. `main` is branch-protected with all 17 as required checks.
  - **Task 3** — cross-platform path naming and atomic filesystem primitives, including the
    completed-download preservation rule for failed `.part` installs and the safe-name edge cases.
  - **Task 4** — platform-correct config paths, console output, expected error taxonomy, and
    privacy-bounded logging.
  - **Task 5** — structured portable manifests, revision preservation, and transactional schema
    migrations that stage `.a2l/` state and leave the original vault untouched on callback failure.
  - **Task 6** — `School` protocol, Waterloo adapter, explicit timezone rendering, conservative
    licensed-topic policy, boundary-aware matching, and a warned generic adapter.
    `UWaterloo.outline_hosts()` is still empty. `UWaterloo.auth_hosts()` is **no longer empty**: it
    returns `["duosecurity.com", "adfs.uwaterloo.ca"]`, the reviewed identity-provider boundary for
    the interactive sign-in window only. The suffix absorbs Duo's changing tenant and asset
    subdomains without becoming a wildcard, and the CDP gate additionally requires HTTPS on the
    default port with DNS-label-boundary matching. See the auth-hardening entry in
    **Current state** for what that list still owes in evidence.
  - **Task 7** — strict scoped session projection with silent keyring-to-file fallback, atomic
    protected persistence, dual-backend clearing, and no unrelated cookie attachment.
  - **Task 8** — calibrated D2L API transport with explicit timeout/redirect/egress controls,
    bounded idempotent retries, conditional streaming downloads, disk/size validation, and
    session-expiry detection; mutating redirects are never replayed, `Retry-After` covers 429/503,
    and calibration persists only discovered versions and enrolment metadata while `a2l courses`
    remains a deterministic offline view over that state.
  - **Task 9 implementation** — persistent dedicated Chrome/Edge CDP authentication, explicit
    interactive egress interception, `Storage.getCookies` filtering, authoritative `whoami`
    verification, hidden cross-platform cookie paste, and TTY-confirmed profile clearing. Live
    same-device auth on Windows, macOS, and Linux is intentionally not represented as complete
    until manually run and recorded without retaining session material.
  - **Task 10** — metadata-first, merge-not-replace course ingestion; revision-safe resumable
    downloads; excluded-host link stubs; sanitized Dropbox RichText and first-party attachments;
    opt-in pseudonymized discussions; explicit path-null fetch repair; and bounded outline
    rendering through the existing dedicated CDP connection.
  - **Task 11** — backend-isolated PDF conversion with pinned pdf-oxide, explicit external-Tesseract
    OCR gaps, named PDFium fallback, deterministic notebook/HTML/archive renderers, hash-linked
    derived metadata with threshold/page coverage, and local-twin history preservation.
  - **Task 12** — deterministic course index, provenance-checked `content_map.json`, AI-policy
    surfacing, and sync snapshots.
  - **Task 13** — `clock.py`, `audit.py`, and the golden-vault test.
    - **`clock.py` is the single wall-clock seam for anything that reaches the vault.** Vault
      writers must call `clock.now()`/`clock.stamp()`; `test_no_forbidden_calls` fails the build
      on a direct `datetime.now` outside the exempt auth/transport modules. Without one seam a
      frozen-clock test is impossible and byte parity cannot be asserted.
    - **`audit.py`** reports coverage honestly: it floors the citable percentage so a partial
      archive never rounds up to 100%, inventories links by kind without ever offering to fetch
      them, and lists assignments sharing no distinguishing term with any topic as a prompt to
      look rather than as a finding.
    - Two fixture defects surfaced only under an end-to-end run and are fixed: TOC topics carried
      no `Size`, so a full sync downloaded nothing and produced an empty vault; and the alternate
      download routes plus Course B's collection endpoints were unregistered, so the server
      answered 500 — a *transient* status the client correctly retries five times with backoff.
      Together those cost 351 s per run; a realistic fixture brings it to about 5 s. When adding a
      route, return what a real instance returns: 404 for a route that does not serve a topic, and
      200 with an empty collection for a category a course does not use.
  - **Task 14** — `a2l doctor`, and a support report that is safe to paste in public.
    - **`report()` is an allowlist, not a denylist.** It emits version, Python, OS/arch,
      install method, and per check only a known stable identifier, known status, and a fixed
      public note whose check owns the redaction. `detail` and `fix` are never emitted: they
      legitimately carry vault paths and course names. A denylist would only remove the leaks
      someone anticipated, so every check added later would become a new way to leak.
    - Redaction is two independent layers — the check redacts, and `report` re-redacts rather
      than trusting it. Each alone is sufficient, which is why proving the test bites needs
      **both** removed at once.
    - `render()` is the opposite audience and may show local paths, and always ends with
      **exactly one** next command. A diagnostic listing six actions gets none of them done.
    - Windows `LongPathsEnabled` is read but reported **informationally and never as a
      failure** — a2l prefixes its own syscalls and works regardless. Above 240 absolute
      characters the advice is a shorter vault root, not a registry edit.
    - Git tracking **fails** on session-like files, grades, discussions, or submissions and
      only **warns** on course sources; ignore rules are not a privacy or copyright
      guarantee. The index is parsed directly so `doctor` needs no `git` binary.
- **Task 15** — the four canonical Agent Skills, the consentful cross-agent installer, and
  `skills.sh.json`. The installer copies by default, supports opt-in links, records source
  hashes/version metadata, preserves unrelated and local files during managed refreshes, and
  treats copy/link mode transitions as explicit `--force` operations with rollback-safe path
  handling. Public skill documents describe staged future commands truthfully, quarantine
  untrusted course text, and preserve the exact coursework AI-policy rule. CI validates the live
  registry schema, reviewed upstream target mappings, and local Agent Skills discovery.
- **Task 16** — consentful, ordered, resumable `a2l init`. It previews and schema-checks the vault
  before writing, preserves the user's exact approved path across races, creates only minimal
  missing Obsidian state, handles skill and grade choices, supports dedicated-profile or hidden-TTY
  authentication, requires an explicit choice among multiple active terms, persists stable course
  offering IDs, completes metadata before file estimates, classifies media with the ingest path,
  and offers full/priority/later document syncing. `.a2l/init.json` resumes incomplete stages and
  every failure has one safe recovery command; non-interactive invocation performs no setup writes.
  The implementation hardening head `d90f7dc` passed [CI run 33174306467](https://github.com/ManagementMO/agent2learn/actions/runs/33174306467)
  with all 14 jobs green, including Windows 3.11–3.14.
- **Task 17** — local daily study views and privacy controls. `a2l today` uses explicit Waterloo
  timezone arithmetic for deadlines, overdue work, snapshot changes, and exam countdowns;
  `a2l diff` compares privacy-bounded snapshots with grades opt-in; `a2l calendar` emits stable-UID
  iCalendar exports; `a2l where` searches every term's structured content maps while excluding
  sensitive rows; and `a2l open` reveals only a resolved local course directory. `privacy status`
  reports redacted category state, while `privacy purge` is preview-first, exact-phrase,
  non-TTY-refusing, stale-plan-bound, symlink-safe, and allowlisted down to explicit files and
  structured records. Generated JSON rewrites are atomic, generated content is distinguishable
  from user files, and logical-deletion limits are stated in the preview.
- **Task 16.5 complete** — closes the system-level gap between completed libraries and the public
  product. `pipeline.py` is now the one metadata-first sync sequence used by `a2l sync`, `a2l init`,
  and the golden harness; it writes explicit outline/policy state, downloads by saved scope,
  converts all current local sources, refreshes indexes, writes one snapshot, and audits. Fresh
  onboarding maps actual globally detected agents to consented project-local skill paths. Doctor
  fails closed on unreadable/tracked private Git state and opens the required prefilled issue form.
  Deadlines use Waterloo local time, priority estimates share ingest's 200,000,000-byte planner,
  declined new terms are remembered without changing selection, notebook cells have deterministic
  IDs, and installed-wheel skill discovery is a matrix smoke. Final evidence: 637 passed / 4
  skipped / zero warnings locally; independent whole-branch review clean; all 14 jobs passed in
  [CI run 33226466258](https://github.com/ManagementMO/agent2learn/actions/runs/33226466258), including
  the then-51-entry golden vault and installed-wheel smoke on Windows, macOS, and Linux.
- **Post-Task 14 hardening — 2026-08-26:** a repository-wide review closed the remaining
  exception-safety, report-redaction, long-path, and cross-platform edges found after the first
  green Task 14 CI run. This includes same-origin API probes, malformed-session containment,
  linked-worktree Git inspection, per-term/empty-twin/last-sync coverage, strict public report
  fields, truthful `--open` disclosure, allowlisted structured logs, canonical redirect metadata,
  bounded archive inspection, safe snapshot timestamps, scoped cookies, symlink/hard-link-safe
  download parts, no-follow link metadata, executable and temporary-file long-path probes, and
  long-path syscall boundaries across vault writers and migration staging. The regression tests
  cover the discovered failures; they do not waive Task 9 live validation or any later release
  gate.
- **Run the gates before believing a change is done:** `uv sync --frozen --all-extras --dev` then
  `uv run ruff check .`, `uv run ruff format --check src tests tools`, `uv run mypy src tests tools`, `uv run pytest -q`,
  `uv run pytest --cov=agent2learn --cov-branch --cov-report=term-missing`,
  `uv run python tools/generate_fixtures.py --check`, `uv run python tools/check_notices.py`.
- **Verify a new gate by making it fail.** Every safety check added so far was confirmed by
  perturbation — seven fixture mutations, a notices-drift injection, a deliberately-broken offline
  guard, a `datetime.now` smuggled into a vault writer, a filename budget changed from 60 to 55,
  and a CRLF forced into every generated file. Three defects in these tasks were hidden *behind a
  passing job*, so a green badge is not evidence on its own.
- The 2026-09-01 coding follow-up is closed by the 2026-09-02 assignment-prompt work above. The
  CLI-over-real-pipeline check that found the earlier three defects remains a permanent gate,
  `tests/test_cli_over_pipeline.py`, and was proven to bite by perturbing the resolver back to
  folder-name-only (8 failures).
- Known open items, none of them coding work: the `auth_hosts()` entries have no recorded
  same-device host evidence yet (`docs/AUTHENTICATION.md` now presents them as provider-boundary
  reasoning rather than observation) and the list has never run against a live instance, which
  makes the Windows and Linux auth validation below more load-bearing than before;
  Task 9's live same-device auth still needs pass/fail
  records on Windows and Linux (macOS passed 2026-08-25); the supervised non-graded upload must
  pass for the exact release candidate before `SUBMISSION_AVAILABLE` may be flipped; PyPI Trusted
  Publishing still needs owner-side setup, while the GitHub `testpypi` and `pypi` environments now
  exist with required owner review and administrator bypass disabled; GitHub private vulnerability reporting,
  Dependabot alerts, and Dependabot security updates are enabled (2026-08-30); `mypy` covers
  `src/`, `tests/`, and `tools/`; coverage is measured in `docs/COVERAGE.md` with a 77.5% branch
  floor in CI;
  three Dependabot PRs propose versions past the declared caps; their recommendations are in
  `docs/DEPENDABOT_REVIEW.md`, but each still needs a human merge/hold decision.
- Do not publish a package, create a GitHub release, or register a production domain yet.
- **Prerequisites P1 and P2 both PASSED on 2026-08-25 (macOS).** Do not re-litigate either.
  - **P1:** a browser-harvested LEARN session authenticates a plain `requests` call on the same
    device (`whoami` 200/JSON). **Build `api.py` on `requests`.** Windows and Linux still need the
    same check before release.
  - **P2:** the documented `…/submissions/mysubmissions/` route returned 200 for a supervised
    non-graded upload and API read-back matched filename, size, and timestamp. `X-Csrf-Token` is
    required. **`mypost` is unnecessary — do not implement it.** Group submissions, closed folders,
    large files, and non-Waterloo instances remain unproven, so every submission safety control
    stays exactly as specified.
  - Live instance versions are **`lp 1.62` / `le 1.96`**, and `GET /d2l/api/versions/` is
    unauthenticated. Never hardcode versions; unauthenticated API calls return 403 `text/html`,
    which is the login-HTML shape the expiry detector must catch.

## Frozen v0.1 decisions

- Package/import name: `agent2learn`; console command: `a2l`; public project name: Agent2Learn.
- Python 3.11–3.14; `uv` for development/install; one Python engine and one canonical `skills/`
  source. No vendor plugin, MCP server, or npm runtime in v0.1.
- Licence: Apache-2.0. Use the unmodified Apache 2.0 `LICENSE`, PEP 639
  `license = "Apache-2.0"`, `license-files = ["LICENSE"]`, and no deprecated `License ::` classifier.
- PDF conversion is core: exact-pin `pdf-oxide==0.3.77`; use external Tesseract through
  `pytesseract`; keep `pypdfium2` behind `convert.ConverterBackend` as the named degraded fallback.
  pdf-oxide renders default OCR pages itself. Never invoke its built-in OCR/model-download path.
- OCR threshold: configurable, default 80 whitespace-delimited words per page. Mixed documents use
  structured pdf-oxide Markdown for healthy pages and Tesseract text for thin pages exactly once in
  source order—never append whole-document Markdown and duplicate the OCR pages.
- **The all-262-PDF acceptance run is COMPLETE. Read this before touching the converter.**
  Result at threshold 80: **96.4% of baseline words, zero failures** on either backend
  (`pdf-oxide` 397,104 words / 6,633 headings; prior baseline 412,082 / 4,745).
  This **fails the original "≥100% aggregate words" gate, and that gate was wrong.** Raw word count
  rewarded the prior backend's measured **31–46% duplicate lines** on OCR'd documents; on the eight
  worst files C/A was 52.6% by raw words but **92.0% by unique vocabulary**. Excluding one course
  whose instructor posted image-only slides, the result is **99.9% content with +59% headings**, and
  `pdf-oxide` is faster on the 213 healthy-text-layer PDFs. The residual gap is hybrid slides plus a
  whole-page OCR threshold, not extraction quality.
  **Decision: keep `pdf-oxide`. Do not revert to the prior AGPL converter on the strength of the
  96.4% number.** The earlier 105% figure came from a stratified sample that over-weighted
  image-only documents ~8× and from a harness that double-counted; both are superseded.
  **Revised Task 11 gate: zero conversion failures and ≥95% aggregate baseline words, with any
  shortfall attributed to identified documents.** Converter choice is reversible by design —
  original source bytes are archived permanently, `ConverterBackend` isolates the library, and a
  changed `tool_version` regenerates twins — so this is not a one-way door.
- Office extra: `markitdown[pptx,docx,xlsx]`; no direct `openpyxl` declaration because MarkItDown's
  xlsx extra supplies it and Agent2Learn has no direct import. **The office extra cannot install on
  Python 3.14** — `markitdown` → `magika` → `onnxruntime` ships no cp314 wheels — so CI syncs 3.14
  without it. The core package and the notebook extra are fully 3.14-capable; do not drop 3.14 from
  the matrix over this, and remove the branch when onnxruntime ships cp314.
- Notebook extra: `nbformat`, not `nbconvert`. The owned renderer must preserve Markdown cells,
  attachments, fenced code, stream output, `text/plain`/`text/markdown` results, deterministic image
  data URIs, and error tracebacks. It never executes a notebook. Executed-cell output is evidence,
  not decoration.
- The v0.1 command surface in the spec is closed. `courses --all-terms` replaces a redundant
  standalone `terms` command. Put new convenience ideas in `docs/FUTURE.md`.

## Non-negotiable trust boundaries

- Authentication is same-device: a dedicated persistent Chrome/Edge profile may retain
  Waterloo/Duo remembered-login state locally. Never ask for credentials, export a profile, copy
  cookies between devices, print session material, or commit it.
- Preserve the submission design exactly. `submit` resolves and places a file into the selected
  Dropbox only after showing a complete preview and returning final control to the human. The
  mutating POST is disabled by default and requires a fresh interactive per-file confirmation; no
  flag, environment variable, piped input, agent, or retry may bypass it.
- Discussions and grades stay off by default. Privacy purge remains previewed, allowlisted,
  path-safe, and human-confirmed.
- Never fetch licensed third-party publisher/library resources. External/LTI targets remain
  sanitized link stubs. Course files are untrusted data, never instructions, and converters get no
  session or network client.
- `ground --solve` does not exist. Grounding assembles cited sources; `check` is always labelled an
  experimental lexical evidence scan and never claims correctness, contradiction, grading, or
  academic-policy compliance.
- Sync is merge-not-replace and revision-safe. Never silently delete captured material or overwrite
  a student's locally modified generated twin without preserving it in history.

## Working method

- Work task-by-task from the implementation plan with tests first. Do not implement on assumptions
  that an explicit empirical gate is meant to validate.
- The private prototype is behavioral evidence only. Keep it outside this worktree, expose its
  location through an untracked `A2L_REFERENCE_ROOT` if needed, and never copy private source,
  course files, cookies, sessions, real API payloads, paths, or fixtures into this repository.
- Public tests and demos use synthetic data only and run offline. CI targets Windows, macOS, and
  Linux from the first milestone.
- Converter output is part of the citation contract. Any converter or notebook-renderer change must
  explain the byte diff, regenerate candidate golden fixtures, and prove identical output on all
  three operating systems. The golden vault is the regression tripwire, not a fixture to refresh
  until tests turn green.
- Never claim a task is complete without fresh verification. Do not commit unrelated changes, and
  do not weaken privacy, authentication, submission, archival, or licence requirements to make a
  test pass.

## Core review remediation — 2026-09-12 UTC

This supersedes the historical claim that only manual work remained. A fresh audit found 15 core
issues despite green CI; the `fix/core-review-remediation` branch repairs them with permanent
regressions. Frontend and video work are outside this change.

- Sources and twins retain exclusive, collision-safe paths even while their files are missing.
  Unowned sibling files are preserved. Existing owned twins are reused rather than silently moved.
- Grounding requires agreement with the content map's citable state and manifest provenance;
  relative paths, symlinks, and hard links cannot make a draft cite itself.
- Missing course selection refuses sync. Valid empty courses succeed. Malformed TOCs retain their
  cache but cannot report complete discovery.
- Conditional fetch verifies local bytes before using validators and again before accepting 304.
  Encoded HTTP lengths are checked against wire bytes; decoded-byte ceilings remain enforced.
- Download journals recover installed bytes after a failed manifest commit, including initial
  installs. Generated prompts and outlines use `transactions.py` to recover source/twin pairs,
  retain prior revisions, and refuse post-interruption edits instead of overwriting them.
- Fetch converts only its requested source using the configured OCR threshold; a raw file is not
  reported as a verified Markdown citation.
- `locations.py` records stable course ownership in `_meta/course.json` and assignment directory
  bindings in assignment metadata. Renames retain paths; ambiguous ownership fails closed.
- `tzdata` is a core dependency using the previously locked 2026.3 release. POSIX bootstrap locates
  the installed uv binary before using it; both installers request Python 3.11–3.14 explicitly.
  A real clean-home macOS bootstrap installed the candidate and obtained Python 3.14 successfully.
- Privacy purge inventories backups inside the selected vault, not unassociated sibling backups.
- The explained golden change is exactly two added course ownership records and directory fields
  in the first course's assignment metadata: 55 files, with every source/twin byte hash unchanged.
- Local full verification: **1031 passed, 4 skipped**, warnings treated as errors, **79.84%**
  branch-aware coverage; the 77.5% floor is unchanged. The strict retrieval benchmark measured
  1.70 seconds after exact-scoring optimizations, with independent rational-reference checks.
- `tools/smoke_installed_core.py` must run from a clean, base-only installed wheel environment,
  not an editable checkout. It verifies timezone data without the system database, production
  sync, source preservation, grounding, and checking, with unexpected network requests blocked.
  CI runs it across the existing OS/Python matrix alongside the skill-source smoke.

Local verification does not replace exact-commit three-OS CI or live same-device authentication.
Submission remains disabled, and publication still requires the existing human release gates.

## Release preparation — 0.1.1

- The remediation PR #17 is merged. Release preparation uses `release/v0.1.1` from current `main`,
  not the shared frontend branch. A divergent `git pull origin main` on that frontend branch is
  not a package-release failure; do not reset, rebase, or overwrite another agent's work.
- Package metadata, runtime `__version__`, both installer pins, and all four skill metadata versions
  must agree on 0.1.1. The CLI-version smoke compares reported output with installed distribution
  metadata, so run `uv sync --frozen --all-extras --dev` after changing a version.
- The direct manual command is `uv tool install agent2learn`, followed by `a2l init`. A real
  isolated candidate-index probe passed with supported system Python and with no Python installed.
  An older system-only interpreter failed; one-time `uv python install 3.12` made the same bare
  command succeed. Keep that workaround in troubleshooting; do not claim the package can control
  uv's interpreter selection before installation. Platform installers still select supported Python.
- The historical `v0.1.0` tag points at 67b12bd and must not be silently moved. Prepare a fresh
  matching `v0.1.1` tag only after the existing release approvals and publisher setup are complete.
- A release-preparation commit or PR is not publication. PyPI/TestPyPI account bindings, actual
  registry uploads, and live same-device validation must be verified separately. Upload capability
  remains disabled; no safety gate is relaxed for this version bump.
- Owner-approved pending publishers are configured on PyPI and TestPyPI for `agent2learn`, GitHub
  `ManagementMO/agent2learn`, workflow `release.yml`, and environments `pypi` / `testpypi`. Both
  management pages confirmed the records after submission. These bindings are not registry uploads
  or evidence that the package is publicly installable.
- CI and tagged-release installer jobs also exercise the bare uv command outside the checkout,
  without `UV_PYTHON`, using fresh tool directories and the exact staged candidate index.
- During 0.1.1 preparation, the owner confirmed that the required Windows/Linux same-device LEARN
  checks were completed and recorded. This is owner attestation; the assistant did not repeat the
  live checks or inspect private records. The owner explicitly authorized merging PR #20 after CI,
  tagging v0.1.1, and promoting verified artifacts through TestPyPI and PyPI, including deployment
  approvals. That authorization does not enable LEARN submissions or apply to a later version.

## Release recovery — 0.1.2

- The v0.1.1 run 34712712368 built, attested, and uploaded valid distributions to TestPyPI, but
  all three staging checks failed because `SHA256SUMS.txt` also named uv's generated `.gitignore`.
  GitHub's artifact transfer did not include that hidden bookkeeping file. Production PyPI and
  GitHub Release creation correctly remained blocked; do not bypass their hash gates.
- The checksum producer now emits only regular `.whl` and `.tar.gz` files and rejects an empty
  distribution set. Regression tests execute the real workflow Python payload with bookkeeping
  files present. Strict downstream filename-set and digest equality remain unchanged.
- Release builds pin uv 0.12.13, the builder used for the attested v0.1.1 artifacts. A local older
  uv changed only WHEEL/RECORD metadata; matching the recorded builder reproduced both originals.
  Dependency bounds and the runtime lock are not changed to suppress that difference.
- The owner explicitly chose a fresh 0.1.2 release instead of moving v0.1.1. Keep both historical
  tags and the TestPyPI 0.1.1 files intact. Package/runtime/installer/skill versions target 0.1.2;
  after its checks pass, merge the fix, create v0.1.2, and promote through TestPyPI then PyPI using
  the existing protected workflow. The owner authorized that version's publication. LEARN uploads
  remain disabled, and the normal user command remains `uv tool install agent2learn`.

## Published release — 0.1.2

- PR #21 merged as 05b99f4 after all 17 CI jobs passed. Tag v0.1.2 remains on that merge commit;
  v0.1.0/v0.1.1 and the TestPyPI 0.1.1 files were not moved or replaced.
- Run 34715405821 successfully built and attested 0.1.2, passed all three installer jobs, published
  to TestPyPI, passed all three exact-hash staging/install checks, and published to production PyPI.
- The final GitHub attachment job failed because it had no checkout and `gh release create` lacked
  an explicit repository. The already-authorized GitHub Release was then created with `--repo`
  using those same downloaded, attested artifacts; its asset digests match PyPI and the manifest.
  The historical workflow run still records the failed attachment step; it was not rewritten.
- A fresh isolated public-index `uv tool install agent2learn` installed 0.1.2 with no Python flag,
  custom index, local-wheel override, or dependency constraints. CLI version, four bundled skills,
  and the installed core workflow smoke passed. Older-system-Python and shell-PATH fallbacks remain
  documented rather than hidden.
- The workflow follow-up passes `GITHUB_REPOSITORY` explicitly to the release CLI and tests the
  command from a directory without a checkout. It does not rebuild or republish version 0.1.2.

## Public presentation preference

- The owner wants a text-first release. Do not add promotional-media placeholders or make media
  production a publication prerequisite in the README, package description, or launch plan.
- Public examples still use synthetic data, and all privacy, authentication, and submission
  safeguards remain unchanged.

## Release candidate — 0.1.3

- The owner initially authorized a documentation-only 0.1.3: align all version references, remove
  the unwanted promotional-media requirements, and use absolute README documentation URLs so the
  links work on both package indexes and GitHub.
- Commit and push the change, merge only after exact-head CI passes, create a fresh v0.1.3 tag,
  and promote the same verified artifacts through TestPyPI and PyPI using the existing approvals.
  Do not move older tags or replace older registry files. Past versions retain their historical
  metadata; the new release updates the current package page.
- The initial candidate kept runtime behavior unchanged. The owner later approved the quiz-coverage
  runtime fix described below. Dependency bounds and submission capability remain unchanged. Do not
  describe the candidate as published until registry uploads and public installation are verified.
- The owner also requested one-paste install-to-setup entry points. Preserve the existing terminal
  gate by keeping stdin attached when launching the macOS/Linux script, and use uv to run the
  freshly installed command without relying on the parent shell's PATH. Headless use must remain
  install-only; login, Duo, and local-write consent remain human steps.
- Finish the local implementation and self-verification before waiting for one final PR CI/CD
  pass. Do not stall each incremental change on GitHub checks. The owner requested a real cloud
  Devin VM/Desktop test and will complete login there when needed; do not substitute local tests
  or move browser sessions between devices.
- A real-account 0.1.2 report now blocks the documentation-only candidate: quiz enumeration returned
  JSON HTTP 403 for `Quizzing.SeeQuizzing` while topic fetching worked. A synthetic real-HTTP
  regression reproduces the global bulk-sync stop. The spec and plan now distinguish that known
  quiz permission gap from fatal discovery/auth failures and require persisted, truthful coverage.
  The runtime fix has passed 1063 local tests (six platform/optional skips), the coverage gate,
  and a fresh base-wheel smoke that fails against the previous candidate. The golden change adds
  only two reviewed collection-coverage records; all 55 previous artifact hashes are unchanged.
  The cloud Linux VM passed 1064 tests (five platform/optional skips), source checks, and installed
  base-wheel checks; its independently built wheel matched the local wheel SHA-256 exactly.
  Final CI/CD and real-account full-sync acceptance remain distinct: do not describe the fix as
  published or the full live sync as complete until the corresponding evidence exists.
- After these results, the owner explicitly approved including the runtime fix in 0.1.3 and
  proceeding through final PR CI, merge, tagging, TestPyPI, and PyPI gates. PR #23 had already
  merged the documentation-only commit; use a follow-up PR and retain the subsequent frontend
  deployment and video-removal changes on main. No v0.1.3 tag or registry upload existed at this
  scope approval. Do not fabricate a new real-account full-sync PASS from synthetic tests.
- The owner approved only the new, verified coverage-fixture checksum as a secret-scan false
  positive. The baseline change records that one digest and line-number bookkeeping; detector
  settings, thresholds, and exclusions are unchanged.
- Cloud verification must keep its tools, test home, and candidate artifacts under a persistent
  home directory, not `/tmp`: a VM restart discarded the latter and its terminal process. With
  an isolated HOME, preserve the VM's configured XAUTHORITY path for GUI access; do not copy its
  contents or weaken X-server/browser security. Source checks must retain the selected Python,
  all test extras, and uv on their subprocess PATH. These are test-environment requirements.

## Release recovery — 0.1.4

- PR #26 merged as d2acb4d after all 17 required CI jobs passed in run 34734171068. The immutable
  v0.1.3 tag points at that merge. Release run 34735270744 built and attested both distributions,
  passed all three installer jobs, and published the exact files to TestPyPI. All three staging
  hash checks passed, but all three staging installs failed; production PyPI and GitHub release
  publication were correctly skipped. Production still serves 0.1.2 at this checkpoint.
- The failure was index precedence: uv prioritizes `--extra-index-url` over `--index-url` under
  `first-index`. Since production now contains Agent2Learn, the old recipe found only production's
  older version and never considered TestPyPI's candidate. Do not use unsafe index matching.
- The owner explicitly approved a fresh 0.1.4 instead of moving v0.1.3 or replacing its TestPyPI
  files. The correction installs the wheel downloaded from TestPyPI only after host, size, and
  SHA-256 verification, while dependencies resolve only from PyPI with `first-index` unchanged.
  Existing protected environments, Trusted Publishing, tag checks, and submission-disable gates
  remain intact. No dependency bound or third-party lock entry changes for this recovery.
- A real-uv two-index regression reproduced the old failure and passes with the correction; it
  also proves that a conflicting staging dependency is not selected. Download tests reject corrupt
  or oversized bytes, foreign hosts, cleartext URLs, embedded credentials, and redirects before
  exposing an installable artifact path.
- The corrected workflow steps were also executed against the actual, already-published TestPyPI
  0.1.3 artifacts: exact hashes, installation, CLI version, installed core workflow, and skills all
  passed without any new upload. The new 0.1.4 still needs its own final CI and publication gates.
- The owner requested an independent end-to-end QA prompt, including a real same-device login they
  will complete. Its target is the eventual published 0.1.4, not the staging-only 0.1.3. Preserve
  existing user data, keep uploads disabled, and report real-account versus synthetic evidence
  separately rather than claiming universal success.

## Final documentation correction — 0.1.5

- PR #27 merged as 4b98c64 after all 17 required checks passed in run 34736768908. A fresh clean
  checkout also passed 1071 tests with six skips. The old temporary worktree was found incomplete
  and was preserved rather than used for release operations.
- The v0.1.4 tag remains on 4b98c64. Its release run 34738091012 passed build, attestation, and all
  installer jobs, then was stopped at the unapproved TestPyPI gate after a final README review
  found a stale `currently 0.1.3` parenthetical. Neither registry received 0.1.4.
- The owner explicitly chose a fresh 0.1.5 rather than ship the stale package description or move
  v0.1.4. Remove the hardcoded README version note, align package/runtime/installer/skill versions,
  and retain a regression against stale current-version claims. Runtime behavior, dependency
  versions, artifact-source protections, and submission capability remain unchanged.
- Finalize through a normal PR and all required checks, then a fresh v0.1.5 tag and the existing
  protected TestPyPI/PyPI workflow. Preserve every earlier tag/artifact. The independent QA prompt
  must target the final published 0.1.5 and continue to distinguish live-account evidence from
  synthetic verification.

## Validation hardening and release preparation — 0.1.6

- Production 0.1.5 was published from `dc2e55d`. Its wheel SHA-256 remains
  `aec6f8d1642acf1c1d1101a5393e724210ddc13e800de2f1d702f81904748594`; preserve that release and
  every older tag/artifact. Do not label a locally rebuilt 0.1.5 wheel as the published artifact.
- PR #29 merged the validation fixes as `25d6b3f`; its exact main CI run `34784211929` passed
  all 17 jobs. The fixes cover explicit missing-browser diagnostics, interrupted consent exit
  codes, OCR error/path handling, unchanged-twin preservation, truthful conversion/download gaps,
  and custom uv-tool installation detection. These are source fixes, not proof of a completed
  real-student sync or of package publication.
- The owner now explicitly authorizes finishing remaining validation and publishing the next
  patch, including normal PR/merge and protected TestPyPI/PyPI approvals. Prepare fresh 0.1.6;
  do not move old tags, enable submissions, bypass protections, or copy browser/session state.
- The five outstanding dependency proposals are integrated on the current release candidate with
  targeted lock updates, not by blindly merging stale branches. See `docs/DEPENDABOT_REVIEW.md`.
  Release review also fixed a falsely green notices check that omitted direct Click/tzdata rows;
  its completeness and missing-row regressions were observed failing before the repair.
- An allowed older-dependency resolution exposed another defect: Typer 0.15.0 with current Click
  installed but crashed on help. The candidate raises the Typer floor to 0.16, retains the locked
  0.27.1, and tests installed CLI behavior with both default and floor resolutions. Do not replace
  this with a version-only smoke: `--version` passed even when help and argument rendering failed.
- Live same-machine authentication with the original installed 0.1.5 wheel passed on this Mac,
  and `auth --check`, resumed setup, and subsequent diagnostics reused the saved session. The
  owner delegated approval of a new private non-Git vault and exactly one current-term course.
  Grades, discussions, and submissions stayed off. The first metadata attempt failed with an
  unreproduced cause; resuming the saved setup completed without broadening selection.
- The real quiz denial was observed: HTTP 403 / `not_authorized` / `Quizzing.SeeQuizzing`.
  Accessible content still downloaded, so that original blocker was resolved in its narrow live
  sense. Full archive acceptance nevertheless failed at a separate HTML route boundary: all 50
  HTML File topics downloaded as asset ZIPs; ten containers included about 1.54 GB of media,
  and 15 hit existing archive safeguards. Do not weaken those safeguards or treat absent PDF
  topics as absent PDF resources. The aligned source-only HTML exception and upgrade-preservation
  contract are in the design spec and algorithm reference section 4.
- Priority selected zero topic files because every document size was unknown. The safety budget
  was correct, but its explanation was missing. The CLI now explains empty priority plans,
  qualifies partially known deadlines, and retains quiz-gap disclosure alongside conversion
  errors. Live grounding by one assignment's exact title and ID worked; a private lexical scan's
  five cited excerpts matched their local lines and excluded draft/report/answer canaries.
- Current-corpus QA located 262 primary PDFs and two differing alternate copies. Its first run
  converted every input with eight explicitly unresolved pages, but the original historical
  denominator/harness was not recovered. A bounded follow-up found empty Tesseract output on all
  eight pages; the candidate distinguishes that from missing OCR and recommends original-page
  inspection. Do not infer blankness, completeness, or semantic correctness from output counts.
  Native/OCR union and partial-citable twins are not part of this repair. Keep all source files,
  fingerprints, corpus results, and detailed validation reports private and outside Git.
- The test suite now defaults to per-test machine paths, an in-memory keyring, and loopback-only
  Python networking. Its isolation regression runs behind synthetic host-state sentinels, so
  removing a test guard cannot touch real credentials/configuration. Installed-wheel smoke
  scripts remain a separate gate and do not substitute for the real student workflow.
- Do not merge a new installer pin into main and leave it pointing at an unavailable release.
  Land reviewed source/dependency/test fixes separately while retaining the published installer
  pin; keep the fresh version bump separate until publication can proceed through the existing
  protected workflow. A green automated run does not waive the design specification's manual
  evidence, the unreproduced historical corpus baseline, or untested graphical OS workflows.
- The final source-fix local gate on 2026-09-14 passed 1,262 tests with six explicit skips and
  80.86% branch-aware coverage. Ruff, formatting, strict mypy, fixtures, and notices passed.
  Independent review additionally found a recorded-size mismatch could re-admit a hash-matching
  HTML ZIP; three consumer regressions failed before removing that erroneous prerequisite.
- An isolated base-wheel candidate repaired the same live vault in 65 seconds: all 50 HTML
  topics became citable, 12 external links remained excluded, and quiz coverage stayed unavailable
  and disclosed. All 50 old source containers were preserved in history; IDs and paths stayed
  stable, and all twins were hash-linked. Direct-source HTML differs from the bundle's rewritten
  HTML, so identical raw bytes are not a valid quality claim. The bounded paragraph comparison
  and the historical PDF baseline still require their separately recorded interpretation.

## Owner-approved limited release scope — 2026-09-14

- The owner approved the current frozen PDF baseline and an explicitly limited macOS-validated
  0.1.6 release, with remaining human/platform checks reported as unverified. This is a replacement
  baseline decision, not reproduction of the historical harness. See `docs/RELEASE_VALIDATION.md`
  and the aligned design/plan addenda; keep detailed private corpus evidence outside Git.
- Complete all executable checks, investigate actual failures, and proceed through normal PR,
  merge, fresh tag, protected TestPyPI/PyPI approvals, and exact-artifact verification. Keep the
  historical timeout failures visible even if unchanged retries pass. No skipped tests, security
  weakening, moved tags, session transfers, or live submission enablement are authorized.
- Do not call unavailable Windows/Linux graphical login or human visual/semantic comparison
  complete. The eight unresolved corpus pages are explicit limitations, not successful text
  recovery. Final published-release claims require current registry and provenance evidence.