Follow-up docs pass after the stream: reconcile docs/ against what shipped, once main stops moving #1013

New issue

Open

opened 2026-08-19 01:52:35 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-19 01:52:35 +00:00

Member

The second half of #1011, deliberately separated because it should happen at a defined point after the freeze lifts rather than continuously.

#1011 covers the inline: always skill prose, where a wrong sentence is in the model's prompt every turn and therefore urgent. This covers docs/, where a wrong sentence misleads a person instead. Lower stakes, larger surface: 40 pages.

Why this waits rather than happening now

On 2026-08-18 between roughly 20:00Z and 02:00Z, main took at least eight merges touching this material: #985, #997, #999, #1001, #1003, #1004, #1005, plus coilyco-bridge/deploy#683. During one single-commit rebase it moved four times.

Documenting a surface while several seats are actively reshaping it produces prose that is stale before it lands. The freeze lifting on 2026-08-20 is the natural moment, because that is when the current burst stops and what shipped becomes stable enough to describe.

Known drift, found while working on other things

Not an audit. These turned up incidentally and are the seed list.

The six-rounds number appears in four independent places, two of them docs: docs/sirens-echo-tools.md:20 ("more than six rounds") and docs/sirens-echo-rate.md:31 ("plus up to six tool rounds"), alongside the two capability.md copies #1011 covers. internal/community/config.go owns that value and the Dowel definition overrides it to 12. Four copies of one tunable, none of which knows about the override.
Dowel is absent from docs/. Exactly 1 of 40 pages mentions the lane at all (docs/sirens-echo-http.md), while the lane is the thing that went on camera. Its Moxn write surface, its /publish boundary, its telemetry pinning, and its skill roots are documented only in skill prose and in coilyco-bridge.
docs/sirens-echo-eval.md documents eval-deep and board-deep and no Dowel equivalent, which matches reality — scripts/task.sh has no board-dowel and agents/dowel/ holds only an empty evaluations/. So the doc is accurate today and becomes wrong the moment the Dowel board is wired. Worth updating in the same pass rather than separately.
docs/sirens-echo-tool-markup.md describes the Temporal mirror as "Deep only", a deployment choice made by which lane sets the variables. sirens-dowel-values.yaml sets all three of SIRENS_ECHO_TEMPORAL_HOST, ..._NAMESPACE, and ..._TASK_QUEUE, and the workflow id prefix is still sirens-deep-trajectory-. Worth confirming which half is stale.

What the pass should produce

Each of the 40 pages either verified against the shipped code and configuration, or edited, or explicitly marked as describing a lane that no longer exists.
Every restated tunable replaced with a pointer to the file that owns it, per the estate rule that a tunable lives in one owning source.
The Dowel lane documented to the standard Echo and Deep already meet, since it is the lane with the most unusual configuration and the least written down.
Anything genuinely uncertain recorded as a question on an issue rather than guessed into prose.

Scope

Documentation only. No behaviour, no configuration, no capability surface. It should not start before the freeze lifts on 2026-08-20, and it should be one pass with a defined end rather than an ongoing task.

Refs #1011, #929, #981

The second half of #1011, deliberately separated because it should happen at a **defined point after the freeze lifts** rather than continuously. #1011 covers the `inline: always` skill prose, where a wrong sentence is in the model's prompt every turn and therefore urgent. This covers `docs/`, where a wrong sentence misleads a person instead. Lower stakes, larger surface: **40 pages.** ## Why this waits rather than happening now On 2026-08-18 between roughly 20:00Z and 02:00Z, `main` took at least eight merges touching this material: #985, #997, #999, #1001, #1003, #1004, #1005, plus `coilyco-bridge/deploy#683`. During one single-commit rebase it moved four times. Documenting a surface while several seats are actively reshaping it produces prose that is stale before it lands. **The freeze lifting on 2026-08-20 is the natural moment**, because that is when the current burst stops and what shipped becomes stable enough to describe. ## Known drift, found while working on other things Not an audit. These turned up incidentally and are the seed list. * **The six-rounds number appears in four independent places**, two of them docs: `docs/sirens-echo-tools.md:20` ("more than six rounds") and `docs/sirens-echo-rate.md:31` ("plus up to six tool rounds"), alongside the two `capability.md` copies #1011 covers. `internal/community/config.go` owns that value and the Dowel definition overrides it to 12. Four copies of one tunable, none of which knows about the override. * **Dowel is absent from `docs/`.** Exactly **1 of 40** pages mentions the lane at all (`docs/sirens-echo-http.md`), while the lane is the thing that went on camera. Its Moxn write surface, its `/publish` boundary, its telemetry pinning, and its skill roots are documented only in skill prose and in `coilyco-bridge`. * **`docs/sirens-echo-eval.md` documents `eval-deep` and `board-deep` and no Dowel equivalent**, which matches reality — `scripts/task.sh` has no `board-dowel` and `agents/dowel/` holds only an empty `evaluations/`. So the doc is accurate today and becomes wrong the moment the Dowel board is wired. Worth updating in the same pass rather than separately. * **`docs/sirens-echo-tool-markup.md` describes the Temporal mirror as "Deep only"**, a deployment choice made by which lane sets the variables. `sirens-dowel-values.yaml` sets all three of `SIRENS_ECHO_TEMPORAL_HOST`, `..._NAMESPACE`, and `..._TASK_QUEUE`, and the workflow id prefix is still `sirens-deep-trajectory-`. Worth confirming which half is stale. ## What the pass should produce * Each of the 40 pages either verified against the shipped code and configuration, or edited, or explicitly marked as describing a lane that no longer exists. * Every restated tunable replaced with a pointer to the file that owns it, per the estate rule that a tunable lives in one owning source. * The Dowel lane documented to the standard Echo and Deep already meet, since it is the lane with the most unusual configuration and the least written down. * Anything genuinely uncertain recorded as a question on an issue rather than guessed into prose. ## Scope Documentation only. No behaviour, no configuration, no capability surface. It should not start before the freeze lifts on 2026-08-20, and it should be one pass with a defined end rather than an ongoing task. Refs #1011, #929, #981

coilyco-ops added the

labels

2026-08-19 03:38:52 +00:00