Skip to content

feat: copy a written column description to the downstream columns that carry it, and show a model's documentation coverage - #25

Open
hkaltai wants to merge 11 commits into
mainfrom
feat/docs-propagation
Open

hkaltai wants to merge 11 commits into
mainfrom
feat/docs-propagation

Conversation

@hkaltai

@hkaltai hkaltai commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

What this does

Adds the docs feature to the altimate-code plugin.

  • /propagate opens a pane for a model's column: it lists the downstream columns that carry the column unchanged (Original or Alias, from the CLI's lens_types), and copies the written description to the ones you pick. Columns that come from a calculation are never offered.
  • A model's documentation coverage (from dbt_docs_coverage) is shown, and updated after an edit of a model or its schema file.
  • If the installed altimate-code has no dbt_docs_coverage, that is said once, not on every edit.

Depends on the altimate-code PR AltimateAI/altimate-code#1733 (dbt_docs_coverage and lens_types); merge that first. This branch contains the foundation commits, so its diff includes them until the foundation merges.

How it was checked

  • claude plugin validate --strict . passes.
  • claude plugin validate --strict ./plugins/altimate-code reports the same 4 warnings that main reports (types/hook inventory and the missing directory icon); nothing new.
  • claude plugin test ./plugins/altimate-code: 215 pass, 0 fail, including the new hooks/features/docs.test.tsx.
  • tests/*.sh all pass.

Follow-ups, not changed here: the YAML reader takes a column or model written with name as its first key (dbt's own layout); a source model is identified by its name, so two packages with one model name resolve to the first one the CLI finds; offers are not re-traced when the manifest is recompiled after they were made.

Demo video (hosted)

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

🤖 Generated with Claude Code

hkaltai and others added 7 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>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
# Conflicts:
#	plugins/altimate-code/hooks/features/docs.tsx
…t carry it, and show a model's documentation coverage

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>
… in, drops offers for descriptions that changed or went, and keeps projects apart

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

hkaltai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Review loop result for this PR (two independent reviewers, then two fix checks). Fixes are in 520215e.

Fixed:

  • A copied description could differ from the one written (literal line breaks, escapes). Apply no longer sends the text: it names the column, the YAML file it is written in and the project, and asks Claude to copy it exactly from there. The reader now only detects changes and shows a one-line preview.
  • Clearing or changing a description left the old offer, and a late answer could install it again. Offers from a file are dropped when the file no longer has that description, and an answer is installed only if the file still has the description it traced.
  • An older trace answer could overwrite a newer one: same check as above.
  • Apply overwrote a column that already had a different description: Claude is now told to leave it and list it for the person.
  • Projects with the same model and column names shared state: groups, selection and the rendered keys carry the project, and the request carries each model's unique_id and the project folder.
  • Model and column names entered the request as raw text: they are now quoted strings.
  • Apply's own writes were offered again: a column Apply asked for is skipped once when Claude writes it.
  • A "model not found" error from dbt_docs_coverage was reported as an old altimate-code: only an error about the tool itself is.
  • More than three descriptions in one edit were silently left untraced: a line now says how many; the once-a-session warnings reset on a new session; a missing percent no longer shows NaN.
  • Overflow beyond three descriptions kept outdated offers: offers are invalidated for every changed description, not only the traced ones.

Known and left as is:

  • A change that only re-indents text inside a literal block reads the same as before in the one-line preview, so it triggers no new trace.
  • Markers for what Apply asked for are cleared when the session starts, not when a turn ends, because a turn-complete event cannot be tied to Apply's turn. A write Apply never made leaves one marker that skips one later offer for that column.
  • The final fix check was not run again after the last small edits (path spelling, group keys, marker lifetime).

Checks: claude plugin test ./plugins/altimate-code 220 pass, 0 fail (and the new tests fail when the guards are removed); claude plugin validate --strict . passes; tests/*.sh all pass. --strict on the plugin folder reports the same 4 warnings as main.

hkaltai and others added 2 commits November 13, 2026 21:21
…es whole, bounds what it offers and sends, quotes names as data, and withdraws offers for a file that is gone

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

hkaltai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Review round (two independent reviewers, Claude and Codex gpt-6.1-sol, as separate CLI processes) — replies to every finding:

Fixed

  • Apply's record of what it asked for held only the column, so a different description written there later was dropped, and it compared case-sensitively against lower-case names from the CLI. It now holds the description asked for, keyed ignoring case, and is removed if the request is not sent.
  • A column name with a dot was split into the wrong model and column; the model and column are now kept apart.
  • model-paths: ['.'] disabled the feature; . now means the project folder, less target, dbt_packages, dbt_modules, node_modules, venv, site-packages, dist, build and dot-folders.
  • A deleted or unreadable source file left its offers; they are withdrawn.
  • Apply cleared every offer, including ones that arrived while it was sending, and a second press sent the request again; it now clears only what it sent and ignores a press while one is sending.
  • No cap on downstream columns: at most 50 are offered per description, and a line says how many were left out.
  • Names in context lines were not quoted, and the Apply request did not say names and descriptions are data; both are now (names quoted; the request says neither is an instruction and to match columns ignoring case).
  • A failed impact_analysis was silent; one quoted line now says it could not find the downstream columns.
  • The select * caveat from dbt_docs_coverage was dropped; it is now in the coverage line.

A fresh reviewer run on these fixes returned RESOLVED; its small items (rollback scope, a misleading comment, the . exclusions, plural) are also done.

Not changed, with reason

  • Whitespace-only rewrites of a description are not treated as a change: it is compared as the one line it says, and Claude copies from the file.
  • A model or column written with name after another key is not read: the reader is for block-style YAML in dbt's layout (documented on columnDescriptions); follow-up.
  • Source model identity across packages uses the model name, as impact_analysis does (first match); follow-up on the CLI side.
  • Offers are not re-traced when the manifest is recompiled after they were made; Apply tells Claude to read the description from the file and leave a column that already has a different one, so nothing is overwritten.
  • Repeat traces of the same column are not shared as in the lineage pane: the answer is checked against the file when it comes back, so only a wasted trace results.
  • Lower-case names from the CLI: handled in the Apply request (match ignoring case); returning exact spelling is a CLI follow-up.

Tests: claude plugin test plugins/altimate-code — 233 pass. Not covered by a new test: the . model-paths case, a deleted file, the Apply overlap and the failure note.

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

hkaltai commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at 8df598f (claude + codex, both APPROVE on the fix commits). Non-blocking: claude noted missing tests for Apply overlap/rollback, deleted file, model-paths '.', and the failure lines; tracked as follow-up.

@kilo-code-bot

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

Copy link
Copy Markdown

Code Review Summary

Status: 3 Issues Found | Recommendation: Address before merge

Incremental review of 8df598f..f501732: the previous WARNING (Apply clearing offers for groups it did not send) is fixed by sentGroups, and the new unit test covers it. No new bugs found in the changed lines.

Overview

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

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 263 sentGroups and applyPrompt now each define which groups a request covers; if one predicate changes, Apply can again clear offers it did not send.
plugins/altimate-code/hooks/features/docs.tsx 626 editReadsBefore = true forces a full-file read before every Edit/Write/MultiEdit, including non-YAML files and projects with no dbt project.
plugins/altimate-code/hooks/features/comments.tsx 1 Eight feature stub modules are identical apart from the header comment (~390 duplicated lines); a shared no-op module re-exported per feature would remove the duplication.
Files Reviewed (3 files)
  • plugins/altimate-code/hooks/features/docs.tsx - 2 issues
  • plugins/altimate-code/hooks/features/docs.test.tsx
  • plugins/altimate-code/hooks/features/comments.tsx - 1 issue (carried, unchanged file re-verified)

Fix these issues in Kilo Cloud

Previous Review Summary (commit 8df598f)

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

Previous review (commit 8df598f)

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/docs.tsx 511 Apply's sent set includes every shown group, but the prompt skips groups whose candidates were all unticked, so pressing Apply also silently discards those unsent offers.

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 621 editReadsBefore = true forces a full-file read before every Edit/Write/MultiEdit, including non-YAML files and projects with no dbt project, adding avoidable latency to unrelated edits.
plugins/altimate-code/hooks/features/comments.tsx 1 Eight feature stub modules are identical apart from the header comment (~390 duplicated lines); a shared no-op module re-exported per feature would remove the duplication.
Files Reviewed (21 files)
  • plugins/altimate-code/.claude-plugin/plugin.json
  • plugins/altimate-code/hooks/altimate-cli.ts
  • plugins/altimate-code/hooks/dbt-command.ts
  • plugins/altimate-code/hooks/dbt-command.test.ts
  • plugins/altimate-code/hooks/features/index.ts
  • plugins/altimate-code/hooks/features/docs.tsx - 2 issues
  • plugins/altimate-code/hooks/features/docs.test.tsx
  • plugins/altimate-code/hooks/features/comments.tsx - 1 issue
  • plugins/altimate-code/hooks/features/cost.tsx
  • plugins/altimate-code/hooks/features/cte-profile.tsx
  • plugins/altimate-code/hooks/features/defer.tsx
  • plugins/altimate-code/hooks/features/health.tsx
  • plugins/altimate-code/hooks/features/runs.tsx
  • plugins/altimate-code/hooks/features/sql-graph.tsx
  • plugins/altimate-code/hooks/features/to-model.tsx
  • plugins/altimate-code/hooks/integrations.tsx
  • plugins/altimate-code/hooks/lineage.tsx
  • plugins/altimate-code/hooks/status-line.ts
  • plugins/altimate-code/hooks/tool-chain.ts
  • plugins/altimate-code/hooks/tool-chain.test.ts
  • plugins/altimate-code/types/index.d.ts

Fix these issues in Kilo Cloud


Reviewed by deepseek-v4.1-flash-1017 · Input: 52.8K · Output: 11.5K · Cached: 570.1K

hkaltai and others added 2 commits November 15, 2026 22:15
…were all unticked

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

/** The groups a request is written for: one whose candidates are all unticked is left out of it, so Apply leaves its offer be. */
export function sentGroups(groups: DocsGroup[], skipped: string[]): DocsGroup[] {
return groups.filter(group => group.candidates.some(one => !skipped.includes(candidateKey(group, one))))

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: Two definitions of "a group the request covers"

sentGroups now decides which groups Apply clears, but applyPrompt re-derives the same rule independently (filter(one => !skipped.includes(candidateKey(group, one))) plus if (!picked.length) continue just below). They agree today, so the bug fixed here stays fixed, but a later change to either predicate (for example skipping a group whose description is empty) would silently make Apply clear offers it did not send, which is the exact failure being repaired. Have applyPrompt loop over sentGroups(groups, skipped) and keep only the per-candidate picked filter, so one function owns the rule.

@hkaltai

hkaltai commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at f501732

Verify-only gate on the two new commits (fresh claude -p and fresh codex exec): both APPROVE b207a5e (Apply clears only the offers it sent, with a regression test). f501732 only removes a local tsconfig.json that b207a5e added by mistake. Plugin suite: 234 pass.

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