.dev/ notes convention — pilot adoption

[mmcky]

.dev/ pilot — action-translation

Revision note: simplified to the lightweight spec — see
QuantEcon/QuantEcon.manual#103 for the convention and rationale. Earlier
iterations live in that issue's edit history.

action-translation is the first pilot repo for the QuantEcon .dev/
project-notes convention: a lightweight way to document state, decisions,
and design ideas shared between humans and coding agents.

Structure

.dev/
├── STATE.md         # in flight / blocked / next (~1 page);
│                    #   first line "verified: YYYY-MM-DD"
├── PLAN.md          # current roadmap
├── decisions/       # D-2026-07-05-<slug>.md — never edited; supersede with
│                    #   a new file + note at the top of the old one
├── log/             # 2026-07-05-<session-id>.md — short session notes
└── ARCHITECTURE.md, FUTURE.md   # optional living docs (root of .dev/ =
                     #   living; decisions/ and log/ = append-only)

No YAML, no CI gates: structure lives in filenames, git, the verified:
first line, and inline #promote tags for cross-repo findings.

Adoption steps (reconciling with PR #72)

1. Merge PR chore: adopt .dev/ project-notes convention (pilot) — seeded from the 2026-07-05 deep review #72 for its content (technical review, plan, decisions,
   architecture notes), then a follow-up structure PR:
   • PLAN.md → stays as-is.
   • DECISIONS.md → split into decisions/, date+slug filenames; several
     entries are cross-repo candidates — tag them #promote.
   • ARCHITECTURE.md, FUTURE.md → stay as living docs at .dev/ root
     (deliberation and idea backlog; settled architecture graduates to
     contributor docs, committed ideas graduate to PLAN.md).
   • Seed STATE.md from current status with a verified: line.
   • Contract block → AGENTS.md.
2. Migrate .tmp/ → .dev/scratch/ (gitignored) and update
   copilot-instructions, so the repo has one scratch convention.
