chore: adopt .dev/ project-notes convention (pilot) — seeded from the 2026-07-05 deep review

[mmcky]

Summary

Establishes action-translation as the pilot repo for the QuantEcon .dev/ project-notes convention (pilot: #73; spec: QuantEcon/QuantEcon.manual#103), seeded with the full output of the 2026-07-05 deep technical review (all source, tests, CI, docs, issues, and PRs).

.dev/ is a lightweight, tool-agnostic folder for state, decisions, and design ideas, maintained jointly by humans and coding agents. Plain markdown only — no YAML schema, no CI gates; structure lives in filenames, git, and three plain-text conventions (a verified: first line in STATE.md, supersession notes in old decision files, inline #promote tags for cross-repo findings). Design rule from the spec: complexity must be earned by observed pain, not installed in anticipation of it.

Structure

.dev/
├── STATE.md         # in flight / blocked / next (~1 page); first line "verified: 2026-07-05"
├── PLAN.md          # 8-phase maintenance roadmap from the review
├── ARCHITECTURE.md  # living: recommendations R1–R7 + open questions (repo topology,
│                    #   mystmd migration, whole-file vs section translation)
├── FUTURE.md        # living: 12 documented feature ideas
├── decisions/       # 9 settled decisions, D-YYYY-MM-DD-<slug>.md (context/decision/consequences)
├── log/             # dated session notes with inline #promote tags
└── scratch/         # gitignored — now the repo's single scratch location (replaces .tmp/)

The agent contract lives in AGENTS.md; the convention itself is documented in .dev/README.md.

Notes for review

• Three iterations in one day, deliberately (visible in the commit history): first cut with a single DECISIONS.md + archive folder, then a full-mechanism cut (YAML frontmatter, deterministic health check + CI workflow), then this final simplified form after the spec revision. The intermediate machinery is preserved in git history and in manual#103's edit history if evidence of need ever emerges — the "tidy .dev/" session workflow is the probe for that.
• Scratch migration: .tmp/ → .dev/scratch/ per the pilot spec (adoption step 2); copilot-instructions.md and .gitignore updated, .tmp/ left ignored as a retired legacy path so stale local copies stay invisible.
• Security: the rebase-mode metadata finding from the review is now stated vaguely in PLAN.md per the convention's public-content rule, and the fix is pulled forward to Phase 1.5 (details available privately).
• CI: paths-ignore: ['.dev/**'] added per the spec — safe today because main has no required status checks; an inline comment notes to drop the ignore if test ever becomes required (a skipped required check would deadlock .dev-only PRs).
• PLAN.md's maintenance content is review output, not yet triaged — findings can be re-prioritised as phases are picked up. STATE.md points at the natural first workload (Phase 1, the v0.15.1 patch).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR replaces the legacy dev-notes/ directory with a standardized .dev/ working-notes convention and adds a root AGENTS.md to direct coding agents/maintainers to the new plan/decision artifacts. It aligns internal references to the new locations while removing the old note files (with history preserved in git).

Changes:

• Introduces .dev/ as the canonical home for working notes: PLAN.md, FUTURE.md, ARCHITECTURE.md, DECISIONS.md, plus .dev/README.md describing the convention.
• Adds AGENTS.md at repo root to point agents to .dev/ and common repo commands/rules.
• Updates internal doc references and removes the old dev-notes/ files.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/projects/README.md	Updates related-doc link to point at .dev/ARCHITECTURE.md instead of dev-notes/PLAN.md.
dev-notes/README.md	Deletes legacy developer-notes index (superseded by .dev/README.md).
dev-notes/PLAN.md	Deletes legacy roadmap (content distilled into new .dev/* docs; full text remains in git history).
dev-notes/FIX-ISSUE-63.md	Deletes legacy issue-63 fix write-up (distilled into .dev/DECISIONS.md / .dev/FUTURE.md; history preserved).
AGENTS.md	Adds a root pointer for agents/maintainers to .dev/ and key repo commands/rules.
.github/copilot-instructions.md	Updates release checklist reference from dev-notes/PLAN.md to .dev/PLAN.md.
.dev/README.md	Adds documentation for the .dev/ convention, structure, and update rules.
.dev/PLAN.md	Adds the new active maintenance plan seeded from the technical review.
.dev/FUTURE.md	Adds a curated set of documented feature ideas for later iteration.
.dev/DECISIONS.md	Adds an append-only micro-ADR log seeded with key historical decisions.
.dev/ARCHITECTURE.md	Adds an architecture snapshot, recommendations, and open design questions.

[mmcky]

Review summary — approved ✅

Docs/process-only change (no source touched); low risk — nothing here ships to npm, the action bundle, or the docs site. Verified on the branch that the dev-notes/ → .dev/ migration is complete and internally consistent: no dangling .tmp/ or dev-notes/ references remain, dev-notes/ is fully removed, and the published docs/projects/README.md cross-link was correctly repointed to .dev/ARCHITECTURE.md.

What's done well

• CI paths-ignore: ['.dev/**'] is correct — it only skips when all changed files are under .dev/, so mixed src/+.dev/ PRs still run the dist-drift check. The inline caveat about paths-ignore deadlocking a required status check is exactly right.
• .gitignore keeps .dev/scratch/ committed-but-empty via .gitkeep and retains the .tmp/ ignore for stale local copies.
• Security redaction applied as designed — the rebase-mode metadata fix stays vague in PLAN Phase 1.5 per the public-content rule.

Fixes applied in 4b803db (from review)

• STATE.md was stale on arrival — it listed PR feat(glossary): add French (fr) translation glossary #68 (fr) as open/awaiting review with a missing LANGUAGE_CONFIGS entry, but feat(glossary): add French (fr) translation glossary #68 merged 2026-07-14 with its config wiring. Moved fr to "Recently landed", refreshed Health & context, bumped verified: to 2026-07-14.
• ARCHITECTURE.md R2 described the rebase PR-body channel as an "input surface whose validation is being hardened in PLAN Phase 1.5" — more trust-boundary detail than the public-content rule wants while the fix is unshipped. Dropped that clause; kept the engineering rationale.
• Added a .dev/log/ entry per the AGENTS.md contract (the convention dogfooding itself).

Left for the author's call (not blocking): copilot-instructions.md's release checklist points the version bump at .dev/PLAN.md, but PLAN.md carries the version as prose, not a field — STATE.md's Health section may be the more natural home for "current released version."

Merging.