polish batch, run 16: jargon-audit (internal hostnames, cross-repo bare refs, unlinked insider tools) #449

New issue

Closed

opened 2026-07-01 21:59:11 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-07-01 21:59:11 +00:00

Member

Why

Non-gating jargon walls from a github-only-dev/jargon-audit pass, batched per sweep rules. The headline jargon findings were already filed by a parallel run (#444: README lore + bare refs; #446: refs wrong off-remote — both +1'd); these are the instances that class of fix does not cover:

Internal hostnames as load-bearing doc content. agent-observability.md names the telemetry sink as http://ser8:4318/v1/logs; agent-ts-sidecar.md builds its whole example around kai-tower-3026:11434 (a personal machine) and the mac-proxy tailnet node. A stranger cannot decode these, and they read as "this doc is for the author's house, not for me." Replace with placeholders (<your-signoz-host>, <ollama-host>) or name them via the env vars that already exist (WARD_AGENT_TELEMETRY_ENDPOINT, WARD_TOWER_OLLAMA).
Cross-repo bare refs with no host context. fleet-local.md cites "aos#310 §5" and "cli-guard#178"; FEATURES.md says "the stable read surface aos reads". ward#NNN at least names this repo; aos#NNN requires already knowing aos = agentic-os and which forge it lives on (it's on GitHub while ward is on Forgejo). The footer's "cross-reference convention" link doesn't explain the shorthand map. Add one legend line (aos = coilysiren/agentic-os on GitHub, cli-guard = coilyco-flight-deck/cli-guard here) wherever the convention footer appears, or expand refs to full URLs in public-facing docs.
Insider tool names dropped without links: "Point Dozzle / jq at it" (agent-observability.md), "the fleet's Warp secret-redaction" — one-word link each, or drop.

Deliverable / Done condition

Each checkbox independently fixable; done when all three are checked.

Severity: polish · persona: github-only-dev · angle: jargon-audit
Filed by Claude Code during a cold-read release pressure test (run 16).

## Why Non-gating jargon walls from a `github-only-dev`/`jargon-audit` pass, batched per sweep rules. The headline jargon findings were already filed by a parallel run (#444: README lore + bare refs; #446: refs wrong off-remote — both +1'd); these are the instances that class of fix does not cover: - [ ] **Internal hostnames as load-bearing doc content.** agent-observability.md names the telemetry sink as `http://ser8:4318/v1/logs`; agent-ts-sidecar.md builds its whole example around `kai-tower-3026:11434` (a personal machine) and the `mac-proxy` tailnet node. A stranger cannot decode these, and they read as "this doc is for the author's house, not for me." Replace with placeholders (`<your-signoz-host>`, `<ollama-host>`) or name them via the env vars that already exist (`WARD_AGENT_TELEMETRY_ENDPOINT`, `WARD_TOWER_OLLAMA`). - [ ] **Cross-repo bare refs with no host context.** fleet-local.md cites "aos#310 §5" and "cli-guard#178"; FEATURES.md says "the stable read surface aos reads". `ward#NNN` at least names this repo; `aos#NNN` requires already knowing aos = agentic-os *and* which forge it lives on (it's on GitHub while ward is on Forgejo). The footer's "cross-reference convention" link doesn't explain the shorthand map. Add one legend line (aos = coilysiren/agentic-os on GitHub, cli-guard = coilyco-flight-deck/cli-guard here) wherever the convention footer appears, or expand refs to full URLs in public-facing docs. - [ ] **Insider tool names dropped without links**: "Point Dozzle / jq at it" (agent-observability.md), "the fleet's Warp secret-redaction" — one-word link each, or drop. ## Deliverable / Done condition Each checkbox independently fixable; done when all three are checked. --- **Severity: polish** · persona: github-only-dev · angle: jargon-audit Filed by Claude Code during a cold-read release pressure test (run 16).

coilyco-ops added the

pressure-test

label

2026-07-01 21:59:11 +00:00

coilyco-ops referenced this issue

2026-07-01 21:59:12 +00:00

every single hardcoded issue ref (ex ward#123) is wrong when you are on the wrong git remote #446

coilyco-ops referenced this issue

2026-07-01 21:59:13 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:35 +00:00

coilyco-ops added the

headless

labels

2026-07-01 23:30:28 +00:00

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilysiren referenced this issue

2026-07-02 07:10:55 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 08:06:27 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-449 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:06:25Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-449` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:06:25Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 08:20:34 +00:00

docs: decode insider jargon in cold-read docs (run 16 jargon-audit)

coilysiren closed this issue

2026-07-02 08:20:34 +00:00

coilysiren commented

2026-07-02 08:21:06 +00:00

Owner

WARD-OUTCOME: done - decoded the internal hostnames, insider tool names, and bare cross-repo refs the run-16 cold read flagged; landed on main as dbbe706.

Retro: this one was mostly a scoping problem dressed as a docs edit. The literal jargon swaps were trivial, but two things fought back. First, every doc I touched was pinned right at the 4000-char layout cap (several sat at 3990-3999 by design), so each [Dozzle](url) link I added had to be paid back with a meaning-preserving prose trim to stay under the gate - a fiddly balance-the-budget loop. Second, and more interesting: while I worked, the parallel ward#446 run landed a lint_issue_refs.py gate that had already rewritten the bare aos#N/cli-guard#N refs into full-URL links, which is exactly my checkbox 2 by another route. That surfaced as a rebase conflict and made me re-read main rather than trust my snapshot - the honest fix was to reset onto main and re-apply, leaving only the genuinely-uncovered residue (the bare word "aos", the hostnames, the tool names).

I deferred on mac-proxy/ward-tailnet: the issue flagged them as opaque, but they are load-bearing contract names the mechanism actually resolves, so a placeholder would make the doc wrong. I reframed them as fixed ansible-owned names instead of replacing them. Confident in the result - pre-commit (incl. the new refs gate) is green and the diff is small. One rough edge worth a follow-up: those four hostname docs are on the CONTRIBUTOR_DOCS cap-exemption list, and they are now a squeeze away from the cap; the ward#446 follow-up to trim provenance-ref noise so they fit WITH linked refs would give them breathing room.

WARD-OUTCOME: done - decoded the internal hostnames, insider tool names, and bare cross-repo refs the run-16 cold read flagged; landed on main as dbbe706. Retro: this one was mostly a scoping problem dressed as a docs edit. The literal jargon swaps were trivial, but two things fought back. First, every doc I touched was pinned right at the 4000-char layout cap (several sat at 3990-3999 by design), so each `[Dozzle](url)` link I added had to be paid back with a meaning-preserving prose trim to stay under the gate - a fiddly balance-the-budget loop. Second, and more interesting: while I worked, the parallel ward#446 run landed a `lint_issue_refs.py` gate that had already rewritten the bare `aos#N`/`cli-guard#N` refs into full-URL links, which is exactly my checkbox 2 by another route. That surfaced as a rebase conflict and made me re-read main rather than trust my snapshot - the honest fix was to reset onto main and re-apply, leaving only the genuinely-uncovered residue (the bare *word* "aos", the hostnames, the tool names). I deferred on `mac-proxy`/`ward-tailnet`: the issue flagged them as opaque, but they are load-bearing contract names the mechanism actually resolves, so a placeholder would make the doc wrong. I reframed them as fixed ansible-owned names instead of replacing them. Confident in the result - pre-commit (incl. the new refs gate) is green and the diff is small. One rough edge worth a follow-up: those four hostname docs are on the CONTRIBUTOR_DOCS cap-exemption list, and they are now a squeeze away from the cap; the ward#446 follow-up to trim provenance-ref noise so they fit WITH linked refs would give them breathing room.