diff --git a/.claude/skills/glossary-review/SKILL.md b/.claude/skills/glossary-review/SKILL.md index dd5f4ab7..6d961233 100644 --- a/.claude/skills/glossary-review/SKILL.md +++ b/.claude/skills/glossary-review/SKILL.md @@ -32,7 +32,7 @@ proposes dropping the probe model to halve the cost, the method stops working. economics terms and had **1 of 24** programming terms — a large gap means this exercise is worth running; a small one means it probably isn't. 3. **Read the language's house style** before assessing anything: the existing glossary's - conventions, `src/language-config.ts`, and any `.dev/decisions/**`. This changes + conventions, `src/language-config.ts`, and any `.qe/dev/decisions/**`. This changes the answers, it doesn't just flavour them — Malayalam deliberately **keeps technical terms in English** (`D-2026-06-01-malayalam-keep-english-policy.md`) while French translates them. Proposing `f-string → chaînes f` is a reasonable question for `fr` and @@ -145,7 +145,7 @@ which mechanism you recommend and why, and what it will cost the reviewer. ### 7. After review Apply the answers, merge, then write the run's REPORT.md embedding the final candidate -table and counts. Record any policy-level outcome in `.dev/decisions/`. +table and counts. Record any policy-level outcome in `.qe/dev/decisions/`. ## Scripts diff --git a/.dev/README.md b/.dev/README.md deleted file mode 100644 index 5c16bf1d..00000000 --- a/.dev/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# `.dev/` — project notes - -Working notes for this repository — **state, decisions, and design ideas** — maintained -jointly by humans and coding agents. Nothing here is published (not in the docs site, npm -package, or action bundle). Git holds the project's history; `.dev/` holds the curated, -current picture: distill, supersede, or delete. - -`action-translation` is the **pilot repo** for the QuantEcon `.dev/` convention — -spec and rationale: QuantEcon/QuantEcon.manual#103; pilot: QuantEcon/action-translation#73. - -## Layout - -``` -.dev/ -├── STATE.md # where things stand: in flight / blocked / next (~1 page); -│ # first line "verified: YYYY-MM-DD" -├── PLAN.md # current roadmap (not its history) -├── ARCHITECTURE.md # optional living doc: design deliberation, open questions -├── FUTURE.md # optional living doc: uncommitted feature ideas -├── decisions/ # D-YYYY-MM-DD-.md — one settled decision per file -├── log/ # YYYY-MM-DD-.md — short dated session notes -└── scratch/ # gitignored working files (the repo's scratch location) -``` - -**Lifecycle by location**: anything at the `.dev/` root is *living* (edited in place, always -current); anything under `decisions/` or `log/` is *append-only* (entries never edited; stale -log files may be deleted once distilled — deletion ≠ editing). Settled architecture graduates -from `ARCHITECTURE.md` to contributor docs; committed ideas graduate from `FUTURE.md` to -`PLAN.md`. - -**No YAML schema, no CI gates.** Structure lives in filenames, git, and three plain-text -conventions: - -1. `verified: YYYY-MM-DD` as STATE.md's first line — trust the file less as that date ages. -2. A supersession note at the top of an old decision file, pointing to its replacement - (decision files are otherwise never edited; date+slug filenames avoid id races between - parallel agents). -3. Inline `#promote` tags marking cross-repo findings for the future org knowledge vault — - everything stays one `grep -rn "#promote" .dev/` away. - -Decision files are a few lines each: **context / decision / consequences** (+ refs). - -## Maintenance - -An occasional **"tidy `.dev/`" session** — an agent reads the folder, flags contradictions and -staleness, proposes pruning; a human approves the PR. Run when returning after a gap, or -roughly monthly. Humans curate STATE.md/PLAN.md and approve decisions and pruning; agents -write logs, file decisions, and run tidy passes. If tidy sessions repeatedly surface the same -mechanical problems, that's the evidence to script a check — not before. - -## Content rules - -- `.dev/` is **public**: no credentials, no unpatched-vulnerability specifics (track those in - security advisories until fixed). -- Absolute dates only ("2026-07-05", never "last week") — these files outlive sessions. -- The agent contract lives in [`AGENTS.md`](../AGENTS.md). - -For user-facing and contributor documentation, see [`docs/`](../docs/) and -[`CONTRIBUTING.md`](../CONTRIBUTING.md). diff --git a/.dev/scratch/.gitkeep b/.dev/scratch/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3d6e1435..62a61973 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,12 +3,12 @@ name: CI on: push: branches: [main] - paths-ignore: ['.dev/**'] + paths-ignore: ['.qe/**'] pull_request: branches: [main] # Note: if `test` ever becomes a *required* status check, drop this ignore — - # a skipped required check never reports and would deadlock .dev-only PRs. - paths-ignore: ['.dev/**'] + # a skipped required check never reports and would deadlock .qe-only PRs. + paths-ignore: ['.qe/**'] workflow_dispatch: permissions: @@ -34,9 +34,10 @@ jobs: - name: Format check run: npm run format:check - # Source changes are what invalidate .dev/ path:line references, so this - # runs on the normal CI trigger; .dev-only PRs still skip CI entirely. - - name: Check .dev references + # Source changes are what usually invalidate .qe/ path:line references, so + # this runs on the normal CI trigger. .qe-only PRs skip CI but can still add + # a broken reference: run `npm run check-dev-refs` before merging one. + - name: Check .qe references run: npm run check-dev-refs - name: Build diff --git a/.gitignore b/.gitignore index f9d330db..2885beef 100644 --- a/.gitignore +++ b/.gitignore @@ -21,10 +21,8 @@ docs/_build/ # TypeScript build info *.tsbuildinfo -# Scratch — .dev/scratch/ dir is committed (via .gitkeep) but contents are ignored -.dev/scratch/* -!.dev/scratch/.gitkeep -# Legacy scratch location (retired 2026-07-05; see .dev/decisions/) — keep ignoring stale local copies +# No scratch location in the tree (D-2026-09-21-no-scratch-in-tree in .qe/dev/decisions/); +# legacy locations stay ignored so stale local copies remain invisible .tmp/ **/*.tmp .cache/ diff --git a/.qe/README.md b/.qe/README.md new file mode 100644 index 00000000..baac549e --- /dev/null +++ b/.qe/README.md @@ -0,0 +1,24 @@ +# `.qe/` — the repository's QuantEcon folder + +Everything QuantEcon-specific about *how this repository is worked* lives here, so that +retiring the overlay, archiving the repository or open-sourcing it is one decision about one +directory. Nothing in it is published or built. Its home is the Project Management Protocols +QEP (QuantEcon/qeps, QEP-7 — in draft); this repository is the pilot. + +| Path | What | Written by | Lifecycle | +|---|---|---|---| +| `README.md` | this contract | people | living | +| `project.yml` | declared facts the `qe` skills read: the tracker, the registry slug, the programme | people, once | living | +| `dev/` | the notes record — see [`dev/README.md`](dev/README.md) | people and agents | raw entries append-only; distilled pages rewritten in place | +| `NEXT-STEPS.md` | the reading order across trackers and the gates between them — only in a repository with more than one tracker | people | living | +| `ROADMAP.md`, `DIGEST.md`, `snapshot.json` | views of the tracker drawn by the `qe` workplan skills | the skills | generated — marked as such in their first line; regenerated, never edited | + +Not every file is present in every repository; the table is the convention's full set. + +**The boundary test:** a file belongs here if it would leave with QuantEcon's way of managing +the project; a file that describes the product stays in `docs/`. `AGENTS.md`, `CLAUDE.md` and +`.claude/` stay at the repository root, where tools find them. + +**Rules:** public content only (no credentials, no unpatched-vulnerability specifics); +absolute dates (`YYYY-MM-DD`); nothing under `.qe/` is git-ignored — scratch and working files +live outside the tree, in the agent's own scratchpad or a temporary directory. diff --git a/.dev/ARCHITECTURE.md b/.qe/dev/ARCHITECTURE.md similarity index 100% rename from .dev/ARCHITECTURE.md rename to .qe/dev/ARCHITECTURE.md diff --git a/.dev/FUTURE.md b/.qe/dev/FUTURE.md similarity index 100% rename from .dev/FUTURE.md rename to .qe/dev/FUTURE.md diff --git a/.dev/PLAN.md b/.qe/dev/PLAN.md similarity index 98% rename from .dev/PLAN.md rename to .qe/dev/PLAN.md index 686e5977..fc56f57d 100644 --- a/.dev/PLAN.md +++ b/.qe/dev/PLAN.md @@ -73,7 +73,7 @@ Everything here is a contained fix with an obvious correct behaviour. Ship as on ### 1.5 Rebase-mode input validation (security — pulled forward from Phase 4) - [ ] **[H]** Harden rebase mode's handling of PR-embedded metadata: cross-check it against the workflow's own configuration and require the expected automation identity before acting. - Specifics deliberately omitted here per the `.dev/` public-content rule. Land this before + Specifics deliberately omitted here per the `.qe/dev/` public-content rule. Land this before issue #66 documents the metadata as a public contract. ### 1.6 Release chores @@ -358,8 +358,8 @@ but not sync; `overloaded` retry in the translator but not the reviewer or any C - [ ] Document `.translate/` state files appearing in translation PRs (action side) in `docs/user/action-reference.md` - [ ] Organization decisions (each small, do deliberately): - - [ ] `experiments/` → `.dev/experiments/` (single historical experiment write-up) - - [ ] `docs/projects/` (internal RA planning, excluded from the site toc) → `.dev/projects/` + - [ ] `experiments/` → `.qe/dev/experiments/` (single historical experiment write-up) + - [ ] `docs/projects/` (internal RA planning, excluded from the site toc) → `.qe/dev/projects/` or add to the toc deliberately - [ ] `presentations/`: stop committing generated artifacts (`.pdf`, built `.html`) or archive the directory; content is stale (issue #7 — old project name) @@ -382,7 +382,7 @@ new-language adopter can go from zero to a working target repo following only pu - [x] Close or retitle **#2** to the narrow "cross-model (GPT) reviewer" remainder (FUTURE.md idea 9) — closed; FUTURE.md idea 9 holds the remainder - [x] Gardening pass 2026-07-26 also closed **#70** (ml shipped v0.24.0; `help wanted` moved to - #207), **#73** (`.dev/` pilot complete), **#95** (fixed by #197), **#147** (verdict v2 + #207), **#73** (`.qe/dev/` pilot complete), **#95** (fixed by #197), **#147** (verdict v2 validated; calibration → #103/#154), **#138** (duplicate → #192, items copied across). **#66** closes on #176's completion — recorded as a checklist item there - [ ] Finish **#53** — legacy `heading-map:` fallback removal (`src/heading-map.ts:41`); the diff --git a/.qe/dev/README.md b/.qe/dev/README.md new file mode 100644 index 00000000..3e62db65 --- /dev/null +++ b/.qe/dev/README.md @@ -0,0 +1,68 @@ +# `dev/` — project notes + +Working notes for this repository — **state, decisions, and design ideas** — maintained +jointly by humans and coding agents, inside [`.qe/`](../README.md), the repository's QuantEcon +folder. Nothing here is published (not in the docs site, npm package, or action bundle). Git +holds the project's history; `dev/` holds the curated, current picture: distill, supersede, +or delete. It is about **this repository only** — a finding about another repository, a +project that spans repositories, or the org is tagged `#promote` and promoted out. + +`action-translation` is the **pilot repo** for the QuantEcon notes convention. Its home is the +Project Management Protocols QEP (QuantEcon/qeps, QEP-7 — in draft), which supersedes the +earlier spec in QuantEcon/QuantEcon.manual#103; the pilot's adoption is +QuantEcon/action-translation#73. + +## Layout + +``` +.qe/dev/ +├── STATE.md # orientation and the resume checklist (~1 page); +│ # first line "verified: YYYY-MM-DD"; the tracker (#257) holds the state +├── PLAN.md # current roadmap (not its history) +├── ARCHITECTURE.md # optional living doc: design deliberation, open questions +├── FUTURE.md # optional living doc: uncommitted feature ideas +├── decisions/ # D-YYYY-MM-DD-.md — one settled decision per file +└── log/ # YYYY-MM-DD-.md — short dated session notes +``` + +**A distillation record.** `log/` and `decisions/` are the *raw* layer: append-only, entries +never edited (stale log files may be deleted once distilled — deletion ≠ editing; a decision +is superseded by a new file with a note at the top of the old one). The pages at the `dev/` +root are the *distilled* layer: rewritten in place, always current, citing the entries they +came from. Knowledge moves one way — raw → distilled → promoted: settled architecture +graduates from `ARCHITECTURE.md` to contributor docs, committed ideas from `FUTURE.md` to +`PLAN.md`, cross-repo findings to a QEP or the org vault via `#promote`. + +**No YAML schema, no CI gates.** Structure lives in filenames, git, and three plain-text +conventions: + +1. `verified: YYYY-MM-DD` as STATE.md's first line — trust the file less as that date ages. +2. A supersession note at the top of an old decision file, pointing to its replacement + (decision files are otherwise never edited; date+slug filenames avoid id races between + parallel agents). +3. Inline `#promote` tags marking cross-repo findings for the org knowledge vault — + everything stays one `grep -rn "#promote" .qe/dev/` away. + +Decision files are a few lines each: **context / decision / consequences** (+ refs). A record +explains the choice as of its date and guides the next one; it binds nothing beyond "read it +before re-litigating" — to change a decision, write the superseding record. + +## Maintenance + +An occasional **tidy session** is the distillation pass — an agent reads the folder, updates +the distilled pages from the raw entries, flags contradictions and staleness, records what it +distilled, and proposes pruning; a human approves the PR. Run when returning after a gap, or +roughly monthly. Humans curate STATE.md/PLAN.md and approve decisions and pruning; agents +write logs, file decisions, and run tidy passes. If tidy sessions repeatedly surface the same +mechanical problems, that's the evidence to script a check — not before. + +## Content rules + +- `.qe/` is **public**: no credentials, no unpatched-vulnerability specifics (track those in + security advisories until fixed). +- Absolute dates only ("2026-07-05", never "last week") — these files outlive sessions. +- Nothing under `.qe/` is git-ignored; scratch and working files live outside the tree. +- The agent contract lives in [`AGENTS.md`](../../AGENTS.md). + +For user-facing and contributor documentation, see [`docs/`](../../docs/) and +[`CONTRIBUTING.md`](../../CONTRIBUTING.md). diff --git a/.dev/STATE.md b/.qe/dev/STATE.md similarity index 96% rename from .dev/STATE.md rename to .qe/dev/STATE.md index fa53be48..b94cc462 100644 --- a/.dev/STATE.md +++ b/.qe/dev/STATE.md @@ -90,15 +90,15 @@ Roadmap detail lives in the work-plan tracker **#257**, not here (PLAN.md predat Two reviewers have since agreed three more edits (オーソリティ中心性, 資本の限界生産力, 連邦準備制度経済データ) and asked why `SCF` was left out (last reply 2026-09-21) — awaiting the maintainer's reply; the branch is 21 behind `main` and conflicting. -- **#314** (opened 2026-09-21 as a draft; marked ready for review 2026-09-23 — Copilot's - overview recommends approval, two wording nits) — `.dev/` → `.qe/dev/` per the QEP-7 draft - (QuantEcon/qeps#40, still open). It renames every file under `.dev/` and already conflicts - with `main` (9 behind), so whichever of it and an in-flight PR that touches `.dev/` merges - second needs a rebase — this STATE refresh included; raw `log/` and `decisions/` entries keep - their historical `.dev/` mentions. ## Recently landed +- **`.dev/` → `.qe/dev/` (#314)** — the notes convention moves inside `.qe/`, the repository's + QuantEcon folder, per the QEP-7 draft (QuantEcon/qeps#40): `.qe/README.md` states the folder's + contract, `.qe/project.yml` points the `qe` workplan skills at tracker #257, and nothing under + `.qe/` is git-ignored — working files live outside the tree (decision records + `D-2026-09-21-notes-move-to-qe-dev`, `D-2026-09-21-no-scratch-in-tree`). Raw `log/` and + `decisions/` entries keep their historical `.dev/` mentions. - **2026-09-23 — v0.29.3 released** (release PR #329 `16e50f6`; payload #328 `a4fe00a`, on top of #322 `079b3c7` and #323 `ede10e6`): `fr` glossary v1.2 from the French editor's second round (Namespace → Espace de nommage, Heads → Face, the standard-normal context; the edition @@ -193,7 +193,7 @@ Roadmap detail lives in the work-plan tracker **#257**, not here (PLAN.md predat - `main` green; **1,590 tests across 67 suites** (zero skips, type-checked) as of `16e50f6`; lint at `--max-warnings 0` including root `*.mjs`, CI checks formatting and - `.dev/` path:line references. Note `npm test` fails 11 cli-smoke tests on a stale `dist/` + `.qe/dev/` path:line references. Note `npm test` fails 11 cli-smoke tests on a stale `dist/` — run `npm run build` first; that guard is deliberate, not a break. - Highest-priority known bug class: the success-shaped failure (#90 defects 3–5, #276's two resync mechanisms, and the arrivals #280, #282, #287; freshest field instance 2026-08-19 — diff --git a/.dev/decisions/D-2025-10-01-accept-llm-translation-improvements.md b/.qe/dev/decisions/D-2025-10-01-accept-llm-translation-improvements.md similarity index 100% rename from .dev/decisions/D-2025-10-01-accept-llm-translation-improvements.md rename to .qe/dev/decisions/D-2025-10-01-accept-llm-translation-improvements.md diff --git a/.dev/decisions/D-2026-03-01-heading-maps-in-frontmatter.md b/.qe/dev/decisions/D-2026-03-01-heading-maps-in-frontmatter.md similarity index 100% rename from .dev/decisions/D-2026-03-01-heading-maps-in-frontmatter.md rename to .qe/dev/decisions/D-2026-03-01-heading-maps-in-frontmatter.md diff --git a/.dev/decisions/D-2026-03-04-ink-over-rich-cli.md b/.qe/dev/decisions/D-2026-03-04-ink-over-rich-cli.md similarity index 100% rename from .dev/decisions/D-2026-03-04-ink-over-rich-cli.md rename to .qe/dev/decisions/D-2026-03-04-ink-over-rich-cli.md diff --git a/.dev/decisions/D-2026-03-05-whole-file-backward-eval.md b/.qe/dev/decisions/D-2026-03-05-whole-file-backward-eval.md similarity index 100% rename from .dev/decisions/D-2026-03-05-whole-file-backward-eval.md rename to .qe/dev/decisions/D-2026-03-05-whole-file-backward-eval.md diff --git a/.dev/decisions/D-2026-03-06-cli-rename-translate.md b/.qe/dev/decisions/D-2026-03-06-cli-rename-translate.md similarity index 100% rename from .dev/decisions/D-2026-03-06-cli-rename-translate.md rename to .qe/dev/decisions/D-2026-03-06-cli-rename-translate.md diff --git a/.dev/decisions/D-2026-04-01-rebase-on-merge.md b/.qe/dev/decisions/D-2026-04-01-rebase-on-merge.md similarity index 100% rename from .dev/decisions/D-2026-04-01-rebase-on-merge.md rename to .qe/dev/decisions/D-2026-04-01-rebase-on-merge.md diff --git a/.dev/decisions/D-2026-06-01-malayalam-keep-english-policy.md b/.qe/dev/decisions/D-2026-06-01-malayalam-keep-english-policy.md similarity index 100% rename from .dev/decisions/D-2026-06-01-malayalam-keep-english-policy.md rename to .qe/dev/decisions/D-2026-06-01-malayalam-keep-english-policy.md diff --git a/.dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md b/.qe/dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md similarity index 90% rename from .dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md rename to .qe/dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md index fb04f93c..5caab228 100644 --- a/.dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md +++ b/.qe/dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md @@ -1,3 +1,5 @@ +> **Amended 2026-09-21** by [D-2026-09-21-notes-move-to-qe-dev](D-2026-09-21-notes-move-to-qe-dev.md): the convention stands; its location is `.qe/dev/`. + # Adopt the `.dev/` notes convention (pilot repo) **Context**: Working notes lived in `dev-notes/` (a 1,850-line completed plan, one design diff --git a/.dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md b/.qe/dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md similarity index 84% rename from .dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md rename to .qe/dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md index 87f6d5cf..6804b5ef 100644 --- a/.dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md +++ b/.qe/dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md @@ -1,3 +1,5 @@ +> **Superseded 2026-09-21** by [D-2026-09-21-no-scratch-in-tree](D-2026-09-21-no-scratch-in-tree.md): the tree has no scratch location. + # Scratch moves from `.tmp/` to `.dev/scratch/` **Context**: The repo's documented scratch location was a gitignored `.tmp/` folder (anchored diff --git a/.dev/decisions/D-2026-07-14-opus-for-bulk-seed.md b/.qe/dev/decisions/D-2026-07-14-opus-for-bulk-seed.md similarity index 100% rename from .dev/decisions/D-2026-07-14-opus-for-bulk-seed.md rename to .qe/dev/decisions/D-2026-07-14-opus-for-bulk-seed.md diff --git a/.dev/decisions/D-2026-07-14-thinking-off-sonnet5.md b/.qe/dev/decisions/D-2026-07-14-thinking-off-sonnet5.md similarity index 100% rename from .dev/decisions/D-2026-07-14-thinking-off-sonnet5.md rename to .qe/dev/decisions/D-2026-07-14-thinking-off-sonnet5.md diff --git a/.dev/decisions/D-2026-07-15-sonnet5-validated.md b/.qe/dev/decisions/D-2026-07-15-sonnet5-validated.md similarity index 100% rename from .dev/decisions/D-2026-07-15-sonnet5-validated.md rename to .qe/dev/decisions/D-2026-07-15-sonnet5-validated.md diff --git a/.dev/decisions/D-2026-07-16-single-review-comment.md b/.qe/dev/decisions/D-2026-07-16-single-review-comment.md similarity index 100% rename from .dev/decisions/D-2026-07-16-single-review-comment.md rename to .qe/dev/decisions/D-2026-07-16-single-review-comment.md diff --git a/.dev/decisions/D-2026-07-24-tech-debt-audit-boundaries.md b/.qe/dev/decisions/D-2026-07-24-tech-debt-audit-boundaries.md similarity index 100% rename from .dev/decisions/D-2026-07-24-tech-debt-audit-boundaries.md rename to .qe/dev/decisions/D-2026-07-24-tech-debt-audit-boundaries.md diff --git a/.dev/decisions/D-2026-07-26-resync-trust-gate-association-set.md b/.qe/dev/decisions/D-2026-07-26-resync-trust-gate-association-set.md similarity index 100% rename from .dev/decisions/D-2026-07-26-resync-trust-gate-association-set.md rename to .qe/dev/decisions/D-2026-07-26-resync-trust-gate-association-set.md diff --git a/.dev/decisions/D-2026-08-10-partial-sync-pr-ships-annotated.md b/.qe/dev/decisions/D-2026-08-10-partial-sync-pr-ships-annotated.md similarity index 100% rename from .dev/decisions/D-2026-08-10-partial-sync-pr-ships-annotated.md rename to .qe/dev/decisions/D-2026-08-10-partial-sync-pr-ships-annotated.md diff --git a/.dev/decisions/D-2026-08-10-sync-does-not-first-translate.md b/.qe/dev/decisions/D-2026-08-10-sync-does-not-first-translate.md similarity index 100% rename from .dev/decisions/D-2026-08-10-sync-does-not-first-translate.md rename to .qe/dev/decisions/D-2026-08-10-sync-does-not-first-translate.md diff --git a/.dev/decisions/D-2026-08-11-bot-identity-machine-user.md b/.qe/dev/decisions/D-2026-08-11-bot-identity-machine-user.md similarity index 100% rename from .dev/decisions/D-2026-08-11-bot-identity-machine-user.md rename to .qe/dev/decisions/D-2026-08-11-bot-identity-machine-user.md diff --git a/.dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md b/.qe/dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md similarity index 100% rename from .dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md rename to .qe/dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md diff --git a/.dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md b/.qe/dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md similarity index 100% rename from .dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md rename to .qe/dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md diff --git a/.dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md b/.qe/dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md similarity index 100% rename from .dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md rename to .qe/dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md diff --git a/.dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md b/.qe/dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md similarity index 100% rename from .dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md rename to .qe/dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md diff --git a/.dev/decisions/D-2026-09-21-ml-further-reading-boundary-is-the-reference-section.md b/.qe/dev/decisions/D-2026-09-21-ml-further-reading-boundary-is-the-reference-section.md similarity index 100% rename from .dev/decisions/D-2026-09-21-ml-further-reading-boundary-is-the-reference-section.md rename to .qe/dev/decisions/D-2026-09-21-ml-further-reading-boundary-is-the-reference-section.md diff --git a/.qe/dev/decisions/D-2026-09-21-no-scratch-in-tree.md b/.qe/dev/decisions/D-2026-09-21-no-scratch-in-tree.md new file mode 100644 index 00000000..b4d3ba73 --- /dev/null +++ b/.qe/dev/decisions/D-2026-09-21-no-scratch-in-tree.md @@ -0,0 +1,17 @@ +# No scratch location in the tree + +**Context**: `.dev/scratch/` was git-ignored, so git versioned nothing in it, while it +still cost a `.gitkeep`, an ignore rule, a carve-out in `check-dev-refs.mjs`, and a place +for working files to accumulate — and it created a third state for a file, in the tree but +uncommittable, which is where the 2026-07-28 audit bundle sat for weeks. Ruled 2026-09-21 +(@mmcky). #promote + +**Decision**: The convention prescribes no scratch location. Working files live in the +agent's own scratchpad or a temporary directory outside the repository; anything worth +keeping is promoted into `.qe/dev/` deliberately. Nothing under `.qe/` is git-ignored. + +**Consequences**: `scratch/` removed with its `.gitkeep` and `.gitignore` lines; the `gh` +and commit-message conventions in `AGENTS.md` write to a temporary directory instead. +Supersedes D-2026-07-05-scratch-moves-to-dev-scratch. + +**Refs**: QuantEcon/action-translation#73 (adoption step 2, now reversed). diff --git a/.qe/dev/decisions/D-2026-09-21-notes-move-to-qe-dev.md b/.qe/dev/decisions/D-2026-09-21-notes-move-to-qe-dev.md new file mode 100644 index 00000000..40e148be --- /dev/null +++ b/.qe/dev/decisions/D-2026-09-21-notes-move-to-qe-dev.md @@ -0,0 +1,27 @@ +# Working notes move from `.dev/` to `.qe/dev/` + +**Context**: The `.dev/` pilot (D-2026-07-05-adopt-dev-notes-convention) proved the notes +convention; what it lacked was a boundary. Everything QuantEcon-specific about how a +repository is worked — notes, decisions, logs, the views the `qe` skills generate, the +declared project facts — was spread over `.dev/`, root files and `.gitignore` lines, so +retiring or open-sourcing the overlay meant a hunt. Ruled 2026-09-21 (@mmcky) for the +Project Management Protocols QEP (QuantEcon/qeps, QEP-7, draft). #promote + +**Decision**: One folder, `.qe/`, flat at the root, holds the repository's QuantEcon +overlay: `README.md` (the contract), `project.yml` (declared facts), the generated tracker +views where present, and `dev/` — this convention, moved in unchanged and scoped to this +repository only. `dev/` runs as a distillation record: `log/` and `decisions/` are raw and +append-only; `STATE.md`, `PLAN.md`, `ARCHITECTURE.md` and `FUTURE.md` are distilled and +rewritten in place; a tidy pass promotes upward (to `docs/`, a QEP, the vault). The tracker +(#257) is the current-state register; STATE.md keeps to orientation and the resume +checklist. A decision record explains a choice as of its date and guides the next one; it +binds nothing beyond "read it before re-litigating", and is changed by a superseding record. + +**Consequences**: `git mv .dev .qe/dev`; pointers in `AGENTS.md`, `check-dev-refs.mjs`, CI +and the living notes updated; the raw entries under `log/` and `decisions/` keep their +historical `.dev/` mentions unedited. Amends the location half of +D-2026-07-05-adopt-dev-notes-convention (the convention itself stands). Trimming STATE.md to +the new rule is the next tidy pass, not this move. + +**Refs**: QuantEcon/qeps#15, QuantEcon/qeps#18 (QEP-6), QuantEcon/qeps#39 (the PMP +discussion), QuantEcon.manual#103 (the spec this supersedes). diff --git a/.dev/log/2026-07-05-65a4.md b/.qe/dev/log/2026-07-05-65a4.md similarity index 100% rename from .dev/log/2026-07-05-65a4.md rename to .qe/dev/log/2026-07-05-65a4.md diff --git a/.dev/log/2026-07-14-state-refresh.md b/.qe/dev/log/2026-07-14-state-refresh.md similarity index 100% rename from .dev/log/2026-07-14-state-refresh.md rename to .qe/dev/log/2026-07-14-state-refresh.md diff --git a/.dev/log/2026-07-15-f5rev.md b/.qe/dev/log/2026-07-15-f5rev.md similarity index 100% rename from .dev/log/2026-07-15-f5rev.md rename to .qe/dev/log/2026-07-15-f5rev.md diff --git a/.dev/log/2026-07-16-dupcomment.md b/.qe/dev/log/2026-07-16-dupcomment.md similarity index 100% rename from .dev/log/2026-07-16-dupcomment.md rename to .qe/dev/log/2026-07-16-dupcomment.md diff --git a/.dev/log/2026-07-24-pr-a-guardrails.md b/.qe/dev/log/2026-07-24-pr-a-guardrails.md similarity index 100% rename from .dev/log/2026-07-24-pr-a-guardrails.md rename to .qe/dev/log/2026-07-24-pr-a-guardrails.md diff --git a/.dev/log/2026-07-24-pr-b-init-parity.md b/.qe/dev/log/2026-07-24-pr-b-init-parity.md similarity index 100% rename from .dev/log/2026-07-24-pr-b-init-parity.md rename to .qe/dev/log/2026-07-24-pr-b-init-parity.md diff --git a/.dev/log/2026-07-24-pr-c-failure-optional.md b/.qe/dev/log/2026-07-24-pr-c-failure-optional.md similarity index 100% rename from .dev/log/2026-07-24-pr-c-failure-optional.md rename to .qe/dev/log/2026-07-24-pr-c-failure-optional.md diff --git a/.dev/log/2026-07-24-pr-d-canonical-workflow.md b/.qe/dev/log/2026-07-24-pr-d-canonical-workflow.md similarity index 100% rename from .dev/log/2026-07-24-pr-d-canonical-workflow.md rename to .qe/dev/log/2026-07-24-pr-d-canonical-workflow.md diff --git a/.dev/log/2026-07-24-pr-e-contracts.md b/.qe/dev/log/2026-07-24-pr-e-contracts.md similarity index 100% rename from .dev/log/2026-07-24-pr-e-contracts.md rename to .qe/dev/log/2026-07-24-pr-e-contracts.md diff --git a/.dev/log/2026-07-24-pr-f-cheap-correctness.md b/.qe/dev/log/2026-07-24-pr-f-cheap-correctness.md similarity index 100% rename from .dev/log/2026-07-24-pr-f-cheap-correctness.md rename to .qe/dev/log/2026-07-24-pr-f-cheap-correctness.md diff --git a/.dev/log/2026-07-24-pr-g-retry-usage.md b/.qe/dev/log/2026-07-24-pr-g-retry-usage.md similarity index 100% rename from .dev/log/2026-07-24-pr-g-retry-usage.md rename to .qe/dev/log/2026-07-24-pr-g-retry-usage.md diff --git a/.dev/log/2026-07-24-pr-h-fail-closed.md b/.qe/dev/log/2026-07-24-pr-h-fail-closed.md similarity index 100% rename from .dev/log/2026-07-24-pr-h-fail-closed.md rename to .qe/dev/log/2026-07-24-pr-h-fail-closed.md diff --git a/.dev/log/2026-07-24-pr-i-dead-code.md b/.qe/dev/log/2026-07-24-pr-i-dead-code.md similarity index 100% rename from .dev/log/2026-07-24-pr-i-dead-code.md rename to .qe/dev/log/2026-07-24-pr-i-dead-code.md diff --git a/.dev/log/2026-07-24-pr-j-dead-input.md b/.qe/dev/log/2026-07-24-pr-j-dead-input.md similarity index 100% rename from .dev/log/2026-07-24-pr-j-dead-input.md rename to .qe/dev/log/2026-07-24-pr-j-dead-input.md diff --git a/.dev/log/2026-07-24-pr-k-docs-truth.md b/.qe/dev/log/2026-07-24-pr-k-docs-truth.md similarity index 100% rename from .dev/log/2026-07-24-pr-k-docs-truth.md rename to .qe/dev/log/2026-07-24-pr-k-docs-truth.md diff --git a/.dev/log/2026-07-24-wave1-complete.md b/.qe/dev/log/2026-07-24-wave1-complete.md similarity index 100% rename from .dev/log/2026-07-24-wave1-complete.md rename to .qe/dev/log/2026-07-24-wave1-complete.md diff --git a/.dev/log/2026-07-26-192-resync-trust-gate.md b/.qe/dev/log/2026-07-26-192-resync-trust-gate.md similarity index 100% rename from .dev/log/2026-07-26-192-resync-trust-gate.md rename to .qe/dev/log/2026-07-26-192-resync-trust-gate.md diff --git a/.dev/log/2026-07-26-210-deletion-review.md b/.qe/dev/log/2026-07-26-210-deletion-review.md similarity index 100% rename from .dev/log/2026-07-26-210-deletion-review.md rename to .qe/dev/log/2026-07-26-210-deletion-review.md diff --git a/.dev/log/2026-08-04-v0250-release.md b/.qe/dev/log/2026-08-04-v0250-release.md similarity index 100% rename from .dev/log/2026-08-04-v0250-release.md rename to .qe/dev/log/2026-08-04-v0250-release.md diff --git a/.dev/log/2026-08-05-engine-ref.md b/.qe/dev/log/2026-08-05-engine-ref.md similarity index 100% rename from .dev/log/2026-08-05-engine-ref.md rename to .qe/dev/log/2026-08-05-engine-ref.md diff --git a/.dev/log/2026-08-05-writeconfig-merge.md b/.qe/dev/log/2026-08-05-writeconfig-merge.md similarity index 100% rename from .dev/log/2026-08-05-writeconfig-merge.md rename to .qe/dev/log/2026-08-05-writeconfig-merge.md diff --git a/.dev/log/2026-08-10-issue-review-workplan.md b/.qe/dev/log/2026-08-10-issue-review-workplan.md similarity index 100% rename from .dev/log/2026-08-10-issue-review-workplan.md rename to .qe/dev/log/2026-08-10-issue-review-workplan.md diff --git a/.dev/log/2026-08-10-issues-to-file.md b/.qe/dev/log/2026-08-10-issues-to-file.md similarity index 100% rename from .dev/log/2026-08-10-issues-to-file.md rename to .qe/dev/log/2026-08-10-issues-to-file.md diff --git a/.dev/log/2026-08-11-116-trailing-newline.md b/.qe/dev/log/2026-08-11-116-trailing-newline.md similarity index 100% rename from .dev/log/2026-08-11-116-trailing-newline.md rename to .qe/dev/log/2026-08-11-116-trailing-newline.md diff --git a/.dev/log/2026-08-11-init-trailing-newline.md b/.qe/dev/log/2026-08-11-init-trailing-newline.md similarity index 100% rename from .dev/log/2026-08-11-init-trailing-newline.md rename to .qe/dev/log/2026-08-11-init-trailing-newline.md diff --git a/.dev/log/2026-08-11-w0-closeout.md b/.qe/dev/log/2026-08-11-w0-closeout.md similarity index 100% rename from .dev/log/2026-08-11-w0-closeout.md rename to .qe/dev/log/2026-08-11-w0-closeout.md diff --git a/.dev/log/2026-08-11-w0-sfix-batch.md b/.qe/dev/log/2026-08-11-w0-sfix-batch.md similarity index 100% rename from .dev/log/2026-08-11-w0-sfix-batch.md rename to .qe/dev/log/2026-08-11-w0-sfix-batch.md diff --git a/.dev/log/2026-09-03-ml-round2-answers.md b/.qe/dev/log/2026-09-03-ml-round2-answers.md similarity index 100% rename from .dev/log/2026-09-03-ml-round2-answers.md rename to .qe/dev/log/2026-09-03-ml-round2-answers.md diff --git a/.dev/log/2026-09-14-jb2-sync-fallout.md b/.qe/dev/log/2026-09-14-jb2-sync-fallout.md similarity index 100% rename from .dev/log/2026-09-14-jb2-sync-fallout.md rename to .qe/dev/log/2026-09-14-jb2-sync-fallout.md diff --git a/.dev/log/2026-09-18-ml-round3.md b/.qe/dev/log/2026-09-18-ml-round3.md similarity index 100% rename from .dev/log/2026-09-18-ml-round3.md rename to .qe/dev/log/2026-09-18-ml-round3.md diff --git a/.dev/log/2026-09-21-ml-round3-answers.md b/.qe/dev/log/2026-09-21-ml-round3-answers.md similarity index 100% rename from .dev/log/2026-09-21-ml-round3-answers.md rename to .qe/dev/log/2026-09-21-ml-round3-answers.md diff --git a/.qe/dev/log/2026-09-21-qe-migration.md b/.qe/dev/log/2026-09-21-qe-migration.md new file mode 100644 index 00000000..096e3303 --- /dev/null +++ b/.qe/dev/log/2026-09-21-qe-migration.md @@ -0,0 +1,7 @@ +# 2026-09-21 — `.dev/` becomes `.qe/dev/`; no scratch in the tree + +**Trigger**: the 2026-09-21 rulings for the Project Management Protocols QEP (QuantEcon/qeps, QEP-7, draft; discussion QuantEcon/qeps#39): one `.qe/` folder per repository, flat at the root, with the notes convention inside it and no git-ignored scratch location. + +**Done**: `git mv .dev .qe/dev`; `scratch/` removed; `.qe/README.md` (the folder's contract) and `.qe/project.yml` (tracker #257, registry slug `engine-v027`, programme `translation`) added; pointers updated in `AGENTS.md`, `.gitignore`, `check-dev-refs.mjs`, `ci.yml`, the living notes, and the code comments and reports that cite decision records; two decision records filed (`D-2026-09-21-notes-move-to-qe-dev`, `D-2026-09-21-no-scratch-in-tree`) and the two 2026-07-05 records annotated. Raw entries under `log/` and `decisions/` are unedited and keep their historical `.dev/` paths. + +**Not done**: STATE.md is untrimmed — its *In flight* section restates tracker #257, and the two disagree on W1's target release (v0.30.0 against v0.28.0); the next tidy pass brings it to orientation and the resume checklist, per the new rule. diff --git a/.dev/log/2026-09-21-v0291-gate-scenario17.md b/.qe/dev/log/2026-09-21-v0291-gate-scenario17.md similarity index 100% rename from .dev/log/2026-09-21-v0291-gate-scenario17.md rename to .qe/dev/log/2026-09-21-v0291-gate-scenario17.md diff --git a/.dev/log/2026-09-23-close-out.md b/.qe/dev/log/2026-09-23-close-out.md similarity index 100% rename from .dev/log/2026-09-23-close-out.md rename to .qe/dev/log/2026-09-23-close-out.md diff --git a/.qe/project.yml b/.qe/project.yml new file mode 100644 index 00000000..b0caff8e --- /dev/null +++ b/.qe/project.yml @@ -0,0 +1,6 @@ +# .qe/project.yml — declared facts about this repository's project, read by the qe skills. +# The tracker is the current-state register; the registry (QuantEcon/status-projects, +# projects.yml) holds the declared facts the dashboard shows. +tracker: QuantEcon/action-translation#257 +registry: engine-v027 +programme: translation diff --git a/AGENTS.md b/AGENTS.md index cf2f9b20..65e2b88d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,23 +3,28 @@ Guidance for coding agents working in this repository (GitHub Action + `translate` CLI for translating QuantEcon MyST lectures via the Anthropic API; TypeScript). -## Project notes (`.dev/`) - -Working notes — state, decisions, design ideas — live in [`.dev/`](.dev/README.md) -(the QuantEcon `.dev/` convention; this is the pilot repo). - -- Read [`.dev/STATE.md`](.dev/STATE.md) before starting; it carries a `verified: ` - first line — trust it less as that ages. It points to [`PLAN.md`](.dev/PLAN.md), - [`FUTURE.md`](.dev/FUTURE.md), and [`ARCHITECTURE.md`](.dev/ARCHITECTURE.md). -- Finish each session by appending a short log entry to [`.dev/log/`](.dev/log/) - (`YYYY-MM-DD-.md`) and updating STATE.md if reality changed. -- Record settled decisions in [`.dev/decisions/`](.dev/decisions/) in the same PR that makes - them (`D-YYYY-MM-DD-.md`; never edited — supersede with a new file + a note at the - top of the old one). -- Tag cross-repo findings inline with `#promote`. +## Project notes (`.qe/dev/`) + +Working notes — state, decisions, design ideas — live in [`.qe/dev/`](.qe/dev/README.md), +inside [`.qe/`](.qe/README.md), the repository's QuantEcon folder (this repo pilots the +convention; its home is the Project Management Protocols QEP — QuantEcon/qeps QEP-7, in draft). + +- Read [`.qe/dev/STATE.md`](.qe/dev/STATE.md) before starting; it carries a `verified: ` + first line — trust it less as that ages. It points to [`PLAN.md`](.qe/dev/PLAN.md), + [`FUTURE.md`](.qe/dev/FUTURE.md), and [`ARCHITECTURE.md`](.qe/dev/ARCHITECTURE.md). The + work-plan tracker (#257) is the current-state register; keep STATE.md to orientation and + the resume checklist rather than restating it. +- Finish each session by appending a short log entry to [`.qe/dev/log/`](.qe/dev/log/) + (`YYYY-MM-DD-.md`) and updating STATE.md if reality changed. What happened goes in + the log and in the tracker's revision-log comment, never in the tracker's status section. +- Record settled decisions in [`.qe/dev/decisions/`](.qe/dev/decisions/) in the same PR that + makes them (`D-YYYY-MM-DD-.md`; never edited — supersede with a new file + a note at + the top of the old one). A record explains the choice as of its date and guides the next + one; to change a decision, write the superseding record. +- Tag cross-repo findings inline with `#promote`; `.qe/dev/` is about this repository only. - Keep it curated: distill, supersede, or delete — git holds the history. -- `.dev/` is public: no credentials, no unpatched-vulnerability specifics (security - advisories until fixed). +- `.qe/` is public: no credentials, no unpatched-vulnerability specifics (security + advisories until fixed). Nothing under it is git-ignored; scratch lives outside the tree. ## Commands @@ -32,8 +37,9 @@ Working notes — state, decisions, design ideas — live in [`.dev/`](.dev/READ - `dist-action/` is committed and must stay in sync with `src/` — always `npm run build` after source changes; CI fails on drift. -- Use `.dev/scratch/` (gitignored) for scratch files; never create standalone summary/notes - markdown files for individual changes. +- Scratch and working files live outside the tree (the agent's own scratchpad, or + `SCRATCH=$(mktemp -d)`); never create standalone summary/notes markdown files for + individual changes. - Update `CHANGELOG.md` under `[Unreleased]` for user-visible changes. --- @@ -116,28 +122,28 @@ npm run build # Compile TypeScript + bundle dist-action/index.js success. After any scripted edit: `grep` for what should be gone, `grep` for what should be there, and check the file still parses or renders. Prefer exact-match edits over pattern replacement whenever the target is known. -- Multi-line commit messages: write to `.dev/scratch/` first, then use `-F`: +- Multi-line commit messages: write to a temporary file outside the repository first + (`SCRATCH=$(mktemp -d)`), then use `-F`: ```bash - git commit -F .dev/scratch/msg.txt + git commit -F $SCRATCH/msg.txt ``` ### Using the `gh` CLI -Always write output to the local **`.dev/scratch/`** folder (not `/tmp/`) to keep work repo-scoped: +Write command output and drafted bodies to a temporary directory outside the repository — `SCRATCH=$(mktemp -d)`, or the agent's own scratchpad — since nothing under `.qe/` is git-ignored and the repository holds no scratch location: ```bash # Read PR details -gh pr view 123 > .dev/scratch/pr.txt && cat .dev/scratch/pr.txt +gh pr view 123 > $SCRATCH/pr.txt && cat $SCRATCH/pr.txt # Create PR (write body with file tool first, then:) -gh pr create --title "..." --body-file .dev/scratch/pr-body.txt --base main > .dev/scratch/pr-result.txt && cat .dev/scratch/pr-result.txt +gh pr create --title "..." --body-file $SCRATCH/pr-body.txt --base main > $SCRATCH/pr-result.txt && cat $SCRATCH/pr-result.txt # Create release (write notes with file tool first; title is the tag alone — see the # release checklist for why) -gh release create vX.Y.Z --title "vX.Y.Z" --notes-file .dev/scratch/release-notes.md > .dev/scratch/release-result.txt && cat .dev/scratch/release-result.txt +gh release create vX.Y.Z --title "vX.Y.Z" --notes-file $SCRATCH/release-notes.md > $SCRATCH/release-result.txt && cat $SCRATCH/release-result.txt ``` -The `.dev/scratch/` folder is committed (via `.gitkeep`) but its contents are git-ignored. ### Addressing Copilot PR Review Comments @@ -147,13 +153,13 @@ After pushing a PR, Copilot may leave review comments. To address them: ```bash gh api repos/QuantEcon/action-translation/pulls/PR_NUM/comments \ --jq '.[] | {id, path, line, body: (.body | split("\n")[0])}' \ - > .dev/scratch/pr-comments.txt && cat .dev/scratch/pr-comments.txt + > $SCRATCH/pr-comments.txt && cat $SCRATCH/pr-comments.txt ``` 2. **Push fixes** to the PR branch addressing the feedback 3. **Reply to each comment** — write reply to a file, then post: ```bash gh api repos/QuantEcon/action-translation/pulls/PR_NUM/comments/COMMENT_ID/replies \ - -f body="$(cat .dev/scratch/reply.txt)" 2>&1 | jq -r '.html_url' + -f body="$(cat $SCRATCH/reply.txt)" 2>&1 | jq -r '.html_url' ``` 4. **Resolve threads** on the GitHub web interface @@ -227,7 +233,7 @@ Docs live in `docs/` — see `docs/index.md` for the full structure. Before creating a release, verify the following: 1. **CHANGELOG is up to date** — all merged PRs and features are listed under `[Unreleased]`; promote `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD` and leave a fresh empty `## [Unreleased]` header above it, so the next PR's entry has somewhere to go that is not the released section (adopted v0.28.0, #304) -2. **Version bumped** — update `package.json`, this file (`AGENTS.md`), and `.dev/PLAN.md` +2. **Version bumped** — update `package.json`, this file (`AGENTS.md`), and `.qe/dev/PLAN.md` 3. **Tests pass** — run `npm test` and confirm all tests pass 4. **Build succeeds** — run `npm run build` to compile TypeScript and update `dist-action/` 4a. **E2E-gate the tagged release** — after tagging and before moving the floating tags: @@ -268,7 +274,7 @@ Before creating a release, verify the following: 6. **Create GitHub release** — the title is **the tag and nothing else**: ```bash - gh release create vX.Y.Z --title "vX.Y.Z" --notes-file .dev/scratch/release-notes.md + gh release create vX.Y.Z --title "vX.Y.Z" --notes-file $SCRATCH/release-notes.md ``` The repo sidebar and the releases list truncate long titles, so a descriptive diff --git a/REVIEW-FABLE5-2026-07-15.md b/REVIEW-FABLE5-2026-07-15.md index 7cecd556..f5262b23 100644 --- a/REVIEW-FABLE5-2026-07-15.md +++ b/REVIEW-FABLE5-2026-07-15.md @@ -1,7 +1,7 @@ # Deep Technical Review — 2026-07-15 **Reviewer**: Claude (Fable 5)  ·  **Baseline**: `main` @ `5fb9c40` (v0.16.0, released 2026-07-15) -**Predecessor**: the 2026-07-05 deep review, whose findings live in [.dev/PLAN.md](.dev/PLAN.md) / [.dev/ARCHITECTURE.md](.dev/ARCHITECTURE.md). This review does **not** repeat that catalog — it (a) verifies what changed since, (b) reports **new** findings, with emphasis on code that landed after 2026-07-05 (v0.16.0: model upgrade, `typography.ts`, glossary tooling), and (c) audits docs, tests, dependencies, and release/ops state. +**Predecessor**: the 2026-07-05 deep review, whose findings live in [.qe/dev/PLAN.md](.qe/dev/PLAN.md) / [.qe/dev/ARCHITECTURE.md](.qe/dev/ARCHITECTURE.md). This review does **not** repeat that catalog — it (a) verifies what changed since, (b) reports **new** findings, with emphasis on code that landed after 2026-07-05 (v0.16.0: model upgrade, `typography.ts`, glossary tooling), and (c) audits docs, tests, dependencies, and release/ops state. **Method**: five parallel line-by-line review agents (action core, LLM pipeline, CLI, tests/CI/build/deps, docs/hygiene) over all 78 source files + docs + GitHub state, with independent spot-verification of every headline claim (reproduced locally or checked against production repos). Severity tags follow PLAN.md: **[H]** wrong output / broken workflow, **[M]** wrong under realistic conditions, **[L]** quality/robustness. @@ -9,7 +9,7 @@ ## 1. Executive summary -**Overall: a genuinely well-run repository whose safety nets are weaker than they look.** The engineering culture is strong — current CHANGELOG, decision records, a measured (not vibes-based) model upgrade, fresh committed `dist-action/`, green 4.4s CI, honest `.dev/` notes. But this review found that several of the quality gates the project relies on are partially illusory, that one v0.16.0 feature shipped a corruption bug into the production French repo, and that the 2026-07-05 review's high-severity correctness backlog is essentially untouched while feature work continued. +**Overall: a genuinely well-run repository whose safety nets are weaker than they look.** The engineering culture is strong — current CHANGELOG, decision records, a measured (not vibes-based) model upgrade, fresh committed `dist-action/`, green 4.4s CI, honest `.qe/dev/` notes. But this review found that several of the quality gates the project relies on are partially illusory, that one v0.16.0 feature shipped a corruption bug into the production French repo, and that the 2026-07-05 review's high-severity correctness backlog is essentially untouched while feature work continued. **Top findings** (every [H] independently re-verified — reproduction notes in the Appendix): @@ -29,11 +29,11 @@ ## 2. What changed since the 2026-07-05 review -Seven commits, +7,864/−2,365 across 89 files: `.dev/` convention (#72), model default → `claude-sonnet-5` with centralized model/token config (#75), thinking-eval concluded + glossary-review tooling (#76), experiment-page publishing (#77), deterministic French typography (#79), v0.16.0 release (#80). +Seven commits, +7,864/−2,365 across 89 files: `.qe/dev/` convention (#72), model default → `claude-sonnet-5` with centralized model/token config (#75), thinking-eval concluded + glossary-review tooling (#76), experiment-page publishing (#77), deterministic French typography (#79), v0.16.0 release (#80). **Assessment of the new work itself:** -- **`src/models.ts` — good.** Single source of truth for model/token config; verified against the current Claude API: `claude-sonnet-5`, `claude-opus-4-8`, `claude-opus-4-7` are all real IDs; the 64000 whole-document `max_tokens` is within Sonnet 5's 128K output cap; the ~30% tokenizer-growth sizing rationale matches reality. Nits: the pattern list still blesses retired model IDs (`claude-3-5-sonnet-*`, `claude-3-opus-*` — now 404) and warns on valid ones (`claude-fable-5`, bare `claude-opus-4-5`); the comment at `src/models.ts:57-63` still calls thinking-off "a deliberate hold … being measured" though `.dev/decisions/D-2026-07-14-thinking-off-sonnet5.md` settled it; `DEFAULT_THINKING: {type:'disabled'}` would 400 on `claude-fable-5` if a user ever passes it (explicit `disabled` is rejected there — omit the param instead). +- **`src/models.ts` — good.** Single source of truth for model/token config; verified against the current Claude API: `claude-sonnet-5`, `claude-opus-4-8`, `claude-opus-4-7` are all real IDs; the 64000 whole-document `max_tokens` is within Sonnet 5's 128K output cap; the ~30% tokenizer-growth sizing rationale matches reality. Nits: the pattern list still blesses retired model IDs (`claude-3-5-sonnet-*`, `claude-3-opus-*` — now 404) and warns on valid ones (`claude-fable-5`, bare `claude-opus-4-5`); the comment at `src/models.ts:57-63` still calls thinking-off "a deliberate hold … being measured" though `.qe/dev/decisions/D-2026-07-14-thinking-off-sonnet5.md` settled it; `DEFAULT_THINKING: {type:'disabled'}` would 400 on `claude-fable-5` if a user ever passes it (explicit `disabled` is rejected there — omit the param instead). - **The thinking-off and Opus-for-bulk-seed decisions are well-evidenced** (measured, recorded as decision files) — this is how model choices should be made. The same rigor has **not** been applied to the headline change: the Sonnet 4.6 → Sonnet 5 default swap shipped with no translation-quality regression measurement (now tracked as issue #82). §8.4 proposes a concrete cheap eval. - **`src/typography.ts` — right idea, one bad mask gap (finding §3.1), wrong integration point.** The transform runs only on the CLI `init` path (`src/cli/commands/init.ts:299`) — the action's sync path, `forward` resync, and rebase never call it (known, tracked as #81), so every post-seed French sync PR regresses to ASCII spacing while the prompt rule (`src/language-config.ts:53`) — the one measured to be ignored — remains the only mechanism. The prompt and the post-processor now *disagree by design*, which is only tenable until sync is wired. - **`scripts/glossary/` — useful tooling; its "verbatim production prompt" has already drifted** (omits `customInstructions`/localization rules that production `init` injects by default; copies production's rule-numbering collision; cost model silently prices unknown models at $0 and overstates Sonnet 5 spend ~33% by ignoring intro pricing). @@ -74,7 +74,7 @@ The repair tool can't catch it: `scripts/typography/apply.mjs:58` `normalize()` ### 3.5 [M] Publish safety + broken `npx` documentation -`package.json` has no `private: true` and no `files` allowlist; `npm pack --dry-run` = 428 files / 7.7 MB including `.dev/` internal notes and — because npm-packlist ignores local git excludes — the untracked `.claude/settings.local.json`. Meanwhile the bin name `translate` collides with an unrelated npm package, so the documented `npx translate …` (README:62-66, faq, architecture docs) fetches the wrong package for anyone outside this repo. Either add `private: true` and change docs to a local invocation, or claim a scoped name (`@quantecon/translate`) with a `files` allowlist. Related ops gaps: `main` has no branch protection; repo topics are empty. +`package.json` has no `private: true` and no `files` allowlist; `npm pack --dry-run` = 428 files / 7.7 MB including `.qe/dev/` internal notes and — because npm-packlist ignores local git excludes — the untracked `.claude/settings.local.json`. Meanwhile the bin name `translate` collides with an unrelated npm package, so the documented `npx translate …` (README:62-66, faq, architecture docs) fetches the wrong package for anyone outside this repo. Either add `private: true` and change docs to a local invocation, or claim a scoped name (`@quantecon/translate`) with a `files` allowlist. Related ops gaps: `main` has no branch protection; repo topics are empty. --- @@ -98,7 +98,7 @@ Spot-verified against code at `5fb9c40`. Summary: **Phase 1–8 are essentially | 7 Docs | **Open** | all items re-confirmed except rebase example (§7) | | 8 Issue gardening | **Open** | 0 of 11 done; #1 #2 #3 #4 #6 #7 #48 #53 #61 #65 #66 all still open | -**`.dev/` currency** (the convention's first real test): STATE.md went stale within a day of its `verified: 2026-07-14` line — it still says "Released v0.15.0", lists merged #72 as in-flight, and (most substantively) says fr has "no production repo yet" while `lecture-python-programming.fr` exists with a live sync workflow pinned to v0.16.0. New issues #81/#82 and PR #78 aren't reflected; no `.dev/log/` entries exist for the three 2026-07-15 sessions despite the AGENTS.md convention. The notes are good; the *update discipline on release days* is the gap. +**`.qe/dev/` currency** (the convention's first real test): STATE.md went stale within a day of its `verified: 2026-07-14` line — it still says "Released v0.15.0", lists merged #72 as in-flight, and (most substantively) says fr has "no production repo yet" while `lecture-python-programming.fr` exists with a live sync workflow pinned to v0.16.0. New issues #81/#82 and PR #78 aren't reflected; no `.qe/dev/log/` entries exist for the three 2026-07-15 sessions despite the AGENTS.md convention. The notes are good; the *update discipline on release days* is the gap. --- @@ -119,7 +119,7 @@ Spot-verified against code at `5fb9c40`. Summary: **Phase 1–8 are essentially ### 6.1 Action core (parser / diff / file-processor / heading-map / index / sync-orchestrator / pr-creator) -**Tracked items — every one re-verified STILL PRESENT at current line numbers** (only three commits touched `src/` since 2026-07-05 and none touched these sites): fence-blind `parseSections` (`src/parser.ts:69`; the preamble scan at `:40` is equally fence-blind), #65 anchor ownership (`parser.ts:112-117`), the non-ASCII anchor-adjacency regex (`file-processor.ts:564` — verified: `(经济_intro)=` doesn't match), no-op `validateMyST` (`parser.ts:223-233`; the gates at `sync-orchestrator.ts:340,410` remain unfireable), merge discarding fresh translations (`file-processor.ts:352-399`), old target heading unconditionally re-attached (`file-processor.ts:319-326`), `updateHeadingMap` neither preserving nor deleting as documented (`heading-map.ts:82-166`; its `titleHeading` param is never passed by the action caller), positional-fallback misfire on add+delete (`file-processor.ts:193,254,739-749`), duplicate-slug corruption in all three places, `${sha}^` old-content fetch (`index.ts:776,314`), `$1`/`$&` heading-replacement corruption (`file-processor.ts:387`), `context.sha` on the primary sync path (`index.ts:544`), rebase success-comments on no-op early returns (`index.ts:375,447` vs `:201-208`), >1 MB `fetchFileContent` (nuance: downstream now fails *loudly but misleadingly* — "No content provided" — rather than committing empty output), dead `toc-file` input (and `endsWith('_toc.yml')` also matches `foo_toc.yml`), rebase force-push 409/races with no retry, PR-body metadata never refreshed after a rebase, and the **Phase 1.5 rebase trust boundary — unchanged and still the priority security item** (verification confirmed sibling selection and PR-body metadata handling still lack the provenance/identity checks PLAN 1.5 calls for; exploitation specifics withheld here per the `.dev/` public-content rule — see §7.6's R2 sharpening for the structural fix). +**Tracked items — every one re-verified STILL PRESENT at current line numbers** (only three commits touched `src/` since 2026-07-05 and none touched these sites): fence-blind `parseSections` (`src/parser.ts:69`; the preamble scan at `:40` is equally fence-blind), #65 anchor ownership (`parser.ts:112-117`), the non-ASCII anchor-adjacency regex (`file-processor.ts:564` — verified: `(经济_intro)=` doesn't match), no-op `validateMyST` (`parser.ts:223-233`; the gates at `sync-orchestrator.ts:340,410` remain unfireable), merge discarding fresh translations (`file-processor.ts:352-399`), old target heading unconditionally re-attached (`file-processor.ts:319-326`), `updateHeadingMap` neither preserving nor deleting as documented (`heading-map.ts:82-166`; its `titleHeading` param is never passed by the action caller), positional-fallback misfire on add+delete (`file-processor.ts:193,254,739-749`), duplicate-slug corruption in all three places, `${sha}^` old-content fetch (`index.ts:776,314`), `$1`/`$&` heading-replacement corruption (`file-processor.ts:387`), `context.sha` on the primary sync path (`index.ts:544`), rebase success-comments on no-op early returns (`index.ts:375,447` vs `:201-208`), >1 MB `fetchFileContent` (nuance: downstream now fails *loudly but misleadingly* — "No content provided" — rather than committing empty output), dead `toc-file` input (and `endsWith('_toc.yml')` also matches `foo_toc.yml`), rebase force-push 409/races with no retry, PR-body metadata never refreshed after a rebase, and the **Phase 1.5 rebase trust boundary — unchanged and still the priority security item** (verification confirmed sibling selection and PR-body metadata handling still lack the provenance/identity checks PLAN 1.5 calls for; exploitation specifics withheld here per the `.qe/dev/` public-content rule — see §7.6's R2 sharpening for the structural fix). **New findings** (none previously tracked): @@ -176,7 +176,7 @@ Covered in §3.3 and §5. Remaining specifics: `cli-smoke.test.ts` makes fresh-c - ~55 remote branches; only 3 back open PRs. ~47 are squash-merged/dead and prunable; 6 local branches likewise. - Committed generated artifacts: `presentations/*.pdf`, built `.html`, `diagrams/workflow.png` (PLAN 7 org decision pending; content still carries the old project name = open issue #7). -- Open PRs: #78 (fr programming terms, needs native review), #71 (ml, draft), #69 (ja, 5 weeks quiet, still lacks its `LANGUAGE_CONFIGS` entry). Issues #74/#81/#82 are new since the last review and not yet in `.dev/`. +- Open PRs: #78 (fr programming terms, needs native review), #71 (ml, draft), #69 (ja, 5 weeks quiet, still lacks its `LANGUAGE_CONFIGS` entry). Issues #74/#81/#82 are new since the last review and not yet in `.qe/dev/`. - `main` unprotected; no repo topics; description hardcodes "Claude Sonnet" (will date). --- @@ -199,7 +199,7 @@ The static prefix (rules + 357-term glossary ≈ 15K tokens) is resent at full p ### 7.4 R10 — A deterministic model-swap eval (closes issue #82) -The v0.16.0 default-model change shipped unmeasured — and the repo already concluded deterministic checks beat an LLM judge. Concretely: fixed corpus (~5 lectures × zh-cn + fr), translate with candidate model via the existing `scripts/glossary/lib.mjs` harness, score with **deterministic** checks only: balanced fences / `$$` parity / heading counts / `(anchor)=` preservation (these are literally the Phase 2 `validateMyST` checks — build once, use twice), glossary-term adherence %, code-cell byte-fidelity, length-ratio bounds, fr typography compliance. JSON scorecard into `.dev/experiments/model-eval/`; gate `DEFAULT_CLAUDE_MODEL` bumps on no-regression. ~$1.50/run. +The v0.16.0 default-model change shipped unmeasured — and the repo already concluded deterministic checks beat an LLM judge. Concretely: fixed corpus (~5 lectures × zh-cn + fr), translate with candidate model via the existing `scripts/glossary/lib.mjs` harness, score with **deterministic** checks only: balanced fences / `$$` parity / heading counts / `(anchor)=` preservation (these are literally the Phase 2 `validateMyST` checks — build once, use twice), glossary-term adherence %, code-cell byte-fidelity, length-ratio bounds, fr typography compliance. JSON scorecard into `.qe/dev/experiments/model-eval/`; gate `DEFAULT_CLAUDE_MODEL` bumps on no-regression. ~$1.50/run. ### 7.5 R11 — Make the release process mechanical @@ -227,7 +227,7 @@ Phase 2 (fence-aware parser + **round-trip invariant test**) remains the highest 2. **zh-cn/fa on v0.15.0 vs fr on v0.16.0** — deliberate staged rollout of the Sonnet 5 default, or drift? If staged, is there a planned promotion date (intro pricing ends 2026-08-31)? 3. **npm intent for the CLI**: is `translate` ever meant to be published? (`private: true` vs claiming `@quantecon/translate`.) The docs' `npx translate` currently cannot work for outside users either way. 4. **Node 24**: PLAN 5.8 bundles it with the `@actions/*` major bumps (both force a dist rebuild) — want that in the same patch as 7.1 or its own release? -5. **This file**: AGENTS.md says no standalone summary files — the 2026-07-05 review was distilled into `.dev/` and deleted. Same fate intended for this report once its items are ticked into PLAN.md? +5. **This file**: AGENTS.md says no standalone summary files — the 2026-07-05 review was distilled into `.qe/dev/` and deleted. Same fate intended for this report once its items are ticked into PLAN.md? --- diff --git a/check-dev-refs.mjs b/check-dev-refs.mjs index 8957171a..8bae5e23 100644 --- a/check-dev-refs.mjs +++ b/check-dev-refs.mjs @@ -1,7 +1,7 @@ /** - * Check that `path:line` references in .dev/ notes still resolve. + * Check that `path:line` references in .qe/ notes still resolve. * - * Scans .dev/**\/*.md (excluding gitignored .dev/scratch/) for references of + * Scans .qe/**\/*.md for references of * the form `path/to/file.ext:12` or `file.ext:12-18`. A reference fails if the * file does not exist, or if the referenced line (range end) is past its end. * Bare basenames (`heading-map.ts:45`) resolve against git-tracked files. @@ -10,8 +10,10 @@ * it points at code that exists. It catches drift and typos, which is what a * decision record actually shipped once (#179, then #158). * - * Runs in CI on source changes: what invalidates a .dev reference is source - * moving underneath it, so .dev-only PRs (which skip CI) never need it. + * Runs in CI on source changes, which is what usually invalidates a .qe + * reference (source moving underneath it). .qe-only PRs skip CI but can still + * add a broken or mistyped reference, so run `npm run check-dev-refs` before + * merging one. */ import { execSync } from 'child_process'; @@ -30,7 +32,7 @@ function findMarkdownFiles(dir) { for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const full = path.join(dir, entry.name); if (entry.isDirectory()) { - if (full !== path.join('.dev', 'scratch')) results.push(...findMarkdownFiles(full)); + results.push(...findMarkdownFiles(full)); } else if (entry.name.endsWith('.md')) { results.push(full); } @@ -45,7 +47,7 @@ function lineCount(file) { const failures = []; let checked = 0; -for (const mdFile of findMarkdownFiles('.dev')) { +for (const mdFile of findMarkdownFiles('.qe')) { const lines = fs.readFileSync(mdFile, 'utf8').split('\n'); lines.forEach((line, i) => { for (const match of line.matchAll(REF_PATTERN)) { @@ -71,8 +73,8 @@ for (const mdFile of findMarkdownFiles('.dev')) { } if (failures.length > 0) { - console.error(`✗ ${failures.length} stale reference(s) in .dev/ — update the note or the code:`); + console.error(`✗ ${failures.length} stale reference(s) in .qe/ — update the note or the code:`); for (const failure of failures) console.error(` ${failure}`); process.exit(1); } -console.log(`✓ ${checked} .dev/ file references resolve`); +console.log(`✓ ${checked} .qe/ file references resolve`); diff --git a/dist-action/index.js b/dist-action/index.js index 8b1684d9..dc862014 100644 --- a/dist-action/index.js +++ b/dist-action/index.js @@ -26429,18 +26429,18 @@ var LANGUAGE_CONFIGS = { // per-flag dispositions in QuantEcon/project-translation // reports/2026-08-17-ml-python-by-example-review-disposition.md. // The math-heavy Hint/Solution ruling is recorded in - // .dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md. + // .qe/dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md. // Extended again 2026-09 from the second inline round: 118 suggestion // blocks on lecture-python-programming.ml#7 (functions), dispositions in // reports/2026-09-01-ml-functions-review-disposition.md (same repo); the // exercise-statement scope ruling is - // .dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md. + // .qe/dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md. // The editor's ml#12 answers (2026-09-01) landed 2026-09-03: "For // example" joins the discourse rule; glossary v0.5.0 pins already / name / // example(s) / work; and his exercise ruling REPLACED the 09-01 scope rule // — every exercise-family block is now byte-identical to the source, // enforced in code by verbatim-directives.ts (decision record - // .dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md). + // .qe/dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md). // Third inline round, 2026-09-18: 44 suggestion blocks on // lecture-python-programming.ml#13 (matplotlib), dispositions in // reports/2026-09-18-ml-matplotlib-review-disposition.md. Every round-2 @@ -26454,7 +26454,7 @@ var LANGUAGE_CONFIGS = { // becomes a rule only if it recurs (twice in a round, or across rounds) — // draw-to-draw variance makes a singleton as likely noise as habit. The // Further Reading scope ruling is - // .dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md. + // .qe/dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md. // // The editor's answers on lecture-python-programming.ml#22 (2026-09-19), // encoded 2026-09-21 (rules 27 → 28, glossary v0.7.0): the comma between diff --git a/docs/projects/README.md b/docs/projects/README.md index 814a2807..0280c134 100644 --- a/docs/projects/README.md +++ b/docs/projects/README.md @@ -124,7 +124,7 @@ Summer students would likely focus on **Project A** (the most coding-intensive), ## Related Documents -- [ARCHITECTURE.md](../../.dev/ARCHITECTURE.md) -- Open design questions for `action-translation`; Q3 discusses whole-file vs section-by-section translation architecture, and `experiments/forward/` contains initial experiment results that Project A should build on +- [ARCHITECTURE.md](../../.qe/dev/ARCHITECTURE.md) -- Open design questions for `action-translation`; Q3 discusses whole-file vs section-by-section translation architecture, and `experiments/forward/` contains initial experiment results that Project A should build on - [_archive/PROJECT-BENCHMARK.md](_archive/PROJECT-BENCHMARK.md) -- Original comprehensive benchmark plan with detailed infrastructure specs (CI/CD, issue templates, provider interfaces, dashboard mockup) -- useful reference when implementing - [architecture.md](../developer/architecture.md) -- `action-translation` module structure - [testing.md](../developer/testing.md) -- How the action's test suite works diff --git a/experiments/fr-glossary-programming/REPORT.md b/experiments/fr-glossary-programming/REPORT.md index 9c8fc625..da332e21 100644 --- a/experiments/fr-glossary-programming/REPORT.md +++ b/experiments/fr-glossary-programming/REPORT.md @@ -53,7 +53,7 @@ result for the method: the second model is not a bake-off, it is the signal. Beyond zero drift, Opus was *correct* where Sonnet drifted: `mutable` → `mutable` vs Sonnet's `muable`, which is not the Python sense. Output lengths were near-identical, so the cost difference is purely the price ratio: $1.22 → $2.03 for 5 lectures (~$6.3 → -~$10.4 for all 26). Recorded as `.dev/decisions/D-2026-07-14-opus-for-bulk-seed.md`. +~$10.4 for all 26). Recorded as `.qe/dev/decisions/D-2026-07-14-opus-for-bulk-seed.md`. ## The 11 candidates diff --git a/experiments/ml-benchmark/DISPOSITIONS.md b/experiments/ml-benchmark/DISPOSITIONS.md index 268434d5..548e3cd0 100644 --- a/experiments/ml-benchmark/DISPOSITIONS.md +++ b/experiments/ml-benchmark/DISPOSITIONS.md @@ -147,7 +147,7 @@ interface verbs that were actually transliterated), and **soft-watch** words tha legitimately go both ways by function (`use`, `open`, `right`), which flag for a human eye rather than fail the build. -Candidate for `.dev/decisions/` promotion once Phase 2 validates the rules +Candidate for `.qe/dev/decisions/` promotion once Phase 2 validates the rules empirically. #promote ## Rule text (implemented in the companion PR) diff --git a/experiments/ml-benchmark/REPORT.md b/experiments/ml-benchmark/REPORT.md index 8648c773..b7fc3290 100644 --- a/experiments/ml-benchmark/REPORT.md +++ b/experiments/ml-benchmark/REPORT.md @@ -440,7 +440,7 @@ and roughly double the $3.20 the tooling reports. **The cost tracker reports `$0.000` for every `claude-opus-5` call.** The model is absent from `VALID_MODEL_PATTERNS` in `src/models.ts` (a known staleness item in -`.dev/FUTURE.md`) and evidently from the pricing table too, so Opus spend is +`.qe/dev/FUTURE.md`) and evidently from the pricing table too, so Opus spend is invisible rather than merely unvalidated. Sonnet 5 measures ~$0.23/lecture; Opus 5 list price is $5/$25 per MTok against Sonnet's $3/$15, so the true Opus figure is roughly $0.4–0.5/lecture. Filed as **#230**. diff --git a/experiments/thinking-sonnet5/PLAN.md b/experiments/thinking-sonnet5/PLAN.md index f2072cbd..2d55daee 100644 --- a/experiments/thinking-sonnet5/PLAN.md +++ b/experiments/thinking-sonnet5/PLAN.md @@ -217,7 +217,7 @@ Romance-language expansion). If one language benefits and the other doesn't, the outcome can be a per-language default rather than a single tool-wide value. Whatever we choose becomes a decision record in -[`.dev/decisions/`](../../.dev/decisions/) and, if we enable thinking, a code +[`.qe/dev/decisions/`](../../.qe/dev/decisions/) and, if we enable thinking, a code change: flip `DEFAULT_THINKING` (or make it per-path) **and** switch the translator/reviewer text extraction from `content[0]` to `content.filter(b => b.type === 'text')` (a thinking block lands first when diff --git a/experiments/thinking-sonnet5/REPORT.md b/experiments/thinking-sonnet5/REPORT.md index 70aa4c73..c1f94bdb 100644 --- a/experiments/thinking-sonnet5/REPORT.md +++ b/experiments/thinking-sonnet5/REPORT.md @@ -80,4 +80,4 @@ ranking): - Harness + prompts: `scripts/` (see [PLAN.md](./PLAN.md)); metrics in `outputs/metrics.jsonl` (git-ignored). -- Decision record: `.dev/decisions/D-2026-07-14-thinking-off-sonnet5.md`. +- Decision record: `.qe/dev/decisions/D-2026-07-14-thinking-off-sonnet5.md`. diff --git a/scripts/glossary/lib.mjs b/scripts/glossary/lib.mjs index 75533a07..7db1bcae 100644 --- a/scripts/glossary/lib.mjs +++ b/scripts/glossary/lib.mjs @@ -36,7 +36,7 @@ export function rel(p) { // signal, and cutting it to save cost silently breaks the method: // // seed — the model that will actually do the bulk translation (Opus 4.8, per -// .dev/decisions/D-2026-07-14-opus-for-bulk-seed.md). +// .qe/dev/decisions/D-2026-07-14-opus-for-bulk-seed.md). // probe — a DIFFERENT-family model, run only to disagree with the seed. // // Why a probe is needed: on the fr programming run, the seed model showed ZERO diff --git a/src/language-config.ts b/src/language-config.ts index d141db82..9ac815dc 100644 --- a/src/language-config.ts +++ b/src/language-config.ts @@ -75,18 +75,18 @@ export const LANGUAGE_CONFIGS: Record = { // per-flag dispositions in QuantEcon/project-translation // reports/2026-08-17-ml-python-by-example-review-disposition.md. // The math-heavy Hint/Solution ruling is recorded in - // .dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md. + // .qe/dev/decisions/D-2026-08-17-ml-math-heavy-sections-stay-english.md. // Extended again 2026-09 from the second inline round: 118 suggestion // blocks on lecture-python-programming.ml#7 (functions), dispositions in // reports/2026-09-01-ml-functions-review-disposition.md (same repo); the // exercise-statement scope ruling is - // .dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md. + // .qe/dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md. // The editor's ml#12 answers (2026-09-01) landed 2026-09-03: "For // example" joins the discourse rule; glossary v0.5.0 pins already / name / // example(s) / work; and his exercise ruling REPLACED the 09-01 scope rule // — every exercise-family block is now byte-identical to the source, // enforced in code by verbatim-directives.ts (decision record - // .dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md). + // .qe/dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md). // Third inline round, 2026-09-18: 44 suggestion blocks on // lecture-python-programming.ml#13 (matplotlib), dispositions in // reports/2026-09-18-ml-matplotlib-review-disposition.md. Every round-2 @@ -100,7 +100,7 @@ export const LANGUAGE_CONFIGS: Record = { // becomes a rule only if it recurs (twice in a round, or across rounds) — // draw-to-draw variance makes a singleton as likely noise as habit. The // Further Reading scope ruling is - // .dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md. + // .qe/dev/decisions/D-2026-09-18-ml-further-reading-lists-stay-english.md. // // The editor's answers on lecture-python-programming.ml#22 (2026-09-19), // encoded 2026-09-21 (rules 27 → 28, glossary v0.7.0): the comma between diff --git a/tool-test-action-on-github/README.md b/tool-test-action-on-github/README.md index cf47d265..185707d7 100644 --- a/tool-test-action-on-github/README.md +++ b/tool-test-action-on-github/README.md @@ -91,7 +91,7 @@ Both source and target PRs remain **open** for evaluation. ./rate-check.sh --languages ml --draws 12 # this checkout's build ``` -Phase 1 takes **one draw per scenario**. That is the right test of whether the tagged bytes deliver through the action path, but a model-side defect that fails less than always slips through it: scenario 17's new document (`game-theory.md`) was refused by the structural-parity guard on about 40% of draws from v0.28.0 to v0.29.0 and passed three release gates before the rate rose enough to be caught (QuantEcon/action-translation#320). `rate-check.sh` measures the rate directly: it runs the CLI N times (default 12) per fixture and language, counts the draws that produced no output file, prints a table with the refusal reasons, and exits non-zero if any cell shows more than `--max-refusals` (default 1). It costs no GitHub runs — N × fixtures × languages CLI translations against a cached prompt — and `--ref` builds any tag or branch in a temporary worktree with that version's own glossary, so an old release can be measured too. Fixtures default to the files the scenarios introduce as whole new documents (only `game-theory.md` today); add to `--fixtures` when a scenario adds another. Logs, `meta.txt` and `summary.txt` land in `.dev/scratch/rate-check/-/`; `--summarize ` re-prints a finished run's table and verdict without new draws. Validated on 2026-09-23: v0.29.2 reads 0/12 on `game-theory.md` for `ml`, v0.29.0 (via `--ref`) reads 4/12 and fails — the defect that passed three gates. +Phase 1 takes **one draw per scenario**. That is the right test of whether the tagged bytes deliver through the action path, but a model-side defect that fails less than always slips through it: scenario 17's new document (`game-theory.md`) was refused by the structural-parity guard on about 40% of draws from v0.28.0 to v0.29.0 and passed three release gates before the rate rose enough to be caught (QuantEcon/action-translation#320). `rate-check.sh` measures the rate directly: it runs the CLI N times (default 12) per fixture and language, counts the draws that produced no output file, prints a table with the refusal reasons, and exits non-zero if any cell shows more than `--max-refusals` (default 1). It costs no GitHub runs — N × fixtures × languages CLI translations against a cached prompt — and `--ref` builds any tag or branch in a temporary worktree with that version's own glossary, so an old release can be measured too. Fixtures default to the files the scenarios introduce as whole new documents (only `game-theory.md` today); add to `--fixtures` when a scenario adds another. Logs, `meta.txt` and `summary.txt` land in `${TMPDIR:-/tmp}/action-translation-rate-check/-/`, outside the repository; `--summarize ` re-prints a finished run's table and verdict without new draws. Validated on 2026-09-23: v0.29.2 reads 0/12 on `game-theory.md` for `ml`, v0.29.0 (via `--ref`) reads 4/12 and fails — the defect that passed three gates. ### Phase 2: Evaluate Translation Quality diff --git a/tool-test-action-on-github/rate-check.sh b/tool-test-action-on-github/rate-check.sh index acc3adbb..e5558abd 100755 --- a/tool-test-action-on-github/rate-check.sh +++ b/tool-test-action-on-github/rate-check.sh @@ -26,7 +26,9 @@ # --model Claude model (default claude-sonnet-5, the production default) # --summarize DIR re-read a finished run directory (no new draws) and print its table # -# Per-draw logs, meta.txt and summary.txt land in .dev/scratch/rate-check/-/. +# Per-draw logs, meta.txt and summary.txt land outside the repository, in +# ${TMPDIR:-/tmp}/action-translation-rate-check/-/ (nothing under .qe/ is +# git-ignored and the tree holds no scratch location — D-2026-09-21-no-scratch-in-tree). # Exit 0 = every cell within --max-refusals; 1 = a cell over it; 2 = usage or setup error. set -euo pipefail @@ -156,7 +158,7 @@ for fx in "${FIXTURE_LIST[@]}"; do cp "$DATA_DIR/$fx" "$SRC_DIR/"; done } > "$SRC_DIR/_toc.yml" STAMP="$(date -u +%Y-%m-%dT%H-%M-%SZ)-$$" # PID keeps two runs in one second apart -RUN_DIR="$REPO_ROOT/.dev/scratch/rate-check/$STAMP" +RUN_DIR="${TMPDIR:-/tmp}/action-translation-rate-check/$STAMP" # outside the tree (no in-tree scratch) mkdir -p "$RUN_DIR" { echo "ENGINE_TAG='${ENGINE_TAG}'"; echo "ENGINE_SHA='${ENGINE_SHA}'"; echo "MODEL='${MODEL}'"