dsh-base

Imported from zylimit/dsh-base (AGENTS.md). Install upstream with npx skills add zylimit/dsh-base. Copyright stays with the author.

dsh-base — project constitution

This file is injected into every request. It holds only durable invariants. Procedure lives in skills (.dsh/skills/); reference material lives in docs/. When a rule here and a skill disagree, this file wins.

0. What this repository is

A development scaffold for the DeepSeek Harness. It ships a project constitution, a skill library, a zero-dependency governance engine (dsb), document templates, git hooks and CI. It governs itself with its own engine: every rule below is either enforced by a named command, or explicitly marked prompt-only.

Engine entry point: node .dsh/base/dsb.mjs <subcommand> Exit codes: 0 clean · 1 violation · 2 blocking gate · 3 degraded (never a false green) · 4 stale evidence.

1. Evidence law

A claim about the state of this repository is worth nothing without a fresh command output.

Before stating that anything works, passes, is fixed, or is done:

1. Name the command that would prove it. (prompt-only)
2. Run it fresh. Never reuse an earlier run across an edit. (prompt-only)
3. Read the full output and the exit code. (prompt-only)
4. Confirm the output actually supports the specific claim. (prompt-only)
5. Only then say it. (prompt-only)

Banned phrasings: "should work", "probably fine", "looks correct", "I believe it passes". Say instead: what ran, what it returned, and what remains unverified.

A missing tool is BLOCKED, never PASS. An empty verification plan is BLOCKED. Nothing ran, so nothing is proven. Degraded (exit 3) is not success.

2. Approval tiers (prompt-only)

When the tier is ambiguous, take the higher tier. Prompt-only.

3. Scope law — preventing runaway change

1. Work from a task envelope: Goal · Scope · Out of scope · Existing pattern · Verification · Escalation. A task without all six is not ready; ask, do not guess. (prompt-only)
2. Change only files inside Scope. A necessary change outside Scope is a new task, not an extension of this one. (prompt-only)
3. No drive-by refactors, no opportunistic renames, no reformatting files you did not otherwise change. (prompt-only)
4. Reuse the pattern named in the envelope before inventing a new one. (prompt-only)
5. Run node .dsh/base/dsb.mjs budget. Over budget means split the change or escalate — never widen the budget to make a boundary failure disappear.
6. Missing information is not permission. (prompt-only)

4. Architecture law — preventing decay

1. .dsh/base/catalog.json is the authoritative architecture. A design that cannot be expressed as modules, layers and forbidden edges is not finished. Enforced by arch-check.
2. When a document and the catalog disagree, the measured graph from arch-check wins and the document is corrected. Never the reverse.
3. Every module at risk tier high or critical carries an AGENTS.md with the sections Purpose · Boundaries · Invariants · Verification. The harness loads it automatically when an agent touches that directory: it is the cheapest boundary contract available. Enforced by agents-lint.
4. Every architectural decision is an ADR under docs/adr/ with a mandatory Enforced-by: line naming a real check id, fitness rule id, engine capability, or an explicit manual:<who>. A phantom reference fails adr-check: it reads as enforced while enforcing nothing.
5. New architectural debt is not permitted. Existing debt is. arch-check --record sets the baseline; arch-trend --gate fails only on a regression past the best ever recorded.

5. Quality-attribute law

Eight attributes: security safety privacy resilience reliability availability performance maintainability. Six tiers: critical high medium low minimal none.

1. critical and high block: the gate does not pass unless a check that claims the attribute actually passed for the affected module. Enforced by gate.
2. Counter-evidence outranks confirming evidence. One claiming check that FAILs or is BLOCKED reopens the gap even if others passed. Enforced by gate.
3. SKIPPED covers nothing. Declared but unwired is a visible gap, not a pass. Enforced by gate and attributes.
4. minimal and none require a written attributeReasons entry. Opting out of governance is a recorded decision, never a free default. Enforced by catalog-lint.
5. security, safety and privacy are protected: never waivable, never fast-skippable, never downgraded by a waiver. There is no expressible waiver for them. Enforced by waiver and fast.

5a. Fast mode — shipping under pressure without lying

Time pressure is real, and a gate that ignores it gets bypassed with --no-verify, which teaches the team that the gate is optional. So the pressure is served, under four conditions that stop it becoming permanent.

1. It expires by itself. dsb fast on --minutes 90 --reason "<why>". A reason is required and a window with no end is not a window. Maximum 8 hours.
2. It cannot touch the protected floor. Every check claiming security, safety or privacy runs regardless. Those are not slow; they are why the software is allowed to exist. Enforced by gate.
3. It skips only what was marked allowFastSkip in advance, while there was time to think about which evidence is cheap to defer. Deciding that during the emergency is how everything becomes skippable. Enforced by gate.
4. It is a loan, not a discount. Each skipped check is recorded SKIPPED with reason fast-mode, the gate record is stamped fastMode, and that record cannot close a task or a release. risk reports FAST_MODE_DEBT until a full gate repays it. Run dsb fast off then dsb gate.

