chore(tech-debt): strip historical narrative, delete dead docs by drewstone · Pull Request #12 · tangle-network/agent-runtime

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

drewstone · 2026-05-17T14:52:35Z

Summary

Tech-debt sweep on main. Scope limited to four categories per repo CLAUDE.md:

Historical-narrative comments removed. Across src/runtime-run.ts, src/trace-bridge.ts, src/sanitize.ts, src/chat-turn.ts, src/profile-conformance.ts, src/profile-conformance.test.ts, src/index.ts. Removed paragraphs about "replaces legal-agent's bespoke X", "Before this module, consumers hand-rolled Y", "chore: update Tangle agent packages #2 anti-pattern in the canonical audit", "the unified-union alternative was rejected because...", tax-agent file:line references, and "(NEW in 0.7.0)" markers. Replaced with current-state comments.
Docstring / README narrative. Same treatment on README.md and examples/runtime-run/{README.md,runtime-run.ts} — dropped legal-agent migration story and (NEW in 0.7.0) markers from the public-facing quickstart.
Dead docs deleted. Both files under docs/ had zero references in the source tree, in tests, in examples, in README, and in CI workflows:
- docs/domain-agent-runtime-integration-issues.md (165 lines) — issue drafts from when the GitHub connector returned 404; an artifact, not documentation.
- docs/product-runtime-kernel.md (326 lines) — completion record for the 0.5.0-0.5.2 release process; described historical scope, not current package state.
- Removed \"docs\" from package.jsonfiles array; the directory is gone.
No silent fallbacks introduced. The four existing catch blocks in the package were reviewed:
- src/run.ts:308,315 — preserves full diagnostic info into backend_error events; correct.
- src/chat-turn.ts:178 — already documents skipping non-JSON SSE sentinel lines per SSE spec; correct.
- src/backends.ts:297 — parses non-JSON SSE chunks as raw text deltas; behaviour relied on by 'parses OpenAI-compatible streamed chat completions' test. Left alone; not a silent default on a required field.

Held off

No new public exports.src/chat-turn.ts, src/intent-router.ts, src/profile-conformance.ts are not re-exported from src/index.ts, so the canonical substrate primitives the 0.8.0 release added are not reachable from @tangle-network/agent-runtime. Fixing this is additive (minor bump) and out of scope for a tech-debt sweep.
No algorithmic changes. Confined to comments, docstrings, dead-doc removal, and one package.json files-array tweak that follows from the doc deletion.

Verification

pnpm typecheck clean.
pnpm test — 6 files, 68 passing (unchanged from main).
pnpm build — esm + dts emit clean.

Net diff: 13 files changed, 66 insertions(+), 594 deletions(-).

Sweep removes commentary that describes what code used to do, what bug it replaces, or which audit found a pattern — per the CLAUDE.md doc discipline. Trims "(NEW in 0.7.0)" markers and legal-agent migration narrative from README and example docs. Deletes two orphan docs under docs/ that no source or doc references; both were point-in-time release/issue snapshots that no longer describe current state. - src/runtime-run.ts: drop "replaces legal-agent's bespoke..." paragraph from module doc; tighten complete() and randomSuffix comments. - src/trace-bridge.ts: drop "Before this module, consumers hand-rolled..." paragraph; reword tool_call args-omission and text_delta drop comments to describe current behaviour. - src/sanitize.ts: drop "the unified-union alternative was rejected because..." narrative on createRuntimeStreamEventCollector. - src/chat-turn.ts: drop "Caller pattern (replaces ~400 lines of legal/gtm/creative chat-runtime wrappers)" and tax-agent file:line reference; reword transport / fallback comments. - src/profile-conformance.ts: strip "from the canonical audit" / "#2 anti-pattern in the canonical audit" from issue messages and reword system-prompt-too-short message; trim docstring. - src/profile-conformance.test.ts: rename "the gtm-agent anti-pattern audit-found is caught" -> describes current behaviour; same for the describe block + shell-cap test. - src/index.ts: drop "(compat surface)" and "(new in 0.7.0)" section banners. - README.md: drop "(NEW in 0.7.0)" markers from quickstart table and section headers; drop legal-agent migration narrative. - examples/runtime-run: same treatment in README + .ts header. - docs/domain-agent-runtime-integration-issues.md: deleted (165 lines of issue drafts referencing "GitHub connector returns 404"; zero references in tree). - docs/product-runtime-kernel.md: deleted (326-line completion record for 0.5.0-0.5.2 release process; zero references in tree). - package.json: drop "docs" from files (directory is gone). Verification: pnpm typecheck, pnpm test (68 passing, unchanged), pnpm build all pass.

tangletools force-pushed the chore/tech-debt-sweep branch from ddbb5fe to 28968bfCompare May 17, 2026 14:54

drewstone merged commit 1d94b05 into mainMay 17, 2026
1 check failed

drewstone mentioned this pull request Aug 20, 2026
feat(improvement): converge on one measured proposal-to-activation path #561
Closed
12 tasks