Skip to content

feat(ghost-drift): add describe verb for selective fingerprint reads#51

Merged
nahiyankhan merged 2 commits intomainfrom
feat/describe-verb
Apr 23, 2026
Merged

feat(ghost-drift): add describe verb for selective fingerprint reads#51
nahiyankhan merged 2 commits intomainfrom
feat/describe-verb

Conversation

@nahiyankhan
Copy link
Copy Markdown
Collaborator

@nahiyankhan nahiyankhan commented Apr 23, 2026

Summary

  • New CLI verb ghost-drift describe prints a section map of fingerprint.md (frontmatter range, body sections, per-dimension decision blocks) with line ranges and token estimates, so host agents can selectively load only the sections they need instead of loading the whole file.
  • Skill recipes (review.md, generate.md) now open with describe and teach a recall safety rule: when uncertain which decisions are relevant, load the entire # Decisions block — typically 2–4k tokens, cheaper than missing a constraint.
  • New library exports: layoutFingerprint, formatLayout, FingerprintLayout, FingerprintLayoutSection.

Why

Typical fingerprints run 3–5k tokens, and the # Decisions block alone is usually 60–80% of that. Most agent reads (a PR review, a single-component generation) don't need every dimension. describe is the deterministic answer to "what's in this file and where" — line ranges are 1-indexed and inclusive, dropping straight into a Read tool's offset / limit = end - start + 1.

A deliberate non-decision: no [partition] hints next to decision sections. A heuristic dimension→partition mapping that looks authoritative would cause agents to skip relevant decisions; the recall safety rule in the recipe is the right place for that judgement, not the deterministic primitive.

Sample output

Run against packages/ghost-ui/fingerprint.md:

fingerprint.md — 309 lines, ~3,955 tokens

FRONTMATTER    1–164      ~973 tok        [palette, spacing, typography, surfaces, roles, observation, decisions]
# Character      166–169    ~159 tok
# Signature      170–179    ~298 tok
# Decisions      180–305    ~2,503 tok
  ### color-strategy           182–192    ~250 tok
  ### shape-language           205–216    ~181 tok
  ### typography-voice         217–229    ~258 tok
  …
# Fragments      306–309    ~21 tok

Test plan

  • pnpm exec vitest run packages/ghost-drift — 182 tests pass (7 new in test/fingerprint/layout.test.ts)
  • pnpm check — biome + typecheck + file-size + docs-frontmatter + cli-manifest all clean
  • just build-ui — docs site builds; new Inspection — describe section renders with <CliHelp command="describe" /> from auto-generated manifest
  • Manual run on packages/ghost-ui/fingerprint.md (cli + json formats)
  • Reviewer: confirm the recall safety rule wording in review.md / generate.md is appropriate for the recipe's tone

nahiyankhan and others added 2 commits April 23, 2026 06:59
`ghost-drift describe` prints a section map of fingerprint.md (frontmatter
range, body sections, per-dimension decision blocks) with line ranges and
token estimates. Lets host agents load only the sections they need instead
of the whole file — typical fingerprints run 3–5k tokens with 60–80% inside
# Decisions, and most reviews don't need every dimension.

Review and generate skill recipes now open with `describe` and teach a
recall safety rule: when uncertain which decisions are relevant, load the
whole `# Decisions` block — cheaper than missing a constraint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nahiyankhan nahiyankhan merged commit 3d547bc into main Apr 23, 2026
6 checks passed
@github-actions github-actions Bot mentioned this pull request Apr 23, 2026
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