Fast mode does not make the code correct faster. It defers evidence, dates the debt, and refuses to let you forget it.

5b. Review law

An agentic review loop is the strongest measured lever in this field: it moved one model from 27.5 % to 56.9 % on SWE-bench Verified at 6.5x the token efficiency of resampling, and three agents in structured disagreement beat five in consensus. Consensus is the failure mode, so review here is an engine gate, not a habit.

1. Structured disagreement, not consensus. Every required lens reports on its own, from its own prompt, through node .dsh/base/dsb.mjs review lens <name> reading {"findings":[...]} on stdin (exit 1 when the report is refused). Default lenses: security, privacy, resilience, reliability, correctness; the set is catalog.review.lenses. Lenses that agree cheaply have not reviewed anything.
2. A finding needs a file:line or a reproduction. review lens rejects the whole report otherwise (exit 1): an impression nobody can locate cannot be acted on. Blue is held to the same bar — review blue rejects a claim carrying no evidence (exit 1).
3. The verdict is computed, never asserted. review verdict refuses while blue is silent or a required lens never reported (exit 1). One error finding gives FIX_REQUIRED; one lens reporting itself unable gives NEEDS_MORE_EVIDENCE; otherwise ACCEPT (exit 0, any other verdict exit 2) and only then is a receipt written, recording which lenses covered the diff. A receipt with no lens coverage cannot close a task unless catalog.review.requireStructured is false.
4. One lens finding an error is not outvoted. Rule 5.2 applies here unchanged: counter-evidence outranks confirming evidence, so four clean lenses never cancel one located error. Enforced by review.
5. A review binds the diff it judged. review start opens the session against the current diffHash, and the session goes stale the instant the tree changes (exit 4). Re-open and re-run the lenses; never carry a verdict across an edit. Assemble the evidence with node .dsh/base/dsb.mjs review-pack first — a self-selected diff view is where files go unread.
6. The reviewer is never the author. Delegate each lens to a separate agent that did not write the change; when no independent reviewer exists, say so in review verdict --notes. Prompt-only: the engine counts lenses, it cannot tell who wrote the code.
7. Reviews advance in stages, and a stage is the budget. Stage 1 code (correctness, architecture, maintainability) must fully report before stage 2 functional (testing, performance), which must pass before stage 3 trust (security, privacy, reliability, resilience). review lens refuses an early report for a later stage (exit 1, stageGated), so expensive lenses are never spent on code that has not passed the cheap ones. The profile sets the team — personal convenes correctness only, team adds testing and architecture, production adds security, reliability and performance, regulated convenes all nine (including maintainability) — and a lens whose attribute no affected module declares above minimal is not convened. The four hygiene lenses sit in the deeper profiles: they improve the code, they do not decide whether it may ship. Attributes can only shrink the team, never grow it; risk and operations can only raise it. An affected module at high risk convenes at least the team profile, at critical risk at least production, and the release gate refuses a receipt that convened fewer lenses than the configured release floor (default production, never below team).
8. A review must end. catalog.review.maxRounds (default 3) caps consecutive FIX_REQUIRED verdicts on one change; at the limit the verdict reports escalate and says stop — either the change is wrong or the standard is, and no further round can tell you which. Take it to a human. Enforced by review.
9. A finding may be carried, never deleted. review backlog add records a finding a human decides to carry, with owner and expiry; review backlog list reports expirations. A security, safety or privacy finding is never backloggable — the backlog would be the waiver the design refuses.

6. Verification law

1. Verification is impact-scoped, never "run everything" and never "run what feels related". impact decides.
2. An unmapped path, a global path, a truncated file list or a non-git tree forces a conservative full fan-out marked degraded. Over-testing is cheap; a missed regression is not. Enforced by impact.
3. Review is bound to a diff. receipt write records the verdict against diffHash; one byte of change stales it and re-review is required (exit 4).
4. The ledger is hash-chained. A broken chain fails closed: every prior verification is treated as unproven until re-run. Enforced by ledger.
5. A waiver pre-declares a skip before a check runs; once a check has executed, its FAIL or BLOCKED is an immutable ledger fact that no waiver rewrites. Never edit a receipt or waiver by hand. Enforced by waiver and ledger.
6. Never re-run a check with different arguments to obtain a greener answer, and never delete evidence. (prompt-only)

7. Security, privacy and safety floor

