Files

T

Brummel 93887aa03b workflow: replace docs/roadmap.md with Gitea issue backlog

The forward queue moves out of the in-tree markdown file and into
Gitea issues at http://192.168.178.103:3000/Brummel/AILang/issues.
Labels: kind:{milestone,feature,todo,idea} + prio:{p1,p2,p3}
+ state:in-progress. Big chunks live as Gitea milestones
(containers) with full prose in the description; smaller items are
standalone issues. Browse-and-filter scales constant against
growing item count; the previous markdown file was 1059 lines, of
which ~850 were already-closed-entry verlauf (the same failure
class the JOURNAL cut removed).

Sync-drift Code<>Tracker mitigation: Soft-convention `closes #N`
/ `refs #N` in commit bodies — Gitea auto-closes the issue on
push. Captured in user-level CLAUDE.md (~/.claude/CLAUDE.md, not
in this commit) as the durable rule; no hook enforcement.

In-repo changes:

- docs/roadmap.md deleted.
- CLAUDE.md (project): Code-layout drops roadmap; /boss gating
  retargeted; Roles section rewritten with a new "Gitea issues"
  bullet (URL + tea-CLI snippet) and the closes-#N trailer note.
- skills/boss/SKILL.md: 10 sites retargeted, plus Step 1 now
  prescribes `tea issues ls --labels prio:p1` as the queue read.
- skills/brainstorm/SKILL.md: Step 7.5 no-override BLOCK now
  files a Gitea issue via `tea issues create` instead of
  appending a roadmap entry; spec deletion stays.
- skills/audit/SKILL.md + ailang-architect.md: deferral
  requirement and debt-heuristic retargeted; forward-intent
  belongs in the Gitea backlog.
- skills/fieldtest/SKILL.md, skills/docwriter/SKILL.md +
  ailang-docwriter.md: roadmap → backlog.
- design/contracts/honesty-rule.md: forward intent lives in
  the Gitea backlog (pinned phrases unchanged).
- design/INDEX.md: Docs bullet drops roadmap, adds the backlog
  URL.
- crates/ailang-core/tests/docs_honesty_pin.rs: two assert
  messages retargeted (assertion bodies unchanged).
- bench/architect_sweeps.sh: Sweep-4 TABU extended with
  `docs/roadmap\.md` so the deleted path cannot quietly regrow
  as a cross-reference in design/contracts/.

Verification:

- cargo build --workspace clean.
- cargo test --workspace: 647 passed, 0 failed, 2 ignored.
- bench/architect_sweeps.sh exit 0 (all five sweeps clean, incl.
  new TABU).
- grep over the live tree (excluding docs/specs/, docs/plans/)
  shows zero residual docs/roadmap.md refs.

Not touched: ~55 historical files under docs/specs/ and
docs/plans/ that mention docs/roadmap.md. Snapshot-character,
analogous to the JOURNAL-cut precedent — historical specs are
not mass-edited just because a live file was retired; their
mentions were correct at write time.

2026-05-20 14:48:27 +02:00

3.8 KiB

Raw Blame History

name, description

name	description
docwriter	Use when the API surface of one or more crates has stabilized across recent milestones and rustdoc lag is suspected (cargo doc --no-deps shows accumulated warnings, or a newcomer would not be able to navigate the crate from `cargo doc --open` without the design/ ledger). NOT a per-milestone step; Boss-dispatched only, after audit closes clean and after any pending fieldtest has run.

docwriter — post-stability rustdoc sweep

Violating the letter of these rules is violating the spirit.

Overview

Rustdoc rots silently. Every iteration changes APIs and module boundaries; doc comments lag. Running this sweep per-milestone is waste — documenting an item that gets renamed two iterations later just burns context. The right moment is post-stability: after a stretch of milestones in which the surface in question has held still. This skill is the third bucket in the cadence taxonomy (per-milestone-mandatory audit; Boss-judgment post-audit fieldtest; Boss-judgment post-fieldtest docwriter), and it fires on Boss judgment, never on a milestone clock.

When to Use / Skipping

Boss-dispatched only. Audit closing does not trigger docwriter. Trigger conditions are any of:

cargo doc --no-deps 2>&1 shows accumulated warnings across multiple crates after a stability window of several milestones.
A backlog issue like "Rustdoc warning sweep" has matured — the surface it targets has not moved for a while.
Onboarding-readability check: navigating cargo doc --open for a crate is not self-supporting without the design/ ledger.

Skipping is the default. The skill only runs when the orchestrator positively decides the surface is stable enough to document. If the code still feels like it might get rewritten, do not dispatch — wait.

The Iron Law

DOCWRITER IS POST-STABILITY, NOT PER-MILESTONE.
NO API CHANGES — DOCS ONLY.
IF THE CODE STILL FEELS LIKE IT MIGHT GET REWRITTEN, DON'T DOCUMENT IT YET.

Dispatch

The orchestrator dispatches ailang-docwriter with crate_scope, warning_target, and optional priority_items. The agent carries the substantive rules — crate-root vs. module-root vs. item docs, intra-doc link conventions, the verification triple. This SKILL.md only governs trigger and dispatch; the agent file governs the work.

Handoff Contract

docwriter consumes (from orchestrator):

Field	Content
`crate_scope`	Crate name(s) to document, or `all`
`warning_target`	Specific rustdoc warnings to clear, or `all`
`priority_items`	Optional: items the orchestrator wants documented first

docwriter produces:

Field	Content
`status`	`DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`
`files_touched`	paths + which level (crate / module / item docs)
`warnings_cleared`	count, plus the rustdoc check status
`findings`	items whose names or behaviour seemed confusing while documenting them (one line each, no prescriptions)

The orchestrator decides whether findings become a follow-up iteration; docwriter does not self-resolve.

Cross-references

Agent dispatched: skills/docwriter/agents/ailang-docwriter.md — carries the documentation rules, hard limits, verification triple, Common Rationalisations, and Red Flags.
Pre-condition (upstream): skills/audit/SKILL.md must have closed clean (or with ratify-d drift only). Docwriter does not run on a milestone with open drift.
Pre-condition (upstream, conditional): skills/fieldtest/SKILL.md — if a fieldtest is pending for the surface in scope, run it first. Fieldtest can surface bugs or architecture problems that would invalidate the doc work.
Hand-off target: orchestrator (me). Findings flow into the Gitea backlog as candidates for a follow-up tidy iteration.

3.8 KiB Raw Blame History