kayg/calternal

Watch

Fork 0

DOCS: remove product names and explain collaboration document invariants #907

New issue

Open

opened 2026-10-02 17:39:13 +00:00 by kayg · 2 comments

kayg commented

2026-10-02 17:39:13 +00:00

Owner

Evidence

At the #863 audit base, a case-sensitive scan found 16 comment lines in 3 files under crates/calternal-collab/src that name common third-party products. Examples: markdown.rs:19 names Obsidian syntax; session.rs:114 and :155 name ProseMirror blocks.
The public-function scan found four functions without adjacent docs, including session.rs:746 (router) and :1284 (apply).

Owner rule

Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Describe the wiki-embed syntax and block identity rules directly. Document how the router and apply path preserve collaboration state. Keep the parser and session behavior unchanged.

Test idea

Run a source scan for product names and review docs against the existing markdown and collaboration tests. Do not change test expectations.

## Evidence At the #863 audit base, a case-sensitive scan found 16 comment lines in 3 files under `crates/calternal-collab/src` that name common third-party products. Examples: `markdown.rs:19` names Obsidian syntax; `session.rs:114` and `:155` name ProseMirror blocks. The public-function scan found four functions without adjacent docs, including `session.rs:746` (`router`) and `:1284` (`apply`). ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Describe the wiki-embed syntax and block identity rules directly. Document how the router and apply path preserve collaboration state. Keep the parser and session behavior unchanged. ## Test idea Run a source scan for product names and review docs against the existing markdown and collaboration tests. Do not change test expectations.

kayg referenced this issue

2026-10-02 17:44:36 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg commented

2026-10-02 17:49:19 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-collab. Explain room routing and single-apply agent turns. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 0b6b53b7f5032602193d83068c00c3b043b0407c.

Verification: cargo fmt --check exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file.

Files:

crates/calternal-collab/src/lib.rs
crates/calternal-collab/src/markdown.rs
crates/calternal-collab/src/session.rs
crates/calternal-collab/tests/hostile_clients.rs
crates/calternal-collab/tests/restart_epoch.rs
crates/calternal-collab/tests/wiki_embeds.rs

Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

Fixed the Rust comment findings in `crates/calternal-collab`. Explain room routing and single-apply agent turns. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `0b6b53b7f5032602193d83068c00c3b043b0407c`. Verification: `cargo fmt --check` exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file. Files: - `crates/calternal-collab/src/lib.rs` - `crates/calternal-collab/src/markdown.rs` - `crates/calternal-collab/src/session.rs` - `crates/calternal-collab/tests/hostile_clients.rs` - `crates/calternal-collab/tests/restart_epoch.rs` - `crates/calternal-collab/tests/wiki_embeds.rs` Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

kayg commented

2026-10-02 18:02:29 +00:00

Author

Owner

Rust comment fixes are complete on job/docsfix-rust. Final commit: a6d0f1be51d58ca6a28e9efa4a08d2a57924e9ae. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work.

docs: explain room routing and single-apply agent turns (#907)

All executable source and test expectations are unchanged. The final comparison against origin/dev confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments.

Gate: cargo fmt --check exited 0. Verbatim stdout and stderr are empty:

Files:

crates/calternal-collab/src/lib.rs
crates/calternal-collab/src/markdown.rs
crates/calternal-collab/src/session.rs
crates/calternal-collab/tests/hostile_clients.rs
crates/calternal-collab/tests/restart_epoch.rs
crates/calternal-collab/tests/wiki_embeds.rs

Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

Rust comment fixes are complete on `job/docsfix-rust`. Final commit: `a6d0f1be51d58ca6a28e9efa4a08d2a57924e9ae`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: explain room routing and single-apply agent turns (#907) All executable source and test expectations are unchanged. The final comparison against `origin/dev` confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments. Gate: `cargo fmt --check` exited 0. Verbatim stdout and stderr are empty: ```text ``` Files: - `crates/calternal-collab/src/lib.rs` - `crates/calternal-collab/src/markdown.rs` - `crates/calternal-collab/src/session.rs` - `crates/calternal-collab/tests/hostile_clients.rs` - `crates/calternal-collab/tests/restart_epoch.rs` - `crates/calternal-collab/tests/wiki_embeds.rs` Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

kayg referenced this issue

2026-10-02 18:02:42 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue from a commit

2026-10-02 18:10:46 +00:00

docs: explain room routing and single-apply agent turns (#907)

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#907

No description provided.

Rows
Columns