1. No credential, key, token or personal datum is ever written to source, logs, test fixtures, commit messages, or a context pack. Enforced by fitness (no-secret-literal, no-pii-in-logs) and the context-pack deny list.
2. Never read a secret file to "check" it, and never pipe one into another command. Read the .example instead. (prompt-only)
3. Deny by default at every boundary. Every outbound call has a timeout. Every retry has a bound, a backoff and jitter. Every queue and cache has a limit. (prompt-only)
4. Failures fail safe, not open. A component that cannot establish its invariants refuses to serve, loudly. (prompt-only)
5. Errors are handled or propagated with context. Never swallowed (no-silent-failure).

8. Memory law

1. progress.md is project memory and is committed. It is project state, so another machine resumes from it; the tool under .dsh/ may be private, the memory never is. (prompt-only)
2. Three-file synchronisation. Governed code and the ledger move in the same commit, and a specification edit carries its changelog entry in the same commit. Enforced by node .dsh/base/dsb.mjs sync-check --staged in the pre-commit hook: exit 1 on MEMORY_BEHIND_CODE or SPEC_WITHOUT_CHANGELOG.
3. A Done entry without an evidence pointer is not written. A Decisions entry without the rejected alternative is a status update and belongs under Done. Hedged language is demoted to Notes tagged Needs-Confirmation. (prompt-only)
4. Recovery is one bounded command: node .dsh/base/dsb.mjs recap. It derives the live state — position, pinned, in progress, P0/P1, recent decisions and Done, risks, decay signals — inside a character budget, so resuming costs the same whether the project is a week or two years old. A compaction summary is a claim, not a fact; recap reads artifacts.
5. Memory is archived, never deleted. When the ledger exceeds its budget, node .dsh/base/dsb.mjs archive --apply moves the oldest Done and Notes entries into progress.archive.md and leaves a pointer. An archived entry is never rewritten; a correction is a new entry in the live ledger.
6. Re-read the invariants after any compaction and at every phase boundary. Compaction does not correct instruction drift — measured across 23 models, the summary carries the drift forward instead of repairing it — so this constitution decays inside a long session and nothing reports it. node .dsh/base/dsb.mjs invariants re-derives the non-negotiable set plus the live state (open task, open fast-mode window, last gate, broken ledger) inside ~1200 characters: recap says where the work is, invariants says what may not be traded away.

8a. Fleet law — when the system is many repositories

1. One repository per service, each small enough that one agent holds its whole model, is the right answer to context. It moves complexity from file dependencies to contracts between repositories, and nothing inside a repository can see that surface. (prompt-only)
2. fleet.json at the group root declares every repository and every contract it provides and consumes. Enforced by fleet lint.
3. Never change a published contract version in place. Publish the new version beside the old, declare a sunset date, migrate every consumer, then retire. A deprecation with no sunset date is an error, not a label. Enforced by fleet.
4. Before a breaking contract change, run fleet impact <contract>. Its coordinationCost is the number of repositories that must be released together; that number is the decision, not an afterthought.
5. A contract cycle between repositories means they cannot be released independently. That is the distributed-monolith signature: report it, do not normalise it. Enforced by fleet.
6. Boundaries are judged by co-change, not by line count. cochange measures which modules actually move together. High coupling with no declared edge means the boundary is wrong; accepting it requires a written reason in catalog.cochange.accepted, exactly like opting an attribute out of governance.

9. Delegation law

1. Delegate evidence-gathering. Retain judgement. A delegate's claim is accepted only with an evidence pointer. (prompt-only)
2. Every dispatch carries the six-field envelope plus a context-pack path. Every result carries the six-field result envelope with Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.
3. Start independent delegations in one message. Never sleep-poll a background job. (prompt-only)
4. Serialize writers: at most one delegate writes to a given module at a time. (prompt-only)
5. A BLOCKED result escalates in this order: supply the missing context → raise the model → split the task → report the limitation. Never retry unchanged. (prompt-only)

10. Agent efficiency law

1. Code Mode: batch independent reads, searches and commands into one run_code program. One tool call per file is the main avoidable cost in this harness. (prompt-only)
2. grep/glob before read. Do not read a large file in full when a targeted search answers the question. Never read generated output, lockfiles or vendored trees. (prompt-only)
3. Write intermediate findings to a file and pass the path; do not paste large content into messages. (prompt-only)
4. Keep this file small. Detail belongs in a skill, which is loaded only when it is needed. (prompt-only)

11. Command reference

12. Skills

dsb-operating-loop is the entry point for any non-trivial change. Load it first. The full catalog is in the session skill list; every skill is also invocable by the human as /<skill-name>. Run node .dsh/base/dsb.mjs skills-lint after editing any skill: a malformed skill is silently dropped by the harness.