Document fingerprints as steering guidance#164
Closed
nahiyankhan wants to merge 461 commits into
Closed
Conversation
…ed_files - inventory: workspace expansion (package.json workspaces + apps/packages/libs/common one-level) - inventory: build_system_hints alongside platform_hints (informational) - map schema: platform and build_system accept arrays - map schema: build_system enum extended (style-dictionary, maven, sbt, cmake) - map schema: design_system.token_source (inline | external | mixed) + upstream ref - map schema: design_system.derived_files alongside entry_files; entry_files now optional - map lint: design-system-files-missing / upstream-missing / upstream-stranded soft checks - expression: relax unused-palette to count role-binding citations (palette field hexes + inline hex citations in evidence strings) - expression: shadowComplexity enum rename (none → deliberate-none) — breaking - fleet: compute/types/cli updated to handle array-shape platform/build_system - ghost-ui/map.md: declare token_source: inline (system ships its own tokens) Tests: 254 passing (+20 over the 234 baseline). New fixtures: workspace-repo, multi-platform-repo, external-tokens-repo, derived-tokens-repo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* phase-4b-schema-enrichment: feat(map,expression): Phase 4b — schema arrays + token_source + derived_files
- detect repo kind from map.md frontmatter (token_source, registry, composition) - ui-library mode (default, current guidance) - token-pipeline mode (sample at layer level, not component) - consumer mode (record what's internalized from upstream) - library-mode feature_areas heuristic (component categories / token layers) - reaffirm Phase 0 module-suffix decision; texture stays in Topology prose Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* phase-4c-recipe-branching: docs(expression): Phase 4c — branch profile recipe by repo kind
- skill-bundle schema.md: evidence is body, not frontmatter (Phase 4a missed
this LLM-facing copy — agents following the profile recipe were hitting 10
schema errors on first lint because the condensed reference still showed
`decisions[].evidence:` as a frontmatter array).
- profile.md Step 5: explicit "evidence body-only" note so the recipe surfaces
the constraint inline rather than relying on the schema reference.
- unused-palette: slug-binding propagation now actually works. A role binding
like `roles[].tokens.palette.background = "{palette.dominant.primary}"` now
resolves the reference and marks the underlying hex as cited. The 4b CHANGELOG
claimed this but the code only checked literal hexes; multiple validation
agents flagged the gap. Also widens role-palette literal collection to any
slot key (preparing for Phase 5b's open-ended slot vocabulary).
- platform_hints: drop build-system / language / runtime leaks. The hint set
is now constrained to the Platform enum (web/ios/android/desktop/flutter/
mixed/other). `bazel` lives in build_system_hints only; `ruby`, `python`,
`rust`, `go`, `jvm`, `php`, `elixir` no longer surface as platforms (they
weren't valid platform values anyway). Adds a bazel-ruby-ios fixture
modeled on real iOS monorepos that hit this leak.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- build_system enum: add vite, webpack, parcel, rollup, turbopack, esbuild,
nx, turbo. Real consumer repos use Vite + pnpm + Nx; without these the
recipe was forced to drop signal into prose. inventory.ts also detects
these via a new BUILD_TOOL_MATCHERS table (config-file basename matching).
- design_system.upstream: accepts string | string[]. Consumers that pull
from a fan-out of upstream packages (tokens + components + icons + glue)
can now express that structurally instead of packing them into prose.
- roles[].tokens.palette: open-ended slot vocabulary. Was a strict three-key
object (background/foreground/border) with `unknown keys reject`; now a
Record<string, string>. Conventional vocabulary documented in schema.md
and expression-format.md (background, foreground, surface, border,
accent, muted, link); richer slot names (ring, popover, separator, …)
no longer hard-error.
- broken-role-reference: accept opaque external token refs. Style-Dictionary-
style consumer expressions can bind role slots to upstream tokens like
`{base.color.brand.x.light}` without the linter rejecting them. Local refs
(`{palette.dominant.X}` / `{palette.semantic.X}`) still validate; refs
with recognized external heads (base/core/semantic/component/tokens/ref/
sys) or 4+ dotted segments pass through as opaque.
- Tests: vite-nx-repo and multi-upstream-repo fixtures cover detection and
lint paths; expression-side tests cover extended slot keys and external
refs (262 tests, +5 since Phase 5a).
All changes are additive — existing valid map.md and expression.md files
keep validating. ghost-ui/{map.md,expression.md} continue to lint clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…on notes Two prose-only clarifications surfaced by the second-round real-repo validation: - profile.md Step 1.5: token-pipeline takes precedence over both ui-library AND multi-platform when signals overlap. Pipelines often span multiple platforms by definition; the pipeline branch handles per-platform sinks via feature_areas. Prevents agents re-reading the rule order to be sure. - ghost-map.md composition.styling row: for token-pipeline repos where the source is JSON/YAML and no rendering style is "primary," list output styles ordered source-style-first. Prevents fabrication when the standard "first is primary" rule doesn't fit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Companion to 0983acd — the second polish edit lost the race to a linter on the first attempt. For token-pipeline repos where the source-of-truth is JSON/YAML and no rendering style is "primary," list output styles ordered source-style-first. Prevents fabrication when the standard "first is primary" rule doesn't fit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Workspace packages (@ghost/core, ghost-expression, ghost-drift, ghost-fleet, ghost-map) declare their main/module/exports as ./dist/...; vite/vitest cannot resolve those entry points on a fresh runner where dist/ does not exist. Locally tests pass because dist is left over from prior development; pre-push runs build/test/check in parallel so it doesn't trip there either. CI from a clean checkout hits "Failed to resolve entry for package @ghost/core" on every cross-package import. Adding pnpm build before pnpm test in the test job. The lint job already builds incidentally via pnpm typecheck (tsc --build) inside pnpm check. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Decompose ghost into five decentralized tools (Phase 1–5)
Rewrites the cross-cutting docs to match the post-PR-#64 reality where Ghost is five tools (ghost-map, ghost-expression, ghost-drift, ghost-fleet, ghost-ui) instead of one. CLI verbs are scoped to the tool that owns the artifact; per-tool skill bundles replace the single ghost-drift bundle. Content: - CLAUDE.md, root README, and ghost-drift README rewritten around the five-tool surface; new packages/ghost-expression/README for the intended-public sibling. - docs/generation-loop.md updates context-bundle invocations to ghost-expression; expression-format.md drops the dropped-from-scope generate recipe. Docs site: - /tools is now a five-card index. Each tool gets a /tools/<name> landing (hooking ghost-ui through to its existing /ui catalogue). - Cross-tool guides (Getting Started, CLI Reference) move from /tools/drift/* to /docs/* via a new "guide" frontmatter section. - Old /tools/drift/{getting-started,cli} URLs redirect to /docs/*. - Dock command palette restructured into Tools + Docs groups. - Home thesis softened from drift-centric framing; teases the elevation lens / world-model concept that ghost-fleet operationalizes. Tooling: - scripts/dump-cli-help.mjs walks all four CLIs (drift, expression, map, fleet); manifest now keyed by tool with each command carrying its tool prefix. - <CliHelp> takes a `tool` prop and renders the correct prefix. - check-docs-frontmatter accepts the new "guide" section and updated known-routes list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs: align docs site IA with five-tool decomposition
Pulls the Working with Ghost narrative out from the buried
/tools/drift/workflow URL and onto the /tools landing page itself,
behind a compact 5-card tool strip. Adds Step 01 · Map (write a
map.md) before the existing Profile step so the workflow opens with
ghost-map, and renumbers the rest. Drift Workflow nav entries
(/docs index card and ⌘K palette) repoint to /tools; old
/tools/drift/{workflow,concepts} URLs redirect.
Also extends HistoryRibbon (Step 05 · Evolve) with an interactive
playhead — drag to set a decision moment, pick a hypothetical
stance, and the curve re-classifies forward of the playhead.
Demonstrates the "the curve hasn't changed shape — but the meaning
of every point after has" line that the page used to only assert.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs: promote workflow to /tools hero, add Map step
…ming Across CLAUDE.md, README, docs site, skill bundles, and map.md, reframe Ghost as the design-language layer agents reach into when the UI they generate drifts. The "deterministic CLI + judgement in skills" dichotomy stays in INVARIANTS §1/§4 as the underlying constraint, not the headline. Architecture is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs: lead with the agent, demote deterministic-CLI from headline framing
…st-map Land the bucket pipeline and consolidate to a four-tool topology. A scan now runs in three stages — topology (map.md) → objective (bucket.json) → subjective (expression.md) — all owned by ghost-expression. ghost.bucket/v1: new artifact catalogues every concrete design value with structured specs, occurrence counts, and deterministic content-hashed IDs. Schema, lint, merge, and fix-ids primitives live in @ghost/core. New ghost-expression verbs: - inventory [path] — raw repo signals JSON (migrated from ghost-map). - lint [file] — auto-detects expression.md / map.md / bucket.json. - bucket merge — deterministic concat with id-based dedup, idempotent. - bucket fix-ids — recompute row IDs from content; lets surveyor agents author rows with empty id fields and finalize in one pass. - scan-status [dir] — report per-stage state and recommended next stage. New skill recipes (ghost-expression bundle): - map.md — topology stage (migrated from ghost-map skill recipe). - survey.md — objective stage. LLM-driven extraction with dialect-specific grep strategies, exhaustiveness discipline, saturation predicate. - scan.md — meta-recipe orchestrating topology → survey → profile. Refactored: profile.md is now strictly the subjective interpretation stage (reads bucket.json as ground truth; cannot fabricate values). ghost-map package deleted. ghost.map/v1 schema/types moved to @ghost/core; inventory + lint moved to ghost-expression. ghost-fleet now imports map types from @ghost/core. CLAUDE.md, README.md, and docs IA updated to reflect the four-tool topology. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…veness Self-distance reported 17.5% on freshly authored expressions because loadExpression never backfilled `oklch` on hex-only palette colors. comparePalette then treated every color as fully unmatched and contributed distance 1.0 per color even when comparing an expression to itself. Two-layer fix: - loadExpression now backfills oklch deterministically (parseColorToOklch is pure: same hex → same oklch), so re-parsing produces identical in-memory shapes. - comparePalette resolves oklch on-the-fly when missing and falls back to hex-string equality for non-parseable values (CSS vars, opaque refs). Defensive against third-party producers that emit hex-only. Survey recipe tightened with a load-bearing exhaustiveness rule. Triggered by a dogfood scan that produced ~10% recall on components (6 rows for a 97-component package). The rule is repo-agnostic: the agent identifies the canonical signal in this repo, enumerates exhaustively, and cross-checks counts. Recipe explicitly forbids sampling and placeholder/glob library names. Coverage check (step 8) is now a real gate — exhaustiveness must match independent counts before declaring saturation. Pinned attempt-1 artifacts under dogfood/ghost-ui/attempt-1/ with a structured NOTES.md documenting the failure modes. Future attempts go alongside so we can track improvement. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
External libraries (icon sets, primitive collections, motion libs, charting) no longer have a top-level bucket section. Whether a system uses Radix or hand-rolls primitives doesn't change what its design language *is*; what matters surfaces elsewhere — font families show up as typography tokens, and load-bearing library choices (icon family, font sourcing) belong in interpreter prose under the relevant decision dimension. Bucket sections are now: values, tokens, components. Removed from @ghost/core exports: LibraryRow, LibraryRowSchema, libraryRowId. Lint, merge, and fix-ids no longer touch a libraries section. Skill recipes (survey.md, profile.md) updated — survey.md no longer instructs the agent to enumerate libraries; profile.md tells the agent that load-bearing library choices land in prose, not as structured rows. zod schema stays non-strict, so historical buckets that still carry a libraries field continue to lint clean (the field is simply ignored). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…pology Six documentation files were carrying stale framing from the five-tool era or hadn't been updated for the bucket pipeline / libraries-cut. - packages/ghost-expression/README.md: full rewrite. Was framed around "four verbs" (lint/describe/diff/emit) with no mention of the scan pipeline. Now leads with the three-stage table (topology → objective → subjective), enumerates all seven verbs (inventory, scan-status, lint, describe, diff, bucket, emit), and points at all four skill recipes (scan, map, survey, profile). - packages/ghost-drift/README.md: dropped "five-tool decomposition" and the ghost-map reference. The "Authoring expression.md?" sidebar now surfaces inventory + scan-status + bucket merge alongside the existing lint/describe/diff/emit verbs. - CLAUDE.md / AGENTS.md (symlinked): bucket description no longer mentions "and libraries", scan-status added to the verbs table, scan recipe added to the workflows list. - apps/docs/src/content/docs/cli-reference.mdx: added scan-status and bucket sections under ghost-expression. Updated overview to seventeen verbs and added the scan recipe to the skill-recipes table. - apps/docs/src/content/docs/getting-started.mdx: tools table grew to include scan-status, added a three-stage diagram, replaced the single-step "Profile Your First System" with a stage-aware "Scan Your First System" walkthrough. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…nents Slot → token bindings either fall out of decisions[] (pattern consequences) or live in bucket.json components[] (exhaustive catalog). The hybrid roles[] slot was filling neither cleanly, didn't scale to systems with many components, and the schema never committed on whether it was exemplary or exhaustive. Removes roles[] from the zod schema (.strict() now rejects it), Expression type, lint (broken-role-reference rule, slug-binding propagation, and the references.ts token resolver), profile/scan/schema/verify/review recipes, expression.template.md, the docs site, and every fixture (arcade, market, ghost-ui, fleet members, .scratch). unused-palette is simplified to check decision evidence/prose only. Also: ignore .scratch/ for dogfood scans, and ship the ghost-ui expression-fidelity test bundles (arcade + market) as new fixtures. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Free-form `decisions[].dimension` slugs fragment fleet aggregation — ghost-ui's `color-strategy` and a Cash app's `color-system` describe the same axis under different names, and N-way overlap on incidentally shared labels is not a basis for cross-system distance. Add a 12-slug controlled list in `@ghost/core` (color-strategy, surface-hierarchy, shape-language, typography-voice, spatial-system, density, motion, elevation, theming-architecture, interactive-patterns, token-architecture, font-sourcing) plus `closestCanonical()` and `resolveDecisionKind()` helpers. The frontmatter schema accepts an optional `dimension_kind` on `decisions[]` as the escape hatch for genuinely novel decisions, which fleet-aggregation primitives use to roll up by canonical bucket. New soft `non-canonical-dimension` lint warning suggests the closest match without rejecting authoring freedom. Validated against every expression.md in the repo: the ghost-ui reference is 11/11 canonical with zero warnings; across 9 expressions, 47 of 64 decisions land canonical, and the matcher resolves 4 of the remaining 17 to a clear suggestion (`theming` → `theming-architecture`, `shadow-hierarchy` → `elevation`, `semantic-density` → `density`, `product-area-color-coding` → `color-strategy`). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Introduces the perceptual prior — Ghost's opinionated stance that drift severity should track how loudly a change registers visually, not just whether it deviates from a recorded value. Three perceptual tiers fix membership for each canonical dimension: loud (color-strategy, font-sourcing → critical), structural (shape, elevation, surface, interactive, typography-voice → serious), and rhythmic (spatial-system, density, motion, theming, token → nit). Match shape is per-RuleKind: color is exact, spacing is band (±2px), type-size is percent (±10%), radius and shadow are structural. Presence/absence escalation lifts a rule one tier when bucket count for its dimension is at or below presence_floor — sparsity is a design decision, and adding to a silent dimension is the loudest possible change. Adds Rule, RuleKind, RuleMatchShape, DriftSeverity types alongside existing Decision (additive — nothing removed). Expression.rules is optional. Exports computeRuleSeverity, resolveMatchShape, resolveTolerance, escalateForPresence as the helpers a v0 emitter threads the prior through. 35 new tests cover tier coverage, severity mapping, escalation boundaries, match defaults, and tolerance defaults. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds install/install.sh + install/manifest.json so the Ghost design-
language scan + emit recipes can be installed without npm or a build
step:
curl -fsSL https://raw.githubusercontent.com/block/ghost/main/install/install.sh | sh
The installer detects the host agent (claude / cursor / codex /
opencode), validates input up-front, fetches the manifest-listed files
under packages/ghost-expression/src/skill-bundle/, and lays them down
under the agent's skills directory (e.g. ~/.claude/skills/ghost/).
Idempotent — refuses to overwrite without --force. Supports
--source <url> for testing against a local mirror or a release fork.
~200 lines of POSIX sh; no Node, no jq dependency. Smoke-tested for
auto-detect, explicit agent, force-reinstall, bad-agent rejection,
and --help.
Pairs with the prose fallbacks already added to scan.md / map.md /
profile.md — the no-CLI install path is real, not degraded.
Also includes the v0 changeset (rules[] + perceptual prior +
curl-install) describing this branch's user-facing impact.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Trim the unreleased Rule type before it ships. The field added churn without earning its keep — re-scan verification can be done by re-grepping the bucket against the rule's pattern, no per-rule citation list required. Also keeps the YAML lighter for hand-authors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pair packages/ghost-ui/expression.md with its bucket.json so the reference design system carries both stage-2 and stage-3 artifacts side-by-side, like a real consumer would. Earlier dogfood/* attempts remain as the rough drafts; this is the keeper, scanned at 8196f55. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
INVARIANTS.md §3 named Character, Signature, and decision rationale as the body's prose layer. Signature is no longer load-bearing — every claim it carried is covered better by rules[] (with presence_floor for absences), decision evidence, or palette/spacing/typography/surfaces frontmatter — and the section had collapsed into restating other parts of the artifact. This is the invariant amendment per INVARIANTS.md's own preamble. The schema, parser, writer, recipe, template, and existing artifact changes ship as the next commit (major bump on ghost-expression). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Major bump on ghost-expression. The `# Signature` body section and `observation.distinctiveTraits` field are removed from the canonical expression.md schema: - DesignObservation.distinctiveTraits removed from @ghost/core - writer no longer emits `# Signature`; lint no longer expects it - parser silently ignores legacy `# Signature` blocks in older expression.md files (graceful migration for downstream consumers) - profile.md recipe: absences are now codified as rules with presence_floor instead of Signature prose - schema.md / expression-format.md / template / docs site / SKILL.md files all updated - 9 in-repo expression.md files (ghost-ui, fleet fixtures, fidelity bundles, dogfood/ghost-ui) rewritten via scripts/strip-signature.mjs - context-bundle emit uses observation.personality for the trait-phrase hooks where it previously used distinctiveTraits INVARIANTS.md §3 amended in the prior commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tailwind targets render most of their design language from class atoms
(`p-2`, `bg-orange-500`, `text-sm`) that consume framework defaults —
the spacing scale is `N * --spacing` (4px-base) by default, with most
N values never declared as `--spacing-N` tokens in `@theme {}`. A
bucket built from declarations alone undercounts the rendered scale
systematically and produces an irregular `expression.spacing.scale`
even when the live UI sits on a clean modular grid.
Surfaced by the ghost-ui dogfood at edc0913: declarations-only pass
produced spacing scale [20, 32, 44, 52, 75, 100], baseUnit null,
regularity 0.5 — vs. the canonical (curated) [2, 4, 6, 8, 12, 16, 20,
24, 32, 36, 40, 52, 75, 100], baseUnit 4. Resolving the actually-used
class atoms (`rg -oN '\bp[lrtbxy]?-N\b' | resolve to N*4px`) recovers
13 of the 14 canonical values at occurrence floor 2.
Adds a `## Tailwind class-atom pass` section between extraction step 2
and step 3 spelling out:
- the v4 atom-to-literal resolver (calculated from `--spacing`,
overrideable per N via `--spacing-N` declarations)
- the v3 fallback (read `theme.*` from `tailwind.config.{ts,js}`)
- the procedure: grep atoms, resolve to literals, record as
`values[]` rows with `usage.className`, plus tokens[] rows for the
Tailwind defaults consumed
- merge-on-collision behavior when a literal comes from both a
declared token and class-atom usage
Existing `bucket-gen.mjs` generators in dogfood/* don't implement the
pass yet — they still produce declarations-only buckets. A follow-up
attempt-4 would re-validate end-to-end.
Mirror block/sessh: after publishing the release tarball, mint a scoped GitHub App token for block/homebrew-tap and dispatch its bump-formula.yaml so each anarchitecture-ghost@X.Y.Z release auto-opens a formula bump PR. Gated on BLOCK_HOMEBREW_TAP_APP_ID so forks/unconfigured repos skip it.
Move the tap-bump from the now dispatch-only release-tarball.yml onto release.yml's automatic publish path, so brew install block/tap/ghost tracks every npm release. Gated on an actual Changesets publish and the BLOCK_HOMEBREW_TAP_* secrets.
Fix GitHub release tarballs
chore: version packages
* main: chore: version packages ci: fix GitHub release tarballs
Amp-Thread-ID: https://ampcode.com/threads/T-019ed698-27ef-73f9-bd08-21e0117db073 Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-019ed698-27ef-73f9-bd08-21e0117db073
chore: auto-bump Homebrew tap on release
chore: version packages
Make Relay briefs action-shaped
chore: version packages
Package release tarballs with dependencies
chore: version packages
…-loop-contract Add Ghost drift loop contract
nahiyankhan
force-pushed
the
codex/document-fingerprint-steering
branch
from
82d1c05 to
dcc603a
Compare
Collaborator
Author
|
Recreated as #169 (this PR was auto-closed by GitHub during a repo history rewrite that removed the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Category: improvement
User Impact: Fingerprint authors get clearer guidance for writing fingerprints that steer generation and review instead of collecting style inventory.
Problem: The public docs and bundled agent recipes explain the fingerprint layers, but they did not explicitly teach authors how to turn those layers into generation decisions. That made it easier for future fingerprints to drift toward descriptive catalogs instead of durable steering guidance.
Solution: Add concise public and agent-facing guidance that frames fingerprints as decision engines: preserve goals, block anti-goals, resolve tradeoffs, route by situation, cite exemplars, and write patterns for selection, restraint, and review.
Validation:
pnpm check: passed via pre-commitpnpm check:docs: passed,3 docs OKpnpm check:install-bundle: passed,13 files OKpnpm check:terminology: passedgit diff --check: passedpnpm build: passed via pre-pushpnpm test: failed inpackages/ghost/test/context-sandbox.test.tson an existing compact Relay brief assertion expecting no## Generated Cachesection; reproduced separately and unrelated to these docs-only changesChangeset: added patch changeset for
@anarchitecture/ghost.Ghost Review:
node packages/ghost/dist/bin.js check --base origin/main: passed, no active deterministic check failuresnode packages/ghost/dist/bin.js review --base origin/main --include-memory: emitted advisory review packet for the docs/surface-model changeFile changes
.changeset/steering-fingerprint-docs.md
Adds a patch changeset for user-facing fingerprint authoring docs.
apps/docs/src/content/docs/fingerprint-authoring.mdx
Adds an "Authoring For Steering" section after layer responsibilities, with a compact checklist for goals, anti-goals, tradeoffs, situations, principles, contracts, patterns, and exemplars.
docs/fingerprint-format.md
Adds a short format-reference note that high-quality layer content should make generation choices explicit.
packages/ghost/src/skill-bundle/references/capture.md
Adds a steering checklist to the capture recipe before agents write core layers.
packages/ghost/src/skill-bundle/references/patterns.md
Names the three useful jobs of a pattern: selection, restraint, and review.
Screenshots/Demos: N/A, docs-only change.