3. Add .dev/** to paths-ignore in CI and translation workflows.
4. Security note from review: .dev/PLAN.md currently documents an
   unpatched trust-boundary weakness in rebase mode with file:line detail.
   Per the convention's public-content rule, keep such entries vague until
   fixed — and pull that fix forward in the plan, since the detail is
   already public.

Working the pilot

• Agents: read STATE.md first; append a log entry each session; file
  decisions in the PR that makes them; tag cross-repo findings #promote.
• Humans: curate STATE.md/PLAN.md, approve decisions and pruning.
• Occasional "tidy .dev/" session: agent flags contradictions and
  staleness, proposes pruning; human approves the PR. If tidy passes keep
  finding the same mechanical issues, that's the evidence to script a check —
  not before.

Review

After a few months of real use: did STATE.md become what agents and humans
actually read first? Are #promote tags accumulating (the trigger for
building the org knowledge vault)? Keep, expand, or git rm -r .dev/ —
plain markdown and pointers make walking back free.

[mmcky]

Pilot spec updated to match the revised design in QuantEcon/QuantEcon.manual#103 — health-check action is now the first build item. Body updated in place.

[mmcky]

Detailed assessment (from the session that produced PR #72 — which is the previous iteration of this convention, so the two need reconciling; see §2).

1. What's strong

The design's center of gravity — machine-detectable staleness over LLM judgment — is the right bet, and most of the spec's best features follow from it: the 4-key frontmatter cap with a named consumer per key (schema growth requires amending the convention — this is what keeps agent-maintained systems from schema-sprawling), declared lifecycles per file (living vs append-only, no ambiguous files), maintenance attached to events rather than willpower, and the promote-link-append mechanic (one list item mutation is simultaneously status, provenance, and reader context — elegant). The risk register is honest, especially #3: over-production is the failure mode of agent-maintained notes, not neglect. Building the health check first, in this repo (which already ships actions and has CI muscle), is the right sequencing. Kill/keep at 3 months with git rm -r .dev/ as the exit is the right level of commitment.

2. Reconciliation with PR #72 (immediate, practical)

PR #72 (opened today, this repo) implements the prior design: PLAN.md + FUTURE.md + ARCHITECTURE.md + single append-only DECISIONS.md, no STATE.md/logs/frontmatter. Its content is valuable and should survive — it carries the full 2026-07-05 technical review (8-phase maintenance plan, 12 documented feature ideas, architecture recommendations + open questions, 9 distilled decisions). Suggested mapping into the pilot structure:

PR #72 artifact	Pilot home
PLAN.md (8 phases)	PLAN.md unchanged — already "current roadmap, not history"
DECISIONS.md (9 entries, micro-ADR)	Split into decisions/ one-per-file; most qualify as "settled, still-relevant"; several are genuine scope: org candidates (the convention itself, ml keep-English policy) — a good first test of the scope field
ARCHITECTURE.md (R1–R7 + open questions Q1–Q3)	No home in the spec as written — see §3.1
FUTURE.md (12 documented ideas)	Same gap — see §3.1
Root AGENTS.md	Contract lands here (spec says CLAUDE.md/AGENTS.md — AGENTS.md is the tool-agnostic choice, consistent with the convention's own principle)

Cheapest path: merge #72 for the content, then a follow-up "adopt pilot structure" PR (STATE.md, decisions/ split, log/, scratch/, CI wiring). Reworking #72 in place also works but couples the review corpus to the structure debate.

3. Design feedback

3.1 The layout needs an explicit policy for living docs beyond STATE/PLAN. Today's session iterated repo-topology and mystmd-migration questions in ARCHITECTURE.md — multi-page analysis that cannot fit a 1-page STATE.md, isn't roadmap, and isn't yet a decision. Ditto a documented feature backlog (FUTURE.md): ideas need a home where they're iterated before graduating to PLAN. Recommend the spec declare the four core files a minimum, with additional declared-lifecycle living docs permitted (and verified: allowed on any living doc, required on STATE.md — same consumer, no new keys). Otherwise the pilot's first real week of use already violates the spec.

3.2 Decision IDs collide under parallel agents. D-007 sequence numbers reintroduce exactly the coordination problem the session-id log filenames solve — two concurrent PRs will both allocate D-012. Suggest date+slug filenames (D-2026-07-05-artifact-deploy.md) with superseded_by referencing the slug; keeps "structured data in filenames" and removes the allocation race.

3.3 The signal floor straddles pass 1 and pass 2. "References no change, decision, or blocker" is a semantic judgment. Split it: pass 1 gets a deterministic proxy (required sections present; contains at least one commit SHA / PR number / file path — greppable), pass 2 keeps the semantic version.

3.4 Append-only vs "pruned once distilled" is a contradiction agents will trip on. log/ is declared append-only (never edited), but the curation principle says logs are "raw material with a shelf life, pruned once distilled." An agent instructed "never edit append-only files" will refuse to prune. State explicitly: append-only means entries are never edited; whole log files older than N months with all promote: items resolved are deleted by the sweep (deletion ≠ editing).

3.5 This repo already has a scratch convention. .tmp/ is gitignored, .gitkeep-anchored, and documented in copilot-instructions. Two scratch dirs will split agent behaviour. Pilot setup step 2 should pick one — either migrate .tmp/ → .dev/scratch/ (update copilot-instructions + .gitignore) or drop scratch/ locally. Migration is cheap and keeps the fleet convention uniform.

3.6 Decide advisory vs blocking now. Recommend: schema violations (unknown frontmatter keys, dangling superseded_by) block PRs that touch .dev/; staleness/signal findings are advisory (scheduled run refreshes a single tracking issue). A stale verified must not block an unrelated bugfix, and a blocking staleness check invites ritual verified bumps — which leads to:

3.7 Guard verified against Goodharting. Agents ending every session will be inclined to bump verified as a courtesy, defeating the mechanism. The contract should say: update verified only after re-confirming each STATE.md claim against repo reality; pass 2 audits verified bumps that coincide with no STATE.md diff.

3.8 Instrument the success signals from day 1. "Fewer figured-out-again entries" needs a baseline and a grep-able marker — e.g., the contract asks agents to tag re-derived: in a log entry whenever they had to rediscover something STATE.md should have told them. That makes the 3-month review a count, not a vibe. Add pass-2 token cost to the review criteria (risk #4 says value must be measured — measure cost too), and name the review owner + date now.

3.9 Extend the public-exposure rule beyond credentials. Concrete case from today: .dev/PLAN.md (PR #72) documents an unpatched trust-boundary weakness in rebase mode with file:line detail. "Public — write accordingly" should explicitly cover unpatched-vulnerability specifics (track those in security advisories or keep the .dev/ entry vague until fixed) — and, separately, that Phase 4 fix should now move up the queue since the finding is public.

3.10 Minor: define where the log session id comes from (4 random hex is fine, but say so); STATE.md's "next" should link to the current PLAN phase rather than restate it (one less thing to drift); note that paths-ignore: ['.dev/**'] only skips runs where all changed files match, which is the desired behaviour — and the health-check workflow conversely triggers on .dev/**.

4. Suggested pilot order

1. Merge PR chore: adopt .dev/ project-notes convention (pilot) — seeded from the 2026-07-05 deep review #72 (content) → 2. structure-adoption PR: STATE.md seeded, DECISIONS.md → decisions/ (date+slug), log/ + first session entry, scratch decision (§3.5), contract into AGENTS.md, CI paths-ignore → 3. health-check pass 1 as a ~30-line script + scheduled/PR workflow in this repo (blocking/advisory split per §3.6) → 4. run for real work (Phase 1 of PLAN.md is the natural first workload) → 5. pass 2 + vault sweep only once genuine promote: items exist (the spec already gets this right).

Overall: the end-state design is a real upgrade over #72's iteration — the gaps above are all spec-tightening, not rethinks.

[mmcky]

Thanks — this is exactly the kind of contact-with-reality feedback the pilot was for. Response below, with one meta-decision up front.

Meta-decision: we've simplified the spec. Stepping back from this thread, the mechanism was accumulating governance faster than content — schema validation, blocking/advisory taxonomies, metrics instrumentation, audit rules — each defensible alone, collectively heavier than a notes folder warrants. The revised spec (see updated body here and in QuantEcon/QuantEcon.manual#103) drops the YAML frontmatter schema, CI lint, and metrics apparatus entirely. New design rule: complexity must be earned by observed pain, not installed in anticipation of it. The tidy-session workflow is the probe — if it repeatedly surfaces the same mechanical problems, that's the evidence to script a check. The earlier full-mechanism design is preserved in #103's edit history for when/if that day comes.

Adopted from this review (surviving the simplification because they're structural, not machinery):

• §3.1 — Living docs beyond STATE/PLAN, via lifecycle-by-location: anything at .dev/ root is living; decisions/ and log/ are append-only. ARCHITECTURE.md and FUTURE.md are explicitly legitimate, with graduation paths (settled architecture → contributor docs; committed ideas → PLAN.md) so .dev/ doesn't become a shadow docs folder.
• §3.2 — Date+slug decision filenames (D-2026-07-05-artifact-deploy.md); kills the sequence-number allocation race between parallel agents.
• §3.4 — Contradiction resolved: append-only means entries are never edited; distilled/stale log files may be deleted in a tidy PR (deletion ≠ editing).
• §3.5 — .tmp/ → .dev/scratch/, copilot-instructions updated; one scratch convention.
• §3.9 — Public-content rule extended: no unpatched-vulnerability specifics in .dev/ (security advisories until fixed) — and agreed the rebase-mode fix moves up the queue since the detail is already public.
• §2/§4 — Merge chore: adopt .dev/ project-notes convention (pilot) — seeded from the 2026-07-05 deep review #72 for content, restructure in a follow-up PR, in your suggested order.

Deferred with the machinery (good designs, waiting for evidence of need): §3.3 signal-floor split, §3.6 blocking/advisory taxonomy, §3.7 verified-bump auditing (if revived, we'd use accountable bumps — a "confirmed N / corrected M" log line — rather than flagging no-diff bumps, since re-confirming with no changes is the legitimate best case), §3.8 metrics instrumentation (the re-derived: idea is good and costs nothing to use informally as an inline tag), §3.10 details.

Net effect on the pilot: simpler to adopt, same load-bearing structure (curation over history, immutable decisions, event-attached updates, freshness signal on STATE.md), and the review question becomes the honest one — after a few months, is STATE.md the thing agents and humans actually read first?

[mmcky]

Closing — the pilot is complete and the convention is adopted. Outcome for the record, since that is the artifact a pilot owes:

Kept. The four-file core (STATE.md, PLAN.md, decisions/, log/); declared lifecycles, so no file is ambiguously living-or-historical; date+slug decision filenames instead of sequence numbers (§3.2 above — D-007 reintroduces the allocation race that concurrent agents cause); .dev/scratch/ replacing the old .tmp/ convention (D-2026-07-05-scratch-moves-to-dev-scratch.md); the contract itself in AGENTS.md rather than a tool-specific file.

Dropped. The YAML frontmatter schema, the two-pass health-check apparatus, the blocking/advisory taxonomy, and the metrics instrumentation. The design rule that came out of this thread is the durable part: complexity must be earned by observed pain, not installed in anticipation of it. The fuller mechanism is preserved in QuantEcon/QuantEcon.manual#103's edit history if that day comes.

Added since. Exactly one CI gate — npm run check-dev-refs (#158), wired into ci.yml. That is the entire enforcement mechanism.

Evidence it earns its keep. Wave 1 ran eleven PRs through the apparatus in a single day (#158–#168, shipped v0.24.0), and this week's issue triage was able to verify tracker claims against .dev/ records instead of re-deriving them from git history — which is the thing the convention was supposed to buy.

Decision record: .dev/decisions/D-2026-07-05-adopt-dev-notes-convention.md. The org-wide adoption question is not this repo's to settle and lives in QuantEcon/QuantEcon.manual#103.