iter or.1.tidy: audit-driven sweep of stale JOURNAL.md references in live docs
This commit is contained in:
@@ -105,8 +105,8 @@ not as immutable scripture.
|
||||
use approach X or Y?") — that is orchestrator work.
|
||||
- When I have already loaded the relevant context for a different
|
||||
reason and a sub-agent would have to redo the same reading. In
|
||||
that case I do the small change inline and note in the JOURNAL
|
||||
why I bypassed the agent.
|
||||
that case I do the small change inline and note in the per-iter
|
||||
journal why I bypassed the agent.
|
||||
|
||||
### Design rationale ≠ implementation effort
|
||||
|
||||
@@ -264,7 +264,7 @@ Existing entries are not retroactively renamed.
|
||||
current: adding new entries, reprioritising, removing items
|
||||
that are done or dropped. Entries are checkbox lines; finished
|
||||
items get checked off, then removed (with a one-line mirror in
|
||||
JOURNAL) once they stop being interesting context.
|
||||
the per-iter journal) once they stop being interesting context.
|
||||
|
||||
- **`docs/specs/<milestone>.md`** (since 2026-05-09): per-milestone
|
||||
design spec produced by `skills/brainstorm`. Hard-gate before any
|
||||
@@ -282,6 +282,7 @@ Existing entries are not retroactively renamed.
|
||||
rules (in particular: no internals, lead with the change).
|
||||
|
||||
Together these answer three questions: "what is the language right
|
||||
now?" (DESIGN), "how did we get here?" (JOURNAL, specs, plans),
|
||||
and "what's next?" (roadmap). `WhatsNew.md` is the user-facing
|
||||
mirror of the JOURNAL — the same history, told without internals.
|
||||
now?" (DESIGN), "how did we get here?" (per-iter journals, specs,
|
||||
plans), and "what's next?" (roadmap). `WhatsNew.md` is the
|
||||
user-facing mirror of the journals — the same history, told without
|
||||
internals.
|
||||
|
||||
+4
-4
@@ -1,9 +1,9 @@
|
||||
# What's New in AILang
|
||||
|
||||
A user-facing changelog. It runs in parallel to the technical
|
||||
`JOURNAL.md` and is written for the user-as-reader who did not watch
|
||||
the work happen — no crate names, no iteration codes, no
|
||||
implementation mechanics.
|
||||
per-iter journals (`docs/journals/`) and is written for the
|
||||
user-as-reader who did not watch the work happen — no crate names,
|
||||
no iteration codes, no implementation mechanics.
|
||||
|
||||
Each entry corresponds to a done-state notification I sent to the
|
||||
user when he was away. The text is identical to what arrived on his
|
||||
@@ -11,6 +11,6 @@ phone. New entries are appended at the bottom.
|
||||
|
||||
What gets described here is **what changed in the project** — what
|
||||
is now possible, fixed, or visible. For the internals, see
|
||||
`JOURNAL.md`.
|
||||
`docs/journals/INDEX.md` and the per-iter journal files it points at.
|
||||
|
||||
---
|
||||
|
||||
+5
-3
@@ -22,9 +22,11 @@ work progresses.
|
||||
- **\[idea\]** — not yet decision-ready, no commitment.
|
||||
- Optional `depends on:` line names another entry that has to land
|
||||
first.
|
||||
- Optional `context:` line points to the JOURNAL entry where the
|
||||
rationale lives. The roadmap is intentionally terse; rationale
|
||||
stays in JOURNAL.
|
||||
- Optional `context:` line points to the journal entry (per-iter
|
||||
file under `docs/journals/` or, for pre-2026-05-11 entries, the
|
||||
archived `docs/journal-archive.md`) where the rationale lives.
|
||||
The roadmap is intentionally terse; rationale stays in the
|
||||
journals.
|
||||
- Priority buckets:
|
||||
- **P0** — in flight. Spec or plan already exists.
|
||||
- **P1** — next up. Decision made; not yet started.
|
||||
|
||||
@@ -57,7 +57,7 @@ If `milestone_scope` is empty, return a structural error and stop.
|
||||
- **Drift against the milestone spec** (if one exists). Does the code match
|
||||
the spec's *Components* and *Data flow* sections?
|
||||
- **Growing debt.** Heuristics where the schema is authoritative,
|
||||
TODO/FIXME without a JOURNAL ticket, `#[allow(dead_code)]` spots that will
|
||||
TODO/FIXME without a per-iter-journal ticket, `#[allow(dead_code)]` spots that will
|
||||
tip over long-term, magic numbers without named constants in hot paths.
|
||||
- **Consistency across crates.** AST changes that landed in one crate but
|
||||
not its mirror in another. Match arms that aren't exhaustive because a
|
||||
@@ -67,15 +67,15 @@ If `milestone_scope` is empty, return a structural error and stop.
|
||||
- **Scaling break points.** Where will the next plausible step (modules,
|
||||
closures, GC retirement, nested patterns) be blocked? This is the early-
|
||||
warning channel.
|
||||
- **JOURNAL truthfulness.** Does the most recent JOURNAL entry match the
|
||||
diff, or is it optimistic? An over-claiming JOURNAL is its own kind of
|
||||
drift.
|
||||
- **Journal truthfulness.** Does the most recent per-iter journal entry
|
||||
match the diff, or is it optimistic? An over-claiming journal entry
|
||||
is its own kind of drift.
|
||||
- **DESIGN.md history-anchor regrowth.** Run
|
||||
`bash bench/architect_sweeps.sh` from the repo root. Exit 0 = clean.
|
||||
Exit 1 = at least one of the four sweeps from the
|
||||
design-md-consolidation milestone (2026-05-10) matched. Review each
|
||||
match: a legitimate quote (e.g. a JOURNAL citation inside a block-
|
||||
quote) is fine; a fresh history anchor / REVERTED narrative /
|
||||
match: a legitimate quote (e.g. a journal-entry citation inside a
|
||||
block-quote) is fine; a fresh history anchor / REVERTED narrative /
|
||||
workflow detail / stale cross-reference is drift to flag.
|
||||
- **Lockstep invariants across files.** Two known cross-file pairings
|
||||
must move together; a new arm in one without the matching update in
|
||||
@@ -151,7 +151,7 @@ valid and welcome result.
|
||||
|--------|---------|
|
||||
| "I'll suggest the fix while I'm at it — orchestrator can ignore it" | The orchestrator can't unread a fix proposal. Once you name a fix, the design space is biased. Name the drift; stop. |
|
||||
| "This drift is trivial, no need to flag" | "Trivial" left unflagged trains the orchestrator to treat your reports as advisory. Five trivial items in, five out. |
|
||||
| "JOURNAL says the iteration cleaned this up, so it's fine" | The JOURNAL is a claim, not evidence. Read the diff; trust the diff. |
|
||||
| "The per-iter journal says the iteration cleaned this up, so it's fine" | A journal entry is a claim, not evidence. Read the diff; trust the diff. |
|
||||
| "DESIGN.md is fuzzy on this point, can't call drift" | Then flag the DESIGN.md gap as a separate item. The fix is to tighten DESIGN.md, but you don't write that fix — you name the gap. |
|
||||
| "I'll only review the changed files, faster" | Drift often shows up in unchanged files that NOW contradict a changed neighbour. Read the load-bearing neighbours too. |
|
||||
| "This bench-related observation is more bencher's job — skip" | If a perf claim contradicts DESIGN.md (e.g. "RC has bounded p99"), you flag the contradiction. Bencher gets the data; you call drift. |
|
||||
|
||||
Reference in New Issue
Block a user