workflow: replace per-iter journal system with git log + BLOCKED.md
The per-iter journal under docs/journals/ duplicated the iter commit body's substance and accumulated as Verlauf-Doku with no Future-Use. Sweep across all live control documents: CLAUDE.md, the 7 SKILL.md files, the 11 agent files, design/INDEX.md and the contracts/models that referenced journals, docs/roadmap.md, and the handful of source comments + tests that pointed at journal files for rationale. Mechanism changes: - Standing-reading-lists in every agent now read `git log -N --format=full` for recent project state, never per-iter journal files. The architect reads `git log <prev-milestone-close>..HEAD --format=full` for audit scope. - implement-orchestrator no longer writes a journal file. DONE outcomes emit just code + stats; the end-report is the per-task summary the Boss uses to write the commit body. PARTIAL/BLOCKED outcomes emit BLOCKED.md at the repo root — uncommitted by convention, Boss removes on repair or discard. New iron-law line + four-rationalisation row + red-flag bullet codify it. - audit ratify mechanic: --update-baseline is now paired with an explicit ratify paragraph in the audit-close commit body, not a separate JOURNAL ratify entry. - design/contracts/honesty-rule.md: "history and rationale lives in docs/journals/" → "lives in git log (iter and audit commit bodies)". Pinned phrase preserved verbatim. - CLAUDE.md "Roles of …" section reframed: design/, git log, journal-archive.md (content-frozen), roadmap.md, specs/, plans/. No docs/journals/ slot anymore. - roadmap.md context-lines that pointed at per-iter journals are dropped where the spec/commit already carries the rationale, or rephrased to "shipped in the <iter> iter commit" / "docs/journal- archive.md (<date> entry)" for pre-2026-05-11 references. What stays (this commit): - docs/journals/ directory and contents are NOT touched. Removing the contents is a separate follow-up. - docs/journals/2026-05-19-design-decision-records.md still has live readers (docs_honesty_pin.rs Z 108 + parse.rs + duplicate_ctor_pin.rs + 3 roadmap mentions) — also follow-up. - docs/journal-archive.md still exists; its self-pointer header has been updated to drop the "see docs/journals/INDEX.md" mention. Workspace builds, full test suite green.
This commit is contained in:
@@ -43,7 +43,7 @@ it measurably improves correctness or removes redundancy.
|
||||
| `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios |
|
||||
| `examples/` | AILang fixtures used by tests and benches |
|
||||
| `design/` | The canonical contract ledger — `design/INDEX.md` (sole addressable spine: a typed Contracts + Models table), `design/contracts/` (prose-authoritative test-linked invariants), `design/models/` (onboarding whitepapers) |
|
||||
| `docs/` | Specs and decisions log — `docs/journals/` (per-iter journals + `INDEX.md`; incl. the migrated design decision-records), `docs/journal-archive.md` (pre-2026-05-11 history), `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` |
|
||||
| `docs/` | Specs and roadmap — `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `docs/roadmap.md` (forward queue), `docs/journal-archive.md` (pre-2026-05-11 history, content-frozen), `PROSE_ROUNDTRIP.md`. Per-iter history lives in `git log`. |
|
||||
| `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. |
|
||||
|
||||
## Skill system
|
||||
@@ -75,8 +75,8 @@ See @skills/README.md for the skill + agent roster.
|
||||
### What this means in practice
|
||||
|
||||
- **Plan, design, decide** — myself. Architectural choices, scope,
|
||||
invariants, and the contents of `docs/journals/` and the
|
||||
`design/` ledger are my work product.
|
||||
invariants, commit bodies, and the contents of the `design/`
|
||||
ledger are my work product.
|
||||
- **Implement, refactor, write tests, diagnose bugs** — by default,
|
||||
delegated. `ailang-implementer` for code changes that follow a
|
||||
fixed design, `ailang-tester` for E2E coverage, `ailang-debugger`
|
||||
@@ -97,12 +97,14 @@ Two project-wide rules govern who touches git history and how:
|
||||
brainstormer, planner, debugger, fieldtester, docwriter,
|
||||
architect, bencher — runs `git commit`. Every agent writes its
|
||||
output (spec, plan, code, tests, fixtures, rustdoc edits, RED
|
||||
tests, journal files, stats, updated baselines) into the working
|
||||
tree as unstaged changes. I inspect the result with
|
||||
`git status` / `git diff`, decide commit shape (often one
|
||||
cohesive iter-level commit; sometimes a few logical commits when
|
||||
the changes genuinely cover separate concerns), and commit.
|
||||
Per-task or per-phase commits are not a goal in themselves.
|
||||
tests, stats, updated baselines; `BLOCKED.md` on PARTIAL/BLOCKED
|
||||
iter outcomes) into the working tree as unstaged changes. I
|
||||
inspect the result with `git status` / `git diff`, decide commit
|
||||
shape (often one cohesive iter-level commit; sometimes a few
|
||||
logical commits when the changes genuinely cover separate
|
||||
concerns), and commit. Per-task or per-phase commits are not a
|
||||
goal in themselves. `BLOCKED.md` is never committed by
|
||||
convention — Boss removes it on repair or discard.
|
||||
- **main HEAD is sacrosanct.** Nobody (including me) runs
|
||||
`git reset` or `git revert` on main. main moves forward only via
|
||||
my commits. The consequence is the working-tree-as-quarantine
|
||||
@@ -114,8 +116,7 @@ Two project-wide rules govern who touches git history and how:
|
||||
|
||||
These rules supersede earlier mechanics that involved per-iter
|
||||
branches and per-task agent commits. See `skills/README.md`
|
||||
"Conventions" for the same rules in skill-system form, and the
|
||||
2026-05-11 journal for the failure mode that motivated the change.
|
||||
"Conventions" for the same rules in skill-system form.
|
||||
|
||||
### Authority over `skills/` and the agent roster
|
||||
|
||||
@@ -145,8 +146,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 per-iter
|
||||
journal why I bypassed the agent.
|
||||
that case I do the small change inline and note in the commit
|
||||
body why I bypassed the agent.
|
||||
|
||||
### Design rationale ≠ implementation effort
|
||||
|
||||
@@ -167,8 +168,7 @@ equally, and even then it should be named as a tiebreaker, not as
|
||||
the primary reason. The 18a "Type::Fn metadata vs. Type variant"
|
||||
call is the canonical anti-example: the right reason was semantic
|
||||
locality (modes belong to fn-parameter positions, not to types in
|
||||
general), and I retroactively had to add it. JOURNAL entries from
|
||||
2026-05-08 record the lesson.
|
||||
general), and I retroactively had to add it.
|
||||
|
||||
### Feature acceptance: LLM utility
|
||||
|
||||
@@ -193,11 +193,12 @@ Work clusters into **milestones**, each subdivided into
|
||||
→ fieldtest`), skipping rules, and bench-exit-code gating live in
|
||||
`skills/README.md` and the per-skill `SKILL.md` files.
|
||||
|
||||
Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use
|
||||
"iter" / "family"; new entries use "iteration" / "milestone".
|
||||
Existing entries are not retroactively renamed.
|
||||
Vocabulary note: legacy entries in `docs/journal-archive.md`
|
||||
(pre-2026-05-09) use "iter" / "family"; current vocabulary is
|
||||
"iteration" / "milestone". Existing archive entries are not
|
||||
retroactively renamed.
|
||||
|
||||
## Roles of the `design/` ledger, `docs/journals/`, `docs/journal-archive.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/`
|
||||
## Roles of the `design/` ledger, `git log`, `docs/journal-archive.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/`
|
||||
|
||||
- **The `design/` ledger** is the canonical specification. It
|
||||
describes what AILang *is*: schema, semantics, invariants, runtime
|
||||
@@ -209,18 +210,17 @@ Existing entries are not retroactively renamed.
|
||||
feature requires changes to a contract, those changes are part of
|
||||
the same iteration. The `design/` ledger is also the artefact
|
||||
`ailang-architect` checks the code against during drift review.
|
||||
The current-state-mirror discipline is unchanged, just re-homed:
|
||||
a contract describes only the actual present state; forward intent
|
||||
goes to `docs/roadmap.md`, history and rationale to
|
||||
`docs/journals/` (see `design/contracts/honesty-rule.md`).
|
||||
A contract describes only the actual present state; forward intent
|
||||
goes to `docs/roadmap.md`, history and rationale to `git log`
|
||||
(see `design/contracts/honesty-rule.md`).
|
||||
|
||||
- **`docs/journals/<YYYY-MM-DD>-iter-<id>.md`** is the decisions
|
||||
log, one file per iter. Each file records *why* the iter moved
|
||||
the way it did — alternatives considered and rejected, lessons,
|
||||
rationale that does not belong in the `design/` ledger. Append-only
|
||||
per file; new files are appended via `docs/journals/INDEX.md`.
|
||||
`docs/journals/INDEX.md` is the chronological pointer list,
|
||||
orchestrator-maintained, one line per iter.
|
||||
- **`git log`** is the project history. Iter and audit commit
|
||||
bodies carry the *why* — alternatives considered and rejected,
|
||||
verification steps, ratify statements, lessons. The Boss writes
|
||||
these bodies at commit time; they are the durable record. Read
|
||||
recent state with `git log -5 --format=full`; chronological scan
|
||||
with `git log --oneline -30`; per-milestone scope with
|
||||
`git log <prev-milestone-close>..HEAD --format=full`.
|
||||
|
||||
- **`docs/journal-archive.md`** is the archived monolithic
|
||||
decisions log for everything pre-2026-05-11. Content-frozen.
|
||||
@@ -231,8 +231,8 @@ Existing entries are not retroactively renamed.
|
||||
orchestrator owns this file and is responsible for keeping it
|
||||
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
|
||||
the per-iter journal) once they stop being interesting context.
|
||||
items get checked off, then removed 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
|
||||
@@ -243,5 +243,6 @@ Existing entries are not retroactively renamed.
|
||||
by `skills/implement`.
|
||||
|
||||
Together these answer three questions: "what is the language right
|
||||
now?" (the `design/` ledger), "how did we get here?" (per-iter
|
||||
journals, specs, plans), and "what's next?" (roadmap).
|
||||
now?" (the `design/` ledger), "how did we get here?" (`git log`,
|
||||
plus `docs/journal-archive.md` for pre-2026-05-11 context), and
|
||||
"what's next?" (roadmap).
|
||||
|
||||
Reference in New Issue
Block a user