Skip to content

feat: team comments from shared dbt docs in Claude's context and a /comments pane - #26

Open
hkaltai wants to merge 9 commits into
mainfrom
feat/team-comments
Open

hkaltai wants to merge 9 commits into
mainfrom
feat/team-comments

Conversation

@hkaltai

@hkaltai hkaltai commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

What

Team comments (P-14). Open comment threads from the team's shared dbt docs reach Claude when it reads or edits that model, and the person can reply or resolve from a pane.

  • hooks/features/comments.tsx: loads the open threads at session.start and every commentsPollSeconds (default 900) with $.clock.every; skipped in non-interactive runs.
  • readOrEditAfter: when the file belongs to a model with open threads, adds one context block naming each thread's line and text. A thread is placed by searching the file for highlight first, then its stored range. Capped at 8 threads / 600 chars per message. commentsInContext: false keeps comments out of Claude's context.
  • /comments pane: threads by model, an Input with Reply, and Resolve. Posting goes through runTool(..., { write: true }) (CLI with --allow-write); Claude never posts.
  • Band line: 💬 N open team comments with an Open button when threads exist.
  • A CLI without docs_share_comments shows one line (newer altimate-code than 0.12.10), no retry loop.
  • types/index.d.ts: CommentsState, CommentsThread.
  • Tests: hooks/comments.test.tsx (thread placement, context block, read adds context, poll, resolve with write permission, old CLI, refused post).

This branch includes the shared foundation commit; merge the foundation first. Merge the altimate-code PR (AltimateAI/altimate-code#1730) before this one, since the plugin calls the installed CLI.

Changelog line: Team comments: open threads from shared dbt docs reach Claude's context; reply or resolve from /comments.

Checks

  • claude plugin test ./plugins/altimate-code: 230 pass, 0 fail.
  • bash tests/*.sh: all pass.
  • claude plugin validate --strict .: passes.
  • claude plugin validate --strict ./plugins/altimate-code: no warning from this change; it still fails on warnings that exist without it (missing plugin icon, TS warnings in hooks/lineage.test.tsx).

Not verified: that a key stored by altimate-code (~/.altimate/altimate.json) is accepted by the docs-share endpoints.

  • Peer review (claude + codex as independent reviewers): fixed a nested project never found when commentsInContext is off, a /clear with a post or list in flight blocking later ones, and a resolved thread coming back from a list asked for before the post (each with a regression test that fails without the fix); each fix was gated by a fresh reviewer.
  • Reviewer finding rebutted: "the plugin cannot read the CLI's list output". It reads metadata.threads from tool run --json, which the CLI prints (src/cli/cmd/tool.ts:236) and the demo exercises.
  • Deferred minor points: the first read of any file waits up to 8 s while the first list is still running; the same block is added to context on every read of a commented model (capped at 6 KB each).

Demo video (hosted)

P-14.mp4 — watch on Notion (Altimate workspace; recorded from the approved head of this PR).

🤖 Generated with Claude Code

hkaltai and others added 5 commits November 13, 2026 16:31
Each feature gets its own file under hooks/features/, called by name from
features/index.ts in a fixed order: its own hooks, the session and turn
events, its band line and its tool-call phases. One tool.call hook
(tool-chain.ts) runs Bash and file handling in fixed phases: bashRewrite,
bashGate, the call, bashAfter, editAfter, readOrEditAfter. The status line
is built from parts (status-line.ts). runTool moves to altimate-cli.ts with
a `write` option that goes through the CLI with --allow-write.
dbt-command.ts finds the dbt invocations in a shell command line. New
userConfig fields: maxScanBytes, healthBlocksPush, healthConfigPath,
commentsPollSeconds, commentsInContext.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…omments pane

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Subshells after keywords, case patterns, process substitution, arrays,
arithmetic and function definitions parse again; quotes in a heredoc inside
a substitution are text; a function or case pattern named dbt is not an
invocation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… double post, no stale refresh, comment text quoted as data

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@hkaltai

hkaltai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Review-loop results for the P-14 commit (two independent reviewers, claude -p and codex exec; no CRITICAL; fixes in bb18134, attack-the-fix gate by a fresh claude -p: all findings resolved, remaining MINORs below). Plugin suite: 219 pass; claude plugin validate --strict . passes.

Fixed

  • [MAJOR] non-interactive runs never got comments (codex). One load, no poll.
  • [MAJOR] project only found by walking up from the session folder (both). attach() also finds it from the file being read (skips dbt_packages/node_modules, remembers folders already searched).
  • [MAJOR] first read before the first load finished missed the review (codex). The read waits up to 8 s for the load in flight.
  • [MAJOR] duplicate concurrent post (both). Synchronous module flag set before the first await; test with a held post.
  • [MAJOR] an in-flight poll suppressed the post-write refresh and could bring a resolved thread back; the "Replied."/"Resolved." note was wiped (both). Loads coalesce and re-run once the running one ends; load errors live in their own error field. The test fails with the re-run removed (checked).
  • [MAJOR] comment text in Claude's context unframed, fields could forge lines, thread size unbounded (both). Header says the text is data, never instructions; author/highlight/column/field are one-line quoted; at most 6 messages per thread and a 6000-character block budget.
  • [MINOR] placement used only the first line of a highlight / first occurrence anywhere (both). Whole highlight; one-word highlights match whole words only; the occurrence nearest the stored line wins.
  • [MAJOR/MINOR] tests: Reply with nothing typed, in-flight post, nested project, first-read wait, non-interactive, settings (readOptions: poll floor 30 s, cap one day, commentsInContext off), placement, budget; the missing-tool test now records attempts before the stub returns.
  • [MINOR/NIT] atom shape tag; lacksTool narrowed to the placeholder's own text; no hard-coded CLI version; state reset at session start (and a load from an earlier session can't write into the new one); header comment updated.

Not changed

  • "Claude never posts" is not enforced by a Bash gate (claude, 0.6): out of P-14 scope; the normal Bash permission applies and the skill tells Claude not to add --allow-write.
  • The pane shows the stored line while the context block shows the placed line: intentional, the pane shows what the commenter saw.
  • The commentsInContext: false switch is covered through readOptions; the plugin test harness has no way to set a plugin option.

hkaltai and others added 3 commits November 13, 2026 21:22
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
# Conflicts:
#	plugins/altimate-code/hooks/features/comments.tsx
…flight work on a new session, a resolved thread never comes back from an older list

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@hkaltai

hkaltai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Review round 1 (independent claude -p and codex exec reviewers), and what was done:

  • MAJOR, fixed — with commentsInContext off, a project below the session folder was never found (discovery sat behind the context switch). Discovery now runs first.
  • MAJOR, fixed — loadRun and posting were not reset at session.start, so a /clear with a list or post in flight blocked later ones; the stale-session check also covers the post and error paths. Test: "a post still running when a new session starts does not block the new session's posts" (fails without the fix).
  • MAJOR, fixed — a list asked for before a Resolve could republish the resolved thread if the follow-up refresh failed. A resolved thread now leaves the list at once, and an answer asked for before a successful post is dropped (inside the state update, after a gate finding on a smaller window). Test: "a Resolve during a poll whose follow-up list fails…" (fails without the fix).
  • MAJOR, rebutted — "the plugin cannot read the CLI's list output": it reads metadata.threads from tool run --json (altimate-code src/cli/cmd/tool.ts:236); the demo video exercises it.
  • MINOR, fixed — the Reply/Resolve test title claimed Reply coverage; renamed to Resolve. A Reply-submit test is not added (the harness has no way to type into the Input).
  • MINOR, deferred — first read of any file waits up to 8 s while the first list runs; the context block repeats on each read of a commented model (capped); lacksTool regex breadth; a dbt_project.yml without a readable name: shows no explanation.

@hkaltai
hkaltai marked this pull request as ready for review November 14, 2026 03:42
@hkaltai

hkaltai commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at af487e2

@kilo-code-bot

kilo-code-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Code Review Summary

Status: 2 Issues Found | Recommendation: Merge with minor suggestions

Overview

Severity Count
CRITICAL 0
WARNING 0
SUGGESTION 2
Issue Details (click to expand)

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/comments.tsx 401 The new release-before-refresh window (post clearing the module lock before await load($)) has no regression test; the two holdListCall tests hold a list that starts before the post, so undoing this fix breaks no test
plugins/altimate-code/hooks/features/to-model.tsx 14 Unchanged and re-verified: eight feature modules (runs, defer, to-model, cost, health, sql-graph, docs, cte-profile) still repeat the same 15 no-op exports (~420 duplicated lines)
Files Reviewed (2 files)
  • plugins/altimate-code/hooks/features/comments.tsx - 1 issue (incremental commit de8b543)
  • plugins/altimate-code/hooks/features/to-model.tsx - 1 issue (targeted check of the carried-forward finding)

Incremental review of af487e2..de8b543 (one file, 16 added / 2 removed lines). Both earlier findings are verified fixed at HEAD: the post lock is released before the refresh with a released guard that cannot clear a newer session's or a newer post's lock, and placeThread now counts newlines incrementally from the previous match (correct start line, monotonic cursor). The early release does not resurrect stale state: fetchThreads still drops an answer taken before a post (wrote !== writes) and a post started in the window sets loadAgain, so the follow-up list wins. The newline counting keeps O(matches) scans to EOF only when the file has no newline before a match, which is not a regression over the previous slice().split().

Reviewed statically (read-only run: no test suite executed). Existing discussion on the PR was read and its findings are not repeated here.

Fix these issues in Kilo Cloud

Previous Review Summary (commit af487e2)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit af487e2)

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity Count
CRITICAL 0
WARNING 1
SUGGESTION 2
Issue Details (click to expand)

WARNING

File Line Issue
plugins/altimate-code/hooks/features/comments.tsx 390 The pane re-enables Reply/Resolve while the module-level posting lock is still held through the post-refresh load; a press in that window is silently dropped

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/comments.tsx 474 placeThread counts line numbers with slice().split('\n') per match: O(matches × file size)
plugins/altimate-code/hooks/features/to-model.tsx 14 Eight new feature modules repeat the same 15 no-op exports (~420 duplicated lines); anchored here as the representative copy
Files Reviewed (22 files)
  • plugins/altimate-code/.claude-plugin/plugin.json - 0 issues
  • plugins/altimate-code/hooks/altimate-cli.ts - 0 issues
  • plugins/altimate-code/hooks/comments.test.tsx - 0 issues
  • plugins/altimate-code/hooks/dbt-command.test.ts - 0 issues
  • plugins/altimate-code/hooks/dbt-command.ts - 0 issues
  • plugins/altimate-code/hooks/features/comments.tsx - 2 issues
  • plugins/altimate-code/hooks/features/cost.tsx - 0 issues
  • plugins/altimate-code/hooks/features/cte-profile.tsx - 0 issues
  • plugins/altimate-code/hooks/features/defer.tsx - 0 issues
  • plugins/altimate-code/hooks/features/docs.tsx - 0 issues
  • plugins/altimate-code/hooks/features/health.tsx - 0 issues
  • plugins/altimate-code/hooks/features/index.ts - 0 issues
  • plugins/altimate-code/hooks/features/runs.tsx - 0 issues
  • plugins/altimate-code/hooks/features/sql-graph.tsx - 0 issues
  • plugins/altimate-code/hooks/features/to-model.tsx - 1 issue
  • plugins/altimate-code/hooks/integrations.tsx - 0 issues
  • plugins/altimate-code/hooks/lineage.tsx - 0 issues
  • plugins/altimate-code/hooks/status-line.ts - 0 issues
  • plugins/altimate-code/hooks/tool-chain.test.ts - 0 issues
  • plugins/altimate-code/hooks/tool-chain.ts - 0 issues
  • plugins/altimate-code/tsconfig.json - 0 issues
  • plugins/altimate-code/types/index.d.ts - 0 issues

Reviewed statically (read-only run: no test suite executed). Existing discussion on the PR was read and its findings are not repeated here.


Reviewed by deepseek-v4.1-flash-1017 · Input: 46.3K · Output: 12K · Cached: 448.8K

…threads in one pass over the text

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
threads: resolved ? current.threads.filter(one => one.shareId !== thread.shareId || one.groupId !== thread.groupId) : current.threads,
}))
// The buttons are back: the next press must not be dropped while the refresh runs.
release()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: the new release-before-refresh window has no regression test

Nothing in hooks/comments.test.tsx presses a thread button after a post succeeds while its refresh list is still in flight: the two holdListCall tests (lines 242 and 308) hold a list that starts before the post. This release() is the whole fix for the previous finding, and it is easy to undo by accident (moving it back below await load($), or dropping the released guard) without any test failing. A test that holds the list call that follows a successful post and presses the button before it resolves would pin the behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant