ets-hook-dsh-search-suggester
Verified@playform/ets-hook-dsh-search-suggester · v0.2.1 · CC0-1.0
The search-suggester hook: a DeepSeek Harness plugin that hooks the tools/post-execute waterfall and, when a search-class call (grep, glob, read, or a search-shaped bash) matches one of the ten intent kinds (Version, Path, Ledger, Config, Dependency, Test
Install
dsh plugin add @playform/ets-hook-dsh-search-suggester Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Readme
@playform/hook-dsh-search-suggester
v0.2.1 - UNPUBLISHED - plan: SEARCH-SUGGESTER-PLUGIN
The role
The search-intent target suggester for the DeepSeek Harness plugin family (the Classic release).
It is a DeepSeek Harness plugin that hooks the tools/post-execute waterfall and, when a
search-class call (grep, glob, read, or a search-shaped bash) matches one of the ten intent
kinds, prepends ONE labeled additionalContexts note naming the likely target set.
That target set is the standard locations where the intent lives in this repo, delivered before the model burns the searches.
Plan: SEARCH-SUGGESTER-PLUGIN.md.
Why
In the measured sessions, 46% of every tool call is a search-class call, and the discovery is late: in the release lane only 6% of the files the model eventually edited had been read before its first edit.
The repetition is not mostly literal; it is semantic, with the same intent reached through a dozen different literals and a hundred different paths.
The deliverable is not a better search but a target set: a compact, ordered, intent-keyed list of the standard locations, delivered at the first call of an intent.
The intents
Ten kinds, in priority order (destructive first): Version, Path, Ledger, Config,
Dependency, Test, Symbol, Doc, Usage, Owner.
Each kind is a pack row: its signal table (regex rules with weights), its per-intent threshold
(0.85 for the destructive Version/Path/Ledger, 0.75 for the rest), and its ordered
candidate set, where each candidate is a path or glob with a prior and one reason phrase ("the
monorepo manifest", "the const Version", "the build mirror - never edit").
A candidate without a reason is not emitted.
The intents are pack-driven: the built-in pack (the default of this monorepo) lives in
@playform/ets-lib-dsh-pack and is projected here as the search/ domain.
A repository that ships .dsh/pack.yml (or a user-layer pack at
~/.dsh/playform/workspaces/<slug>.yml) gets its OWN search/ intents, and a repository without a
pack stays silent.
The gate
k = sigmoid(sum(weights) + b), b = -0.6, so a single weak signal never crosses the default
threshold.
The noise control combines a cooldown (no second note for the same intent within cooldownCalls), a
dedupe (the same intent + candidate set is one note), a per-turn cap (maxNotesPerTurn), and the
already-recent filter.
Every abstention and suppression is a ledger line, so the precision is measured, not assumed.
The identity element of the algebra is silence.
The delivery
One note, never a content replacement: the post-execute listener runs AFTER the ccr's
{prepend: true} listener and only adds additionalContexts, so a ccr-compressed result is
unaffected.
The note carries the own source label of the plugin
({kind: "search-suggester", form: "notice", summary}), because an unlabeled context would render
as a user prompt in derived history.
The optional second surface (sectionMode: "sticky", off by default) is one
system-prompt/assemble section carrying the target list of the current intent, rebuilt on a TTL
and invalidated on tools/change.
The graph projection (P2)
The generated repo index of the plan is superseded by a projection of the workspace graph (the
approved re-spec, Completion-Spec/03-SUGGESTERS.md section 3): the optional ctx.workspaceGraph is
probed through ctx.get (no inject, because a repo without the graph still emits) and one
snapshot() read becomes the projection.
A candidate's literal score is the proof of the graph (the node exists, its kind matches the expected kinds of the intent, and its recency is the version-token rank of the node), and its scope is the depth tier of the path (the plan's 1.0 / 0.7 tiers).
When the graph is absent or empty, the candidate scores the documented neutral literal 0.5 and
scope 1.0 (the PoC values, byte-identical).
The projection is cached and rebuilt on tools/change while refreshOnBoot holds.
The sticky section renders the projected index (the top graph paths per intent) instead of the static pack list whenever the graph proves a candidate.
The projection adds no ledger string, because the note and the section are the evidence.
The learning
Two layers, both deterministic and LLM-free.
The offline seed (
Function/Seed) runs at load and warms the knowledge from the canonical candidates of the built-in pack (prior 1.0) plus the graph projection (a proven candidate is seeded twice).It never overwrites an existing row, does not save (the next real write persists it), and is switched off by
learn: falseorseed: false.The online learning: after a note, a candidate the model actually touches within the window is a
followed(counts move and the journal closes), while an untouched window closes asignored.The knowledge file (
persistPath,~/.dsh/search-suggester/knowledge.json) is written atomically (temp + rename, mode 0600) and bounded, and a corrupt file degrades to the cold start, where the static pack alone is enough to emit.
The dismissal
The suggestion_dismiss tool (registered through the tool API of the loader when the host exposes
ctx.tools) records a durable dismissal: pass the suggestion family (the intent id a note named)
and optionally one candidate path.
A family dismissal suppresses the note (suppressed dismissed <Intent>), and a path dismissal drops
that candidate.
The record line is dismissed <Intent> <path|*>.
The dismissal lives in the knowledge file and expires after dismissTtl seconds (default 86400),
with no timer because the read prunes it.
The benchmark
The fixed fifty-call replay (Variable/Sequence) runs through the real built listener and is scored
by Function/Benchmark, and the recorded baseline is
calls=50 notes=5 precision=1.00 recall=0.70 first-note=1.
The Source/Test/Benchmark folder asserts the numbers and their determinism, so a rule change that
loses a target shows up as a recall drop.
The waterfall discipline
next() is always awaited first, pass-through returns the downstream decision unchanged, and the
whole transform is fail-open: an internal error logs a warning and the decision passes through, so a
note never fails a tool call.
The registration is plain, after the ccr and the normalize family.
The write/edit/raw-write calls are learning signals only, because a note after the edit is too
late.
The configuration
See SCHEME.md for the full schema.
Every tuning knob is volatile (hot-editable, no remount); the structural knobs (persistPath,
refreshOnBoot) remount on edit, and indexPath is retired by the P2 re-spec (kept so an existing
profile loads unchanged).
Ships disabled: enable by explicit ACTIVATE in the profile.
The build and the tests
Fifteen folders under Source/Test/, each standalone and under Maintain/Run-Smokes.mjs, each with
its own ## Expected count:
- the five original folders (Pack-Driven, Post-Execute-And-Learning, Sticky-Section-And-Ring, Wiring-And-Ledger, Workspace-Gate);
- the four capability folders of this wave (Projection, Dismiss, Seed, Benchmark);
- the nine suites of the plan, three covered by the original folders (Delivery-And-Label and Learning-Update by Post-Execute-And-Learning, Ledger by Wiring-And-Ledger) and six added here (Classification, Threshold-And-Cooldown, Abstention, Persistence, Index-Refresh, Noise).
The aggregate prints 126 PASS.
The plan
- SEARCH-SUGGESTER-PLUGIN - the pattern algebra.
- Completion-Spec/03-SUGGESTERS - the approved re-spec (section 3, the graph projection).
License
CC0-1.0.