Skip to content

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

Merged
hkaltai merged 32 commits into
mainfrom
feat/docs-propagation
Nov 18, 2026
Merged

hkaltai merged 32 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's SQL, as of the last dbt compile; an edit of a schema file updates the offers, not the coverage.
  • 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 4 commits November 13, 2026 16:35
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>
… 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: 9 Issues Found | Recommendation: Address before merge

Incremental review of 6a25fc9..02a1c55. The increment reworks model resolution (modelRef is now byFile-aware, picks a versioned model's declared/latest version, and falls back to model.<package>.<model> instead of the bare name), skips # lines inside a plain description, and adds four tests. Two new suggestions come from the new resolver (marked new); seven prior findings are unchanged code, re-verified at this HEAD, and are listed again without duplicate inline comments (their threads are still open). The earlier findings on the comment-between-paragraphs reader, the modelPaths loop, the projectOf comment placement, the dead stem parameter, the over-4 MiB fallback to a bare name, and the coverage-argument / versioned-test gaps are resolved or fixed by this increment and are dropped.

Overview

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

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 355 New: built is model.<package>.<model>, which is never the unique_id of a model that has versions:. When the manifest read throws (the file exists but is over the 4 MiB a plugin can read, or the read fails), a schema edit of a versioned model now resolves to an id that matches nothing — no offers — where the bare name sent before could still be resolved by the CLI. sqlEdited stays silent as well, because "Model not found" does not match MISSING_TOOL, so coverage never appears.
plugins/altimate-code/hooks/features/docs.test.tsx 549 New: neither node has version or latest_version, so this case passes only through the descending unique_id tie-break (.v2 above .v1); a .v9 id would sort above .v10, so v9 would win. The declared-latest path is covered by the next test, so this is either a fallback test needing a retitle or a latest-version test needing the fields.
plugins/altimate-code/hooks/features/docs.tsx 219 Carried, re-verified: a model's versions: key closes inColumns, so the columns: under each - v: N are never read and a description written for a version is not offered.
plugins/altimate-code/hooks/features/docs.tsx 415 Carried, re-verified: EditedFile is { path, before } (tool-chain.ts:29,124), so the beforeUnknown operand is always undefined; a Write over an existing but unreadable schema file is still created: true, and every description in it is traced, offered and reported as newly written.
plugins/altimate-code/hooks/features/docs.tsx 443 Carried, re-verified: the manifest is read and JSON.parsed once per traced column (up to MAX_COLUMNS = 3) inside the same ROUND_MS window; with the new per-node filters this is now three full parses plus three filter passes. Read once per edit or cache by mtime like lineage's manifestCache.
plugins/altimate-code/hooks/features/docs.tsx 616 Carried, re-verified: answer is cast to `{ drop?: unknown }
plugins/altimate-code/hooks/features/docs.tsx 714 Carried, re-verified: the Edit-with-empty-old_string creation path has no test; no test in the repository passes old_string: ''.
plugins/altimate-code/hooks/features/docs.tsx 722 Carried, re-verified: editReadsBefore = true makes tool-chain read the whole file before every Edit/Write/MultiEdit (tool-chain.ts:112), not only schema YAML in a dbt project.
plugins/altimate-code/hooks/features/docs.test.tsx 588 Carried, re-verified: the refusal test proves the offers survive but not the applied.delete rollback; removing those two lines keeps the test green while a refused Apply's description would be filtered out of the next edit and never offered again.
Files Reviewed (4 files)
  • plugins/altimate-code/hooks/features/docs.tsx - incremental change (valueAt 126, modelPaths 252-257, modelRef 345-374, sqlEdited 491) reviewed with full-file context; 2 new suggestions, 6 carried
  • plugins/altimate-code/hooks/features/docs.test.tsx - 4 changed/added tests traced by hand against the harness (NODE, start, toolArgs); 1 new suggestion, 1 carried
  • plugins/altimate-code/hooks/tool-chain.ts - targeted check of EditedFile, EDIT_TOOLS, the before-read and editReadsBefore (unchanged by this increment)
  • plugins/altimate-code/hooks/lineage.tsx - targeted check of the 4 MiB manifest cap that $.fs.read imposes (unchanged by this increment)

Validation was not run in this read-only review; no lint or test command was executed to confirm the four new tests pass.

Fix these issues in Kilo Cloud

Previous Review Summaries (5 snapshots, latest commit 6a25fc9)

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

Previous review (commit 6a25fc9)

Status: 13 Issues Found (1 warning, 12 suggestions) | Recommendation: Address before merge

Incremental review of 732f56d..6a25fc9. The commit makes two reader fixes in docs.tsx with two tests: valueAt now continues a plain value across blank lines (paragraph breaks), and modelPaths tolerates comments and blank lines between list items. Both behaviours match how a YAML parser reads those inputs, and the new tests assert the intended results. Two suggestions come from the new loops (marked new); the eleven prior findings are unchanged code and were re-verified at this HEAD with current line numbers, so they are listed again without duplicate inline comments (their threads are still open).

Overview

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

WARNING

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 349 Carried, re-verified: $.fs.read refuses files over 4 MiB (lineage.tsx:49,395 stat-checks before reading; docs.tsx does not), so on a large manifest this read throws, the catch returns the bare name, and the cross-package ambiguity this lookup fixes is silently back (the trace and every candidate offered for Apply can come from another package's same-named model).

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 126 New: the loop now crosses blank lines and also reaches a # comment indented deeper than the description key; inlineValue does not strip a line that begins with #, so the comment is appended to the description. Adding or removing such a comment then counts as a changed description (spurious propagation offer) and the pane shows it as part of the text. Skip comment lines, as the outer loop at line 164 does.
plugins/altimate-code/hooks/features/docs.tsx 252 New: /^\s*-\s+/ is tested in the loop condition and again in the body, and the full transform chain is inlined; a single pass (if dash push; else if not blank/comment break) is equivalent and removes the duplicate test.
plugins/altimate-code/hooks/features/docs.tsx 598 Carried, re-verified: answer is cast to `{ drop?: unknown }
plugins/altimate-code/hooks/features/docs.tsx 346 Carried, re-verified: stem is never passed by either call site (425, 473), so it always equals model; in schemaEdited the original_file_path clause can only add a second, different match and demote a unique_id back to the bare name.
plugins/altimate-code/hooks/features/docs.tsx 397 Carried, re-verified: the beforeUnknown operand is always undefined (EditedFile is { path, before }, tool-chain.ts:29, and afterCall passes only those), so the guard rests on before === null && !created; a Write over an existing but unreadable schema file is still created: true and every description in it is traced, offered and reported as newly written.
plugins/altimate-code/hooks/features/docs.tsx 425 Carried, re-verified: the manifest is read and JSON.parsed once per traced column (up to MAX_COLUMNS = 3) inside the same ROUND_MS window; read once or cache by mtime like lineage's manifestCache.
plugins/altimate-code/hooks/features/docs.tsx 340 Carried, re-verified: the projectOf doc comment sits directly above modelRef's comment, leaving projectOf (line 359) undocumented.
plugins/altimate-code/hooks/features/docs.tsx 696 Carried, re-verified: the Edit-with-empty-old_string creation path has no test; no test in the repository passes old_string: ''.
plugins/altimate-code/hooks/features/docs.tsx 704 Carried, re-verified: editReadsBefore = true makes tool-chain read the whole file before every Edit/Write/MultiEdit (tool-chain.ts:112), not only schema YAML in a dbt project.
plugins/altimate-code/hooks/features/docs.test.tsx 544 Carried, re-verified: only impact_analysis args are asserted; nothing pins the dbt_docs_coverage argument (docs.tsx:473), which can now be a versioned unique_id.
plugins/altimate-code/hooks/features/docs.test.tsx 548 Carried, re-verified: the versioned case asserts the bare-name fallback (['stg_orders']) while its title claims the model "is still found by its file name or its name"; the original_file_path branch is exercised by no test.
plugins/altimate-code/hooks/features/docs.test.tsx 571 Carried, re-verified: the refusal test proves the offers survive but not the applied.delete rollback (docs.tsx:600); removing those two lines keeps the test green while a refused Apply's description would be filtered out of the next edit and never offered.
Files Reviewed (4 files)
  • plugins/altimate-code/hooks/features/docs.tsx - incremental change (valueAt 124-127, modelPaths 252) reviewed with full file context; 2 new suggestions, 1 warning and 6 suggestions carried
  • plugins/altimate-code/hooks/features/docs.test.tsx - 2 new tests reviewed and traced by hand; 3 suggestions carried
  • plugins/altimate-code/hooks/tool-chain.ts - targeted check of EditedFile, the before-read and editReadsBefore (unchanged by this commit)
  • plugins/altimate-code/hooks/lineage.tsx - targeted check of the 4 MiB manifest cap (unchanged by this commit)

Validation was not run in this read-only review; no lint or test command was executed to confirm the new tests pass.

Fix these issues in Kilo Cloud

Previous review (commit 732f56d)

Status: 11 Issues Found (1 warning, 10 suggestions) | Recommendation: Address before merge

Incremental review of e6aefd4..732f56d. The only change is a two-line guard in modelRef (docs.tsx:349-350): the single-match branch now requires the entry itself as well as named.length === 1, which satisfies the unchecked-index type without changing behaviour (named.length === 1 already guarantees named[0] exists). No new defect follows from it. All eleven prior findings remain at this HEAD with no code change addressing them; only the line numbers below shifted by one where the new lines were inserted.

Overview

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

WARNING

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 346 Carried, re-verified: $.fs.read refuses files over 4 MiB (lineage.tsx:49,395 stat-checks before reading; docs.tsx does not), so on a large manifest this read throws, the catch returns the bare name, and the cross-package ambiguity this lookup fixes is silently back — the trace and every candidate offered for Apply can come from another package's same-named model.

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 595 Carried, re-verified: answer is cast to `{ drop?: unknown }
plugins/altimate-code/hooks/features/docs.tsx 343 Carried, re-verified: stem is never passed by either call site (docs.tsx:422, 470), so it always equals model; in schemaEdited the original_file_path clause can only add a second, different match and demote a unique_id back to the bare name.
plugins/altimate-code/hooks/features/docs.tsx 422 Carried, re-verified: the manifest is read and JSON.parsed once per traced column (up to MAX_COLUMNS = 3) inside the same ROUND_MS window; read once or cache by mtime like lineage's manifestCache.
plugins/altimate-code/hooks/features/docs.tsx 394 Carried, re-verified: the beforeUnknown operand is always undefined (EditedFile is { path, before }, tool-chain.ts:29), so a Write over an existing schema file whose before-read fails is still created: true and every description in it is traced, offered and reported as newly written.
plugins/altimate-code/hooks/features/docs.tsx 693 Carried, re-verified: the Edit-with-empty-old_string creation path has no test; no test in the repository passes old_string: ''.
plugins/altimate-code/hooks/features/docs.tsx 701 Carried, re-verified: editReadsBefore = true makes tool-chain read the whole file before every Edit/Write/MultiEdit (tool-chain.ts:112), not only schema YAML in a dbt project.
plugins/altimate-code/hooks/features/docs.tsx 337 Carried, re-verified: the projectOf doc comment sits directly above modelRef's comment, leaving projectOf (line 356) undocumented.
plugins/altimate-code/hooks/features/docs.test.tsx 571 Carried, re-verified: the refusal test proves the offers survive but not the applied.delete rollback (docs.tsx:596); removing those two lines keeps the test green while a refused Apply's description would be filtered out of the next edit and never offered.
plugins/altimate-code/hooks/features/docs.test.tsx 544 Carried, re-verified: only impact_analysis args are asserted; nothing pins the dbt_docs_coverage argument (docs.tsx:470), which can now be a versioned unique_id such as model.shop.orders.v2.
plugins/altimate-code/hooks/features/docs.test.tsx 548 Carried, re-verified: the versioned case asserts the bare-name fallback while its title claims the model "is still found by its file name or its name"; the original_file_path branch is exercised by no test.
Files Reviewed (5 files)
  • plugins/altimate-code/hooks/features/docs.tsx - 7 issues (1 warning, 6 suggestions; all carried, line numbers re-checked at this HEAD)
  • plugins/altimate-code/hooks/features/docs.test.tsx - 3 issues (all carried, re-verified)
  • plugins/altimate-code/hooks/tool-chain.ts - targeted check of EditedFile, the before-read path and editReadsBefore (unchanged by this commit)
  • plugins/altimate-code/hooks/lineage.tsx - targeted check of the manifest size cap (unchanged by this commit)
  • Incremental diff itself: docs.tsx:349-350 only, correct and behaviour-preserving

Fix these issues in Kilo Cloud

Previous review (commit e6aefd4)

Status: 11 Issues Found (1 warning, 10 suggestions) | Recommendation: Address before merge

Incremental review of cfac01d..e6aefd4. The commit makes Apply roll back its applied marks when $.prompt.submit answers with a drop, so a refused request leaves the offers for the next Apply instead of clearing them; the new test drives that path and confirms the pane and band still show the offers. The behaviour reads correctly against the surrounding Apply state (the finally still releases applying, and the clear step is intentionally skipped), and the restriction that made the prior review uneasy is unchanged. Two new suggestions: the refusal guard carries a test that cannot be false, and the rollback of the applied marks is not exercised by any test. All nine prior findings are still present at this HEAD (only the two symbols after the inserted block shifted by five lines); the manifest-size warning remains the one item worth deciding on before merge.

Overview

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

WARNING

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 346 Carried, re-verified: $.fs.read refuses files over 4 MiB (lineage.tsx:48), so on a large manifest the read throws, the catch returns the bare name, and the cross-package ambiguity this lookup fixes is silently back — the trace and every candidate offered for Apply can come from another package's same-named model.

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 594 New: answer is cast to `{ drop?: unknown }
plugins/altimate-code/hooks/features/docs.test.tsx 571 New: the test proves the offers survive a refusal but not the applied.delete rollback (docs.tsx:595); removing those two lines keeps the test green while a refused Apply's description would be filtered out of the next edit and never offered.
plugins/altimate-code/hooks/features/docs.tsx 343 Carried, re-verified: stem is never passed by either call site, so it always equals model; in schemaEdited the original_file_path clause can only add a second, different match and demote a unique_id back to the bare name.
plugins/altimate-code/hooks/features/docs.tsx 421 Carried, re-verified: the manifest is read and JSON.parsed once per traced column (up to MAX_COLUMNS = 3) inside the same ROUND_MS window; read once or cache by mtime like lineage's manifestCache.
plugins/altimate-code/hooks/features/docs.test.tsx 548 Carried, re-verified: the versioned case asserts the bare-name fallback while its title claims the model "is still found by its file name or its name"; the original_file_path branch is exercised by no test.
plugins/altimate-code/hooks/features/docs.test.tsx 544 Carried, re-verified: only impact_analysis args are asserted; nothing pins the dbt_docs_coverage argument (docs.tsx:469), which can now be a versioned unique_id such as model.shop.orders.v2.
plugins/altimate-code/hooks/features/docs.tsx 337 Carried, re-verified: the projectOf doc comment sits directly above modelRef's comment, leaving projectOf (line 355) undocumented.
plugins/altimate-code/hooks/features/docs.tsx 393 Carried, re-verified: the beforeUnknown cast is always undefined (EditedFile is { path, before }, tool-chain.ts:29), so a Write over an existing schema file whose before-read fails is still created: true and every description in it is traced, offered and reported as newly written.
plugins/altimate-code/hooks/features/docs.tsx 692 Carried, re-verified: the Edit-with-empty-old_string creation path has no test; no test in the repository passes old_string: ''.
plugins/altimate-code/hooks/features/docs.tsx 700 Carried, re-verified: editReadsBefore = true makes tool-chain read the whole file before every Edit/Write/MultiEdit (tool-chain.ts:112), not only schema YAML in a dbt project (acknowledged follow-up).
Files Reviewed (4 files)
  • plugins/altimate-code/hooks/features/docs.tsx - 7 issues (1 warning, 6 suggestions; 2 new at 594, 5 carried re-verified)
  • plugins/altimate-code/hooks/features/docs.test.tsx - 4 issues (1 new, 3 carried re-verified)
  • plugins/altimate-code/hooks/tool-chain.ts - targeted check of EditedFile and the before-read path (unchanged by this commit)
  • plugins/altimate-code/hooks/lineage.tsx - targeted check of the 4 MiB $.fs.read limit (unchanged by this commit)

Fix these issues in Kilo Cloud

Previous review (commit cfac01d)

Status: 9 Issues Found (1 warning, 8 suggestions) | Recommendation: Address before merge

Incremental review of 1c3e679..cfac01d. The new commit replaces the blind model.<package>.<model> prefix with a manifest lookup: exactly one matching nodes entry becomes its unique_id, anything else falls back to the bare name, and projectOf's project name is still required first. The three replacement tests match that behaviour, and one prior finding is resolved: a model with versions: now falls back to the same bare name the CLI resolved before the prefix was added, so its top-level columns: description is no longer reported "not found". Nothing blocks merge, but the lookup degrades silently on the manifests the plugin already treats as too large to read, which is the one issue worth deciding on before merge.

Overview

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

WARNING

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 346 New: $.fs.read refuses files over 4 MiB (lineage.tsx:48), so on a large manifest the read throws, the catch returns the bare name, and the cross-package ambiguity this commit fixes is silently back — the trace and every candidate offered for Apply can come from another package's same-named model.

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 343 New: stem is never passed by either call site, so it always equals model; in schemaEdited the original_file_path clause can only add a second, different match and demote a unique_id back to the bare name.
plugins/altimate-code/hooks/features/docs.tsx 421 New: the manifest is read and JSON.parsed once per traced column (up to MAX_COLUMNS = 3) inside the same ROUND_MS window; read once or cache by mtime like lineage's manifestCache.
plugins/altimate-code/hooks/features/docs.test.tsx 547 New: the versioned case asserts the bare-name fallback while its title claims the model "is still found by its file name or its name"; the original_file_path branch is exercised by no test.
plugins/altimate-code/hooks/features/docs.test.tsx 538 Carried, still present: only impact_analysis args are asserted; nothing pins the dbt_docs_coverage argument (docs.tsx:469), which now can be a versioned unique_id such as model.shop.orders.v2.
plugins/altimate-code/hooks/features/docs.tsx 337 Carried, still present: the projectOf doc comment sits directly above modelRef's comment, leaving projectOf (line 355) undocumented.
plugins/altimate-code/hooks/features/docs.tsx 393 Carried, still present: the beforeUnknown cast is always undefined (EditedFile is { path, before }, tool-chain.ts:29), so a Write over an existing schema file whose before-read fails is still created: true and every description in it is traced, offered and reported as newly written.
plugins/altimate-code/hooks/features/docs.tsx 687 Carried, still present: the Edit-with-empty-old_string creation path has no test; no test in the repository passes old_string: ''.
plugins/altimate-code/hooks/features/docs.tsx 695 Carried, still present (acknowledged follow-up): editReadsBefore = true makes tool-chain read the whole file before every Edit/Write/MultiEdit (tool-chain.ts:112), not only schema YAML in a dbt project.
Files Reviewed (5 files)
  • plugins/altimate-code/hooks/features/docs.tsx - 6 issues (4 new, 2 carried); modelRef, both call sites, projectOf
  • plugins/altimate-code/hooks/features/docs.test.tsx - 2 issues (1 new, 1 carried); new manifest fixture and three tests
  • plugins/altimate-code/hooks/tool-chain.ts - targeted verification of EditedFile and readsBefore (unchanged)
  • plugins/altimate-code/hooks/lineage.tsx - targeted check of the 4 MiB $.fs.read limit and the manifest cache pattern
  • plugins/altimate-code/hooks/task-impact.tsx - targeted check of existing handling for manifests over 4 MiB

Fix these issues in Kilo Cloud

Previous review (commit 1c3e679)

Status: 6 Issues Found (all suggestions) | Recommendation: Merge

Incremental review of fb0a883..1c3e679. The fix does what it claims: projectOf reads the project's name from dbt_project.yml, modelRef prefixes it, and both the impact_analysis trace and the dbt_docs_coverage call now send model.<project>.<model>. The new test fails without the change (the fixture's project is shop, so every traced model must start model.shop.) and EditedFile/beforeCall still hand features { path, before }. No blocking issue was found; the notes below are the remaining small items, three of them carried from the previous review and re-verified at this HEAD.

Overview

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

SUGGESTION

File Line Issue
plugins/altimate-code/hooks/features/docs.tsx 338 New: the projectOf doc comment now sits above modelRef, so projectOf (line 341) is left undocumented and the first comment reads as describing modelRef.
plugins/altimate-code/hooks/features/docs.tsx 407 New: model.<package>.<model> is not the unique_id of a model that has versions: (those are …​.v<n>), so a versioned model's top-level columns: description now comes back "not found" instead of the offer the bare name produced.
plugins/altimate-code/hooks/features/docs.test.tsx 541 New: the new test only checks impact_analysis; the same change to dbt_docs_coverage (docs.tsx:455) is unasserted, and a name-only resolver there would fail silently with no failing test.
plugins/altimate-code/hooks/features/docs.tsx 379 Carried, still present: the beforeUnknown cast is always undefined (EditedFile is { path, before }, tool-chain.ts:29), so a Write over an existing schema file whose before-read fails is still created: true and every description in it is offered and reported as newly written.
plugins/altimate-code/hooks/features/docs.tsx 673 Carried, still present: the Edit-with-empty-old_string creation path lost its only test; no test in the repository passes old_string: ''.
plugins/altimate-code/hooks/features/docs.tsx 681 Carried, still present: editReadsBefore = true makes tool-chain read the whole file before every Edit/Write/MultiEdit (tool-chain.ts:112), not only schema YAML in a dbt project (author follow-up).
Files Reviewed (5 files)
  • plugins/altimate-code/hooks/features/docs.tsx - 5 issues (2 new, 3 carried)
  • plugins/altimate-code/hooks/features/docs.test.tsx - 1 issue (new)
  • plugins/altimate-code/hooks/tool-chain.ts - targeted verification of EditedFile, editsBefore and the global readsBefore (unchanged)
  • plugins/altimate-code/hooks/altimate-cli.ts - targeted check of the CLI argv layout the new test parses (unchanged)
  • plugins/altimate-code/types/index.d.ts - targeted check that unique_ids distinguish versions (unchanged)

Fix these issues in Kilo Cloud

Additional previous summary content was truncated to keep this comment within platform limits.


Reviewed by deepseek-v4.1-flash-1017 · Input: 93.6K · Output: 30K · Cached: 1.2M

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>
@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.

hkaltai and others added 5 commits November 17, 2026 06:14
…n decides which groups a request covers

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
# Conflicts:
#	plugins/altimate-code/hooks/integrations.tsx
#	plugins/altimate-code/hooks/lineage.tsx
#	plugins/altimate-code/types/index.d.ts
…ase deadline, no tool text passed to Claude

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

hkaltai commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at 418a3e4 (reviewers: gpt-6-astra high, gpt-6.1-sol high)

First pass returned REQUEST CHANGES on two items; both were re-judged and the second pass is APPROVE from both. (1) The cost-gate/health settings and stub handlers are the shared foundation's, each replaced by its own sibling PR, outside this PR's scope. (2) Two models with the same name in different packages is outside the supported-input contract (documented limitation).

@sahrizvi sahrizvi left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Consensus review (panel: Claude as lead, plus Codex on its default model). The OpenRouter models were out of credit and did not take part. Verdict: changes requested. Two majors are open.

Scope is this PR's own change only: the merge base with the foundation PR #30 (4c8add5) up to 418a3e4, which touches features/docs.tsx, docs.test.tsx, features/index.test.ts, task-impact.tsx and types/index.d.ts. Foundation findings are not repeated here. The branch does not have #30's last two commits (2c494ec and ac0d379).

How the YAML gets written. The plugin never rewrites a schema file itself. Apply sends Claude a prompt that names the source file and the target columns, and Claude edits the files with its Edit tool. I replayed one Apply turn on a scratch dbt-duckdb project, using the exact prompt the pane builds from real impact_analysis output from altimate-code #1733 (built from e84b6ecf9a). One file had CRLF endings, comments, a quoted column name with quote: true, a &dbl | anchor block and no trailing newline. All of that survived. Two columns that were already listed got a description, and a column that was not listed was added under its model in that model's YAML file. A column that already had {{ doc("x") }} was left unchanged and reported back. The risk therefore sits in the hand-written reader that decides what to offer, not in a writer.

Majors

  1. The reader assigns descriptions to the wrong model when a list item is a bare - (inline at L169).
  2. Coverage is not refreshed after a schema-file edit, which the PR claims it is (inline at L646).

Minors (inline): versioned models are skipped (L201), Apply uses the selection from the last render (L540), the source model is resolved by name only (L390), and offers are not re-checked after a recompile (L304). One minor is not tied to a diff line and is in the PR comment: no CHANGELOG entry, README section or version bump.

Checks. Head and foundation base both pass claude plugin validate, --strict on the root and on the plugin, tests/*.sh (7 of 7) and pytest (65 passed). claude plugin test: 374 pass at head against 349 at base, with no failures at either. The repo has no tsc or tsconfig.

Mutations. Breaking the Original/Alias filter (adding Transformation, or removing the filter), the Apply-marker skip, the said-once flag, sentGroups, the late-answer check and the leave-existing instruction is each caught by the tests. Loosening the column-key check (at === columnKey to at >= columnKey) is not caught.

Replayed CLI checks. lens_types rates order_id as Original and id_alias as Alias, rates amount * 2 as Transformation, and leaves upper(status) as Not sure. Only the first two are offered. A CLI without the tool prints Unknown tool: …, which MISSING_TOOL matches, and the message is said once. Arguments go to the CLI as an argv array, with no shell.

Merge order: altimate-code #1733 first, then #30, then this PR.

if (!inModels) continue

// A list item starts a model or a column whatever key it opens with: `name` need not come first.
const dash = /^-\s+(.*)$/.exec(body)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Major: the reader puts descriptions on the wrong model. /^-\s+(.*)$/ does not match a bare - list item, which is valid YAML. In

models:
  - name: orders
    columns:
      - name: order_id
        description: Order identifier
  -
    name: customers
    columns:
      - name: customer_id
        description: Customer identifier

no new model is started at the bare -. The name: customers line then sits at modelKey, so the backfill at L193–195 renames the columns already read under orders. columnDescriptions returns customers.order_id → Order identifier and customers.customer_id → …, while a YAML parser reads two separate models. Writing orders.order_id then traces customers.order_id, and the pane offers that column's downstream targets with the orders description. A bare - under columns: drops that column instead. Suggested fix: treat ^-\s*$ (or ^-(\s+|$)) as a list item and add a test for it. (Raised by Codex, reproduced by the lead.)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 1890d12: a bare - now starts its own model or column, and its keys are read at the indent of the line below. Regression test added with your example, including a bare - under columns:.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Resolved. A bare - now starts its own model or column, and the item's keys are read at the indent of the line below it. I compared the reader with a real YAML parser on 5,000 generated schema files (bare dashes, comments and blank lines before an item's keys, |/>/quoted/multi-line plain values, nested meta.description, indentless lists, any key order) and every file matched. The same generator catches the round-1 reader. On a dbt-duckdb project, a description written under a bare - item was traced as its own model. The one gap left is a - # comment item whose keys sit deeper than dash+2: it is skipped, never misattributed (a nit).


/** `file.before` holds the text from before the edit only when `editReadsBefore` is true. */
export async function editAfter($: EngineInterface, e: FileCall, result: ToolCallResult, file: EditedFile): Promise<ContextLines> {
if (/\.ya?ml$/i.test(file.path)) return schemaEdited($, file)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Major: coverage is not refreshed after a schema edit, which the PR says it is. The PR says coverage is "updated after an edit of a model or its schema file", but a .yml edit only goes to schemaEdited, which never calls dbt_docs_coverage or touches coverage. I replayed it with real CLI output: the YAML edit called only impact_analysis, and coverage changed only after a .sql edit. So documenting a missing column, or the model itself, leaves the pane listing it as missing. The manifest also stays stale until the next dbt compile, so the fix needs more than an extra call: run coverage for the models the edited YAML documents, or keep the claim and the pane text to "after a model SQL edit, as of the last compile".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Kept the claim to what is true rather than adding a trace on a schema edit: coverage comes from the manifest's compiled SQL, which only dbt compile refreshes, so a schema-file edit cannot change it until the next compile. The PR description now says coverage updates after a model SQL edit, as of the last compile. Running coverage for the YAML's models on schema edits is a follow-up.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Resolved by narrowing the claim. The PR body now says coverage updates after a model SQL edit, as of the last compile, and that a schema edit updates the offers only. That matches the code. I verified it end to end with the #1733 build: a SQL edit produced the coverage line. Removing the SQL coverage hook makes 4 tests fail.

columnOpen = false
column = null
described = null
inColumns = key[1] === 'columns'

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor: versioned models are skipped. A model's versions: key closes inColumns, and the columns: under each - v: N are never read, so a description written for a version is not offered. Coverage takes its model name from the file name (L435). On a dbt-duckdb project with orders at v1 and v2, orders_v2.sql asks for orders_v2, the CLI answers Model "orders_v2" not found, and nothing is shown. Describing the unversioned top-level columns: of orders traces only the first version the CLI finds (v1). Nothing is misattributed, but versioned models get no offers and no coverage.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Not fixed here: versioned models (versions:) are not read, so they get no offers or coverage; nothing is misattributed. Recorded as a follow-up.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Partly resolved. A SQL edit of orders_v2.sql now resolves to that version's unique_id, and a top-level description resolves to the declared latest version. Columns written under versions[].columns are still not read, so they get no offer. This is a minor follow-up that misses offers but never picks the wrong model, and it does not block.

label={`Apply to ${plural(picked, 'column')}`}
onPress={() =>
later($, async () => {
if (!prompt || applying) return

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor: Apply uses the selection from the last render. prompt, groups and state.skipped come from the render that drew the button. If a tick toggle (or a withdrawn offer) lands before the pane re-renders, Apply still sends, and marks as applied, the old selection. The test harness re-renders between presses, so it did not reproduce there; the closure is as described. Re-read the atom inside the later callback and build the prompt from that state.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 1890d12: Apply now re-reads the pane state when pressed and builds the request and the cleared groups from it, not from the render that drew the button.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Resolved. Apply re-reads the state when it is pressed and sends only offers whose key the pane drew. One follow-up remains: offerKey does not include the candidates, so a re-traced offer with the same text could send a target that was never drawn (an edge-case minor, inline at L50). Removing the drawn filter leaves the tests passing.

const until = (await $.clock.now()) + ROUND_MS
const traced = await Promise.all(
changed.map(async one => {
const result = await runTool($, 'impact_analysis', { manifest_path: project.manifest, model: one.model, column: one.column, change_type: 'modify' }, { until, cliOnly: true }).catch(() => null)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor: the source model is resolved by name only. The source model goes to impact_analysis by name, but the CLI also accepts a unique_id. On a real project with a local package, the manifest's node order was not root-first (model.pkg.pkg_fct came before model.proj.fct). So when two packages share a model name, the trace can come from the other package, and that package's unique_ids go into the Apply request, which can then edit the wrong project's YAML. Resolving the edited file's model to its unique_id (for example from the manifest's patch_path) and passing that would close it. This is listed as a follow-up and is safe to do in one.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Valid, not fixed here: the source model is resolved by name, so two packages with the same model name can collide. Resolving it to a unique_id through the manifest's patch_path is a follow-up; the foundation's tracing is shared by every feature.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Resolved. The source model is traced by its own package's unique_id, resolved from the manifest. I verified this on a project with both model.shop.stg_orders and model.other.stg_orders: the trace went to model.shop.stg_orders. An id the manifest does not list returns MODEL NOT FOUND and offers nothing. The one fallback left is a dbt_project.yml written name : shop, with a space before the colon, which falls back to the bare name (an unusual-formatting minor, inline at L390).

blocks.push(
[
`Take the description of ${name(group.model, group.column)} as it is written in ${JSON.stringify(group.file)} (dbt project at ${JSON.stringify(group.manifest.replace(/\/target\/manifest\.json$/, ''))}), and put it on:`,
...picked.map(one => `- ${name(one.model, one.column)}${one.id ? ` (${JSON.stringify(one.id)})` : ''}, ${one.lens === 'Alias' ? 'renamed from it' : 'carried as is'}`),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor: offers are not re-checked after a recompile. Candidates are stored when they are traced and are not re-checked when the manifest changes. After a model edit and a dbt compile, a column that was an Alias may now be a calculation, but Apply still asks Claude to copy the description onto it. The "leave a column that already has a different description" guard only protects columns that already have one. Re-checking the lens when Apply is pressed, or dropping offers when target/manifest.json changes, would fix it. This is an acknowledged follow-up and not a blocker on its own.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Acknowledged follow-up, as you note: offers are checked when traced, not again after a recompile. Re-checking the lens at Apply time is recorded as a follow-up.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Not resolved; it is still a listed follow-up. Offers are not re-traced when Apply is pressed, so a downstream lineage change made after the offer is not noticed. Under this round's bar it is a minor, not a blocker: it needs a change between the offer and Apply, and the edits still go through Claude's permissions. Re-checking lens_types when Apply is pressed would close it.

@sahrizvi

Copy link
Copy Markdown
Collaborator

Consensus review, the rest of the findings (Claude and Codex). These are the ones not tied to a diff line, plus the nits. The formal review holds the majors and the inline minors.

Minor, not on a diff line

  • No CHANGELOG entry, README section or version bump for /propagate and the coverage line. plugin.json stays at 1.6.1, and the top CHANGELOG entry is main's 1.6.1. The feature would ship unannounced.

Nits

  • A description that is a YAML alias (description: *d) is read as *d and offered. Claude is told to copy the text "exactly as it is written", which can put an alias into a file where the anchor is not defined, and that file then no longer parses.
  • A comment-only line inside a multi-line plain value is folded into the preview (first # a comment second), at docs.tsx L120–123.
  • Test gap: changing at === columnKey to at >= columnKey (L204) leaves every test passing. No test has a nested description: under a column's meta, config or tests.
  • The pane offers downstream columns that already have a description without marking them; only Claude's turn decides to skip them.
  • The first CLI call on a fresh home took 4.9 s, which is longer than ROUND_MS (3.5 s); warm calls took 1.4 s. The first trace of a session can therefore come back with no answer, and it is not retried.
  • The messages for an older CLI say it "needs a release newer than 0.12.10". No released altimate-code has dbt_docs_coverage or lens_types yet (altimate-code #1733 is open), so the message should name the release once there is one.
  • The PR body says 215 tests; head runs 374, including the foundation's.
  • The follow-up "the YAML reader takes a column or model written with name as its first key" is out of date. name after other keys is read correctly, and there is a test for it.
  • features/index.test.ts now ignores every docs · log line. A real docs failure in that test would go unnoticed, so a narrower filter would be safer.

task-impact.tsx only merges two imports from ./altimate-cli; behaviour is unchanged.

hkaltai and others added 2 commits November 17, 2026 13:49
…ble before-text offers nothing; Apply reads the ticks when pressed; one shell-keyword list

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
hkaltai and others added 2 commits November 17, 2026 16:18
…ays unknown; drop unused prompt

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…at/docs-propagation

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

# Conflicts:
#	plugins/altimate-code/hooks/integrations.tsx
@hkaltai

hkaltai commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at fcb2f4a (reviewers: gpt-6-astra high, gpt-6.1-sol high)

@sahrizvi on the CHANGES_REQUESTED review, point by point (earlier fixes at b2be7d6, latest at fcb2f4a):

  • Major 1 (bare - list item): fixed; a bare - now starts its own model or column, with tests.
  • Major 2 (coverage after a schema edit): the claim is narrowed. The PR description now says coverage updates after a model SQL edit, as of the last compile.
  • Minor (Apply uses the last render): fixed; Apply re-reads what is ticked when pressed and sends only offers the pane drew.
  • Minor (versioned models), (source model resolved by name only), (offers not re-checked after a recompile): acknowledged follow-ups, listed in the PR description. None can write to the wrong column today.
  • No CHANGELOG, README or version bump: the release package does that, per the build plan.

// A file that is gone writes nothing, so what was offered from it no longer holds.
const written = columnDescriptions(after ?? '')
// A before-text that could not be read says nothing about what changed: no offer rather than every description.
const fresh = after === null || (file as { beforeUnknown?: boolean }).beforeUnknown ? [] : changedDescriptions(file.before, after)

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

WARNING: The beforeUnknown guard is dead after the merge, so a failed before-read again looks like a brand-new file

The cast cannot ever be true: EditedFile is back to { path, before } (tool-chain.ts:29), beforeCall no longer produces the flag, and afterCall passes only { path, before } to the feature (tool-chain.ts:124). In installToolChain the read is readBefore: path => $.fs.read(path) (tool-chain.ts:142) under bounded(..., null, ...), so a read that rejects or times out (permission error, network mount, over the 4 MiB limit) becomes before: null. changedDescriptions(null, after) then treats the edited YAML as a file that did not exist and reports every description in it as newly written: those are traced and offered for propagation, and the context line tells Claude they were just written.

This is the regression fixed at fcb2f4a, whose tool-chain.test.ts case was dropped in the same merge; docs.test.tsx:236 now models a missing file by throwing from the read, which codifies the conflation this guard was meant to prevent. Restore the beforeUnknown field (set when the before-read rejects or times out, with its regression test), or have schemaEdited skip the offer when file.before === null for a file that exists.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in fb0a883: the premise holds (tool-chain.ts hands the feature before:null for a failed read). The shared hook cannot be changed from this PR, so docs.tsx now treats a null before-text on an Edit (non-empty old_string, so the file must have existed) as an unknown read and offers nothing; a Write, or an Edit with an empty old_string, still counts as creating the file. docs.test.tsx covers both: the created-file case now uses Write, and a new case checks a failed Edit read offers nothing. The remaining Write-with-unreadable-before case needs the shared beforeUnknown field and is written up in shared-fixes/docs-propagation.md.

…of every description in the file

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e name in another package is never the one used

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed models are still found

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

hkaltai commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up on the open kilo-code-bot thread and the review gate. Fixed in fb0a883 (an Edit whose before-read failed offers nothing), 1c3e679 / cfac01d (a source model is traced by the manifest unique_id of its own package, falling back to the name for versioned or unreadable cases), e6aefd4 (a request the engine refused leaves Apply's offers in place). The Write-with-unreadable-before case needs the shared tool-chain change and is in shared-fixes/docs-propagation.md.

review-loop: APPROVED at e6aefd4 (reviewers: gpt-6-astra high, gpt-6.1-sol high)

hkaltai and others added 2 commits November 18, 2026 09:45
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… description is read past a blank line

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
// A plain value runs on over the lines indented more than its key.
// A blank line inside it is a paragraph break, not its end: it goes on while the next text line is still indented.
for (let i = at + 1; i < lines.length; i++) {
if (lines[i]!.trim() === '') continue

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: A comment between paragraphs is read as part of the description

Now that the loop steps over blank lines, it also reaches a # comment on a line indented deeper than the description key. inlineValue only strips a comment that follows whitespace (/\s+#.*$/), so a line that begins with # is returned verbatim and appended:

        description: First paragraph

          # checked against staging
      - name: status

reads as First paragraph # checked against staging. Since changedDescriptions compares this text, adding or removing such a comment counts as a changed description: the column is traced and offered for propagation although its description did not change, and the pane (docs.tsx:553) shows the comment as part of it. Skip lines whose trimmed body starts with #, as the outer loop does at line 164, before appending.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 02a1c55: a comment line between a description's paragraphs is skipped, with a regression test in docs.test.tsx.

if (rest.startsWith('[')) {
for (const one of rest.replace(/^\[|\]$/g, '').split(',')) names.push(one.trim().replace(/^["']|["']$/g, ''))
} else if (rest === '') {
for (let j = i + 1; j < lines.length && (/^\s*(?:#.*)?$/.test(lines[j]!) || /^\s*-\s+/.test(lines[j]!)); j++) if (/^\s*-\s+/.test(lines[j]!)) names.push(lines[j]!.replace(/^\s*-\s+/, '').replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, ''))

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 same list-item test is evaluated twice, which makes the line hard to verify

/^\s*-\s+/ is tested in the loop condition and again in the body, and the whole transform chain is inlined. A single pass keeps the intended behaviour (a blank or comment line does not end the list; anything else does) and removes the duplicate test:

for (let j = i + 1; j < lines.length; j++) {
  const row = lines[j]!
  if (/^\s*-\s+/.test(row)) names.push(row.replace(/^\s*-\s+/, '').replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, ''))
  else if (!/^\s*(?:#.*)?$/.test(row)) break
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 02a1c55: the model-paths loop is now a single pass (blank or comment lines continue, any other non-item line ends the list).

hkaltai and others added 2 commits November 18, 2026 10:00
…package's id, never by a bare name

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ned model's latest version is the declared one

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

hkaltai commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Round on head 732f56d (panel CHANGES_REQUESTED), all handled in a4e8cbf:

  • A model-paths list with comments or blank lines is read in full (docs.tsx modelPaths, regression test added).
  • A plain multi-line description is read past a blank line and stops at the next key at or above the key's indent (regression test added).
  • A Write over an existing file whose before-read failed is still treated as a creation: telling it apart needs the beforeUnknown field from hooks/tool-chain.ts, a shared file, written up in shared-fixes/docs-propagation.md. Accepted limit for this PR.
  • Source-model identity: a SQL edit resolves to the model whose file it is, a YAML name to its package's model (latest declared version for versioned models), and an unresolvable manifest uses the package-qualified id so another package's model is never traced. Tests cover each.

review-loop: APPROVED at a4e8cbf (reviewers: gpt-6-astra high, gpt-6.1-sol high)

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

hkaltai commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

review-loop: APPROVED at 02a1c55 (reviewers: gpt-6-astra high, gpt-6.1-sol high)

*/
async function modelRef($: EngineInterface, project: Project, model: string, byFile = false): Promise<string> {
if (!project.package) return model
const built = `model.${project.package}.${model}`

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: built is not the unique_id of a model that has versions

A model declared with versions: is model.<package>.<model>.v<n> in the manifest, so this string never names one; the doc comment above ("gets the id dbt would give it") holds only for unversioned models. When $.fs.read of the manifest throws — the file exists but is over the 4 MiB a plugin can read (lineage.tsx:48,395), or the read fails — modelRef returns built, so a schema edit of a versioned model's top-level columns: now matches nothing and gets no offers, where the bare name sent before could still be resolved by the CLI. sqlEdited stays silent about it as well, because "Model not found" does not match MISSING_TOOL, so coverage simply never appears. Either keep the bare name for this case (the cross-package risk it had before) or say once that the model could not be resolved.

})

test('a versioned model, whose unique_id is not built from its file name, is traced as its latest version', async ($, on) => {
const manifest = { 'model.shop.stg_orders.v1': NODE('shop', 'stg_orders', 'stg_orders_v1'), 'model.shop.stg_orders.v2': NODE('shop', 'stg_orders', 'stg_orders_v2') }

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: This case pins the id-sort fallback, not the declared latest version

Neither node here carries version or latest_version, so the assertion passes only through the tie-break that sorts by unique_id descending: ...stg_orders.v2 sorts above ...stg_orders.v1, while ...stg_orders.v9 sorts above ...stg_orders.v10, so v9 would win. The declared-latest path is covered by the next test, which sets both fields. Add version/latest_version here (as the next test does), or retitle this case to say it covers a manifest that declares neither.

@sahrizvi sahrizvi left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Consensus re-review, round 2 (panel: Claude as lead, and Codex). Head 02a1c55f86, scope git diff e10448ca66..02a1c55f86: features/docs.tsx, docs.test.tsx and the DocsState types. No shared plugin file differs from main.

Approve. Both round-1 majors are resolved.

  • The bare - reader is fixed. I compared it with a real YAML parser on 5,000 generated schema files: bare dashes, comments and blank lines before an item's keys, |, >, quoted, multi-line plain values, nested meta.description, indentless lists and keys in any order. Every file matched. The same generator catches the round-1 reader.
  • The coverage claim now matches the code. Coverage updates after a model SQL edit, as of the last compile; a schema edit only updates the offers.

End-to-end check. I built altimate-code #1733 (ec464792ca) and used it on a scratch dbt-duckdb project that has two packages, each with a stg_orders model.

  • The real hooks were fed the real files and the recorded CLI output. A description added under a bare - item traced model.shop.stg_orders, not model.other.stg_orders. Only the 3 Original and Alias columns were offered, and Apply sent one request naming them by unique_id.
  • A SQL edit produced the coverage line.
  • Two Haiku turns with the exact Apply prompt only added lines. Comments, key order, quoting and a missing trailing newline were kept, and dbt parse passes.

Checks. claude plugin test: 438 pass at head, 402 at base. Validate and --strict pass. tests/*.sh pass, and pytest has 65 passing tests. Mutation checks: the Original/Alias filter, the item boundaries, the bare-dash lookahead, the unique_id resolution, the SQL coverage hook and the before-read-failed rule each make tests fail when broken.

Remaining minors, none blocking. Each is inline; the release one is in the combined comment.

  • Stale offers after a recompile: needs a lineage change between the offer and Apply, and is a listed follow-up.
  • offerKey ignores the candidates: needs the same text written twice and a press that beats the re-render.
  • name : with a space before the colon: unusual formatting.
  • Per-version columns are not read: missed offers, never a wrong model.
  • Multi-line flow model-paths: unusual layout, silent rather than wrong.
  • No coverage line for a fully documented model: cosmetic, and the pane still shows it.
  • A Write whose before-read failed offers every description: rare, offers only, needs the shared tool-chain field.
  • No CHANGELOG entry or version bump: safe in the release change.

Merge order: altimate-code #1733 first, then this PR.

// What is ticked now, not what was drawn: a tick or a withdrawn offer may have landed since the render.
const state = (await read($, docsAtom)) ?? empty()
// An offer that arrived after the draw waits for the next Apply: it was never shown.
const groups = state.groups.filter(group => group.candidates.length > 0 && drawn.has(offerKey(group)))

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (edge, safe in a follow-up): offers are still not re-checked after a recompile. An offer keeps the candidates traced when the description was written. Suppose the person then changes the downstream model so that fct.id now comes from another column, recompiles, and presses Apply. The request still names fct.id, and Claude is asked to copy the description onto a column that no longer carries the value. This needs a lineage change between the offer and Apply, the request still goes through Claude's normal edit permissions, and the PR body lists it as a follow-up, so it does not block. Re-tracing (or re-checking lens_types) when Apply is pressed would close it. Raised by Codex as major, then rated minor by Codex under this round's bar.


const groupKey = (manifest: string, model: string, column: string) => `${manifest}|${model}.${column}`
/** Names one offer: the column and the description written to it. */
const offerKey = (group: DocsGroup) => `${groupKey(group.manifest, group.model, group.column)}|${group.description}`

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (edge): offerKey does not include the candidates. Here is the sequence. The pane draws description D for m.c with target A. The description is then changed and changed back to D, and the second trace returns target B. The offer now has the same key, so an Apply handler from the earlier render sends B, which the person never saw. This needs the same text written twice and a press that lands before the re-render, so it does not block. A key that includes the candidate ids, or a check of the candidates against the drawn ones, would close it. The drawn filter has no test either: removing drawn.has(offerKey(group)) leaves all 438 tests passing.

if (name === '' || name === '.') return path.startsWith(`${dir}/`) && !/^(?:target|dbt_packages|dbt_modules|node_modules|venv|site-packages|dist|build|\.[^/]+)\//.test(path.slice(dir.length + 1))
return path.startsWith(`${dir}/${name}/`)
})
const pkg = /^name:\s*['"]?([A-Za-z0-9_]+)['"]?\s*(?:#.*)?$/m.exec(text ?? '')?.[1]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (unusual formatting): a name : line with a space before the colon leaves the package unset. name : shop is valid YAML, but this regex does not match it. modelRef then falls back to the bare model name (L354). If the last manifest only lists another package's model of that name (model.vendor.orders), that model's downstream columns are offered for shop's description. The canonical name: shop works correctly: I verified it on a dbt-duckdb project where model.other.stg_orders and model.shop.stg_orders both exist, and the trace went to model.shop.stg_orders. An unresolved qualified id returns MODEL NOT FOUND and offers nothing. Allowing \s* before the colon would close it.

columnOpen = false
column = null
described = null
inColumns = key[1] === 'columns'

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (edge, follow-up): version-specific columns are still not read. A versions: key ends the column list, so descriptions written under versions[].columns give no offer. The rest is fixed: a SQL edit of orders_v2.sql now resolves to that version's unique_id, and a top-level description resolves to the declared latest version. Nothing is put on the wrong model; this only misses offers.

if (!match) continue
const rest = match[1]!.replace(/\s+#.*$/, '').trim()
const names: string[] = []
if (rest.startsWith('[')) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (unusual layout): a multi-line flow list in model-paths is not read. model-paths: [ followed by "sql" and ] on later lines gives ['models'], so edits under sql/ produce no offers and no coverage. This is silent rather than wrong. Block lists with comments and blank lines are now read correctly.

const gaps = [...(view.hasDescription ? [] : ['the model itself']), ...view.missing]
// A select list that is not plain column names (a `*`, an unaliased expression, a UNION) is counted by the manifest's columns only.
const star = meta.source === 'manifest_columns' ? " · the model's select list is not plain column names (a `*`, an unaliased expression or a UNION), so only the columns the manifest lists are counted" : ''
if (!gaps.length && !star) return []

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (cosmetic): a fully documented model gets no coverage line after a SQL edit. When there are no gaps and the source is compiled_sql, the hook returns nothing. The pane still shows the coverage, so the PR's coverage claim holds, but the edit gets no feedback in the transcript. A short "all N columns documented" line would make it consistent.

const written = columnDescriptions(after ?? '')
// A before-text that could not be read says nothing about what changed: no offer rather than every description.
// An Edit replaces text that was in the file, so a missing before-text there is a failed read, not a new file.
const unknown = (file as { beforeUnknown?: boolean }).beforeUnknown === true || (file.before === null && !created)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Minor (edge, needs a shared change): a Write over an existing file whose before-read failed is treated as a creation. Every description in the file is then offered as new; only the first three are traced. This only produces offers and nothing is written without Apply. A failed read is rare. The author has noted that telling the two apart needs a beforeUnknown field from the shared tool-chain.ts, so this is fine as a follow-up.

@sahrizvi

Copy link
Copy Markdown
Collaborator

Consensus re-review, round 2 (Claude and Codex) at 02a1c55f86. This comment has the finding with no diff line and all the nits. The formal review holds the inline minors.

Minor, not on a diff line

  • No CHANGELOG entry, README section or version bump: plugin.json stays at 1.7.0. The author says the release change will do this, which is fine, but the feature should not ship without it.

Nits

  • A description that is a YAML alias (description: *d) is still read and offered as *d. This is still open from round 1.
  • A - # comment item whose keys sit more than two spaces past the dash is skipped, so it gets no offer. It is never put on the wrong model. I checked this against a real YAML parse.
  • Test gap from round 1, still open: changing at === columnKey to >= (L217) leaves every test passing. No test has a description: nested under a column's meta or config. The reader itself is right.
  • Test gap: removing drawn.has(offerKey(group)) from Apply (L598) leaves every test passing.
  • Downstream columns that already have a description are offered without being marked. Claude's turn skips them, as both replays showed.
  • ROUND_MS is 3.5 s, but the first impact_analysis call on a fresh home took 5.2 s with the #1733 build. Warm calls took 2.3–2.9 s. The first trace of a session can therefore time out, and it is not retried.
  • The messages for an older CLI still say "needs a release newer than 0.12.10", but no release has dbt_docs_coverage or lens_types yet. They should name the release once there is one.
  • The PR body is stale in three places:
    • It says "215 pass"; head runs 438 tests.
    • It says "This branch contains the foundation commits"; the foundation is merged.
    • Its follow-ups list name-first reading and name-only source resolution, and both are now fixed.

Fixed since round 1: a comment line inside a multi-line plain value is no longer folded into the preview. Apply reads the ticks when it is pressed.

@hkaltai
hkaltai merged commit 100897c into main Nov 18, 2026
4 checks passed
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.

2 participants