A lightweight cognitive-feedback plugin for DeepSeek Harness (DSH).
DSH Cognitive Feedback is designed to preserve human reasoning ownership while keeping AI-agent development productive.
The plugin does not try to reduce AI usage. Instead, it detects moments where outsourcing the reasoning would create high-value cognitive debt and inserts a small intervention: a nudge, a challenge, a reasoning gate, or a teaching-back check.
Principle: AI should accelerate implementation without silently replacing problem formulation, architecture decisions, debugging reasoning, or research judgment.
V0.1 intentionally contains only four capabilities:
- Dynamic Cognitive Prompt — inject a compact runtime instruction when an intervention is useful.
- Reasoning Gate — before high-value decisions, ask the user to state a hypothesis or proposed direction.
- Teaching Back — after selected work, ask the user to explain why the solution works.
- Cognitive Event Log — persist structured events locally for later analysis.
Soul-Spark is not a V0.1 runtime dependency. A small CognitiveEventSink interface is reserved for future integration.
- No Soul-Spark integration
- No dashboard or web UI
- No cloud synchronization
- No long-term skill scoring
- No automatic source-code modification
- No full transcript storage by default
- No hidden chain-of-thought collection
- No ML-based cognitive classifier
- No complicated dependency graph
V0.1 targets DSH 0.1.5-rc.1 (the installed baseline verified on 2026-09-11). DSH is in developer preview and its plugin APIs may change. The plugin must isolate DSH-specific integration code so future upgrades remain localized.
The plugin injects its cognitive section through the rc.1 ctx.systemPrompt section registry and observes session/event / agent/* events. See docs/dsh-integration.md for the verified interface contract and docs/testing.md for the acceptance tests, including the dynamic-injection / prompt-cache check.
DSH Runtime
│
├── session / agent events
│
▼
Cognitive Controller
├── State Engine
├── Policy Engine
├── Prompt Builder
├── Reasoning Gate
├── Teaching Back
└── Event Logger
│
▼
local JSONL event store
│
▼
CognitiveEventSink
│
└── future Soul-Spark adapter
Two data paths are deliberately kept apart:
| Live prompt | Long-term memory | |
|---|---|---|
| Input | current CognitiveState |
raw CognitiveEvent log |
| Producer | renderCognitiveSection() (src/prompt/renderer.ts) |
buildProjection() (src/projection/) |
| Output | one bounded directive, or nothing | episodes / sessions / interventions for reports |
| Cache | byte-stable while the state fingerprint is unchanged | rebuildable at any time |
src/prompt/renderer.ts never imports storage, the event log, or the projection
layer, and a test enforces that structurally. Historical events cannot change an
otherwise identical current prompt — also covered by a regression test.
Future memory work (Soul-Spark, a database, a summarizer) plugs into the
CognitiveMemorySource interface in src/projection/memory.ts. That is a seam,
not a dependency: the plugin ships an inert NO_MEMORY source, and neither the
policy nor the prompt layer imports it.
- Fail open: if the plugin fails, normal DSH coding behavior continues.
- Small prompts: interventions should be short and actionable.
- Rule first: V0.1 uses deterministic heuristics instead of another LLM classifier.
- User owns decisions: the plugin may challenge a decision but never silently make the decision for the user.
- Structured data only: store cognitive metadata, not hidden reasoning traces.
- Low intervention budget: the system should help without becoming annoying.
ARCHITECTURE.md— runtime architecture and component boundariesCOGNITIVE_MODEL.md— cognitive debt, intervention policy, and learning modelEVENT_SCHEMA.md— versioned event contractIMPLEMENTATION.md— V0.1 implementation plan and acceptance criteriaROADMAP.md— staged evolution beyond V0.1AGENTS.md— development rules for AI coding agentsdocs/dsh-integration.md— verified DSH rc.1 interface contract and compatibility notesdocs/testing.md— unit + live acceptance tests, including dynamic prompt injection and cache impactdocs/decision-policy.md— the Prompt Injection / User Q&A boundary: decision ownership, the level matrix, debug and research rulesdocs/examples.md— expected runtime behavior examplesdocs/development-workflow.md— recommended human/AI development loopsrc/— TypeScript implementation (the only source;lib/*.jsno longer exists)src/projection/— derived, rebuildable read models over the raw event log (episodes, sessions, interventions); never consulted by the live promptdist/— build output loaded by DSH (generated; not committed)tools/inspect-session.mjs— Session V3 log inspector: injection evidence + cache metricstools/cognitive-report.mjs— review the append-only log through the projection layer: funnel, episodes, sessions, interventions, timeline (runnpm run buildfirst)test/— unit tests and the live headless acceptance harness
npm install
npm run resolve:dsh-types # map @deepseek-ai/* to the INSTALLED harness types (read-only)
npm run build # tsc -> dist/ (JavaScript + .d.ts)
npm run typecheck # type check, including test/types/*.ts regressions
npm test # build + unit tests
npm run test:live "<prompt>" # real headless DSH sessions (control vs treatment)The published @deepseek-ai packages disagree with each other on peer ranges
(dsh-agent@0.1.5-rc.1 pulls dsh-session-projection@^0.1.5-rc.1, whose newest
match demands dsh-session@^0.1.5-rc.2 while the harness ships 0.1.5-rc.1), so
npm refuses to resolve the tree.
resolve:dsh-types therefore writes a gitignored tsconfig.dsh.json that
maps @deepseek-ai/* straight at the installed harness declarations. It is
read-only and writes nothing outside this repository. That is also more correct
than installing: the plugin is type-checked against exactly the version it runs on.
An earlier revision of this workflow symlinked the harness packages into this project's
node_modules. A laternpm installfollowed the link and pruned roughly 240 packages out of the global harness install. Path mapping cannot do that, so it is the only mechanism used now.
This repository is itself an experiment in AI-assisted engineering. When an AI agent works on this project, it should not immediately implement a vague request. It should first make the problem, hypothesis, design, evidence, and verification plan explicit.
The plugin should therefore be developed in the same way it is intended to make other AI-assisted work better.
V0.1 implemented and verified against a real DSH 0.1.5-rc.1 session.
The vertical slice works end to end: observe a signal → classify the task → decide whether to intervene → inject a section into the system prompt → record a structured event.
src/**/*.ts— TypeScript source;dist/is the built plugin (JS +.d.ts)npm test— builds, then 133/133 unit tests pass (no DSH required), including the DSH adapter boundary via a fake Cordis contextnpm run typecheck— includes type-level regressions (@ts-expect-errorassertions intest/types/)npm run test:live— real headless sessions, control vs treatment, pinned to the official model route
Beyond V0.1 (schema stays v1; every addition is optional/additive):
| Increment | What it added |
|---|---|
| decision ownership | policy answers who owns this decision (agent/shared/user) before choosing none / nudge / challenge / reasoning gate, and records it in the event |
| correlation | episodeId/interventionId on every related event, so joins never guess from topic or timestamp |
| Cognitive Episode | a derived reasoning unit reconstructed from the log, with an explicit episode.closed terminator |
| teaching-back evidence | deterministic evidence extraction (cause, mechanism, concept, confidence, length) instead of a bare grade |
| prompt / memory boundary | the live renderer is structurally unable to read history; a CognitiveMemorySource seam for future memory |
| projection layer | one-pass session/episode/intervention read models with a rebuildable, discardable cache |
| longitudinal metrics | exposure / response / outcome / utilization from persisted events, with a baseline comparison and an explicit non-causality caveat |
| topic learning state | knowledge-gap recurrence aggregated by normalized topic, reporting-only |
Verified live:
| Claim | Evidence |
|---|---|
| an architecture request is detected deterministically | intervention.triggered {level: 3, reason: "architecture"} in the JSONL |
| the section really reaches the model exactly once | treatment system/message is 4971 chars with 1 [COGNITIVE FEEDBACK] block; control is 4508 chars with 0 |
| the plugin is prompt-transparent when inactive | step-1 usage is byte-identical across arms (cacheRead=768, uncachedInput=15462) |
| dynamic injection does not break prompt-cache reuse | steps 2+ read the full ~17k prefix from cache; per-step hit rate 98.25% with the section present vs 96.67% without |
| no tool-schema churn | the plugin registers no tools; one system/message node is emitted across a 4-step run |
See docs/testing.md for the method, the raw numbers, and the real defects the live tests and the independent review caught.