dev: .dev/ becomes .qe/dev/ — one QuantEcon folder per repository, no scratch in the tree

.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/*<lang>*`. This changes
+   conventions, `src/language-config.ts`, and any `.qe/dev/decisions/*<lang>*`. 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
 

.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

.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/

.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.

.dev/PLAN.md → .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

.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-<slug>.md — one settled decision per file
+└── log/             # YYYY-MM-DD-<id>.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).

.dev/STATE.md → .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 —

.dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md → .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

.dev/decisions/D-2026-07-05-scratch-moves-to-dev-scratch.md → .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

.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).

.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).