The discern project Map

The mental model of discern in one pass: the Gate, isolated worktrees, compiled instructions, and file ownership.

The rules that govern discern, their repository effects, and accepted requirements awaiting implementation.

What discern does and does not do on your machine: no network, no telemetry, and your configured commands only.

How discern generates security-sensitive identifiers and bytes without weakening production randomness for tests.

The tenets discern holds, each with the belief behind it, the obligation, and how it is upheld.

The architecture as one picture: how the binary, an install, and the run-time verbs relate.

Look up discern terms, understand their meaning, and find the next useful explanation.

Install discern, hand setup to your coding agent, and land your first gated change.

Understand why setup recommends a strong model, which choices remain yours, and what the agent should handle without interrupting you.

Follow the setup conversation, verification run, first worktree, Gate Proof, and reviewed landing in detail.

Read the setup diff file by file, including what you edit, what discern shares, and what it regenerates.

Update the discern binary, migrate the project to match it, restart agent sessions, and verify the result.

Read a red discern done result, reproduce the failed job, and take the shortest route to the fix.

Hold a stable quality claim at a floor or ceiling that branches can tighten but not redefine.

Trace the committed tip through required production, evidence reuse, and Proof.

Change-triggered judgment stops — a deterministic trigger serves a question, the agent records a conclusion, and the Proof carries it as agent evidence.

Read the review summary a clean green Gate records for the exact commit that passed.

Keep a landed green Proof with its trunk commit, and opt into fetch transport when another clone needs it.

Find tracked files a Gate stage changed after the final commit, with the responsible stage named.

Run discern done --ci on GitHub Actions and require the machine Gate result before a pull request can merge.

Use discern improvement to find one objective fix or qualitative review that raises the project's baseline.

Interpret validation repeats, measured durations, and producer accounting without inferring authority or author quality.

Use Git history to find files that usually change with the work on your branch and may have been missed.

Read what the Logbook shows about local workflow patterns: command loops, Gate fit, funnel flow, and each Standard's trajectory.

Run discern tidy directly or from the format job to keep the Map, instructions, TODO, and root config canonical.

Cap how many test-stage runs execute at once across every checkout of the repository with [gate].concurrent_test_runs.

Read the Logbook for accepted changes, validation routes, green streaks, cycle times, Standards trends, and agent cohorts in plain counts.

How Patterns compares per-job validation outcomes under matched and controlled recorded conditions.

Read the project-local evidence required before Patterns recommends a Gate configuration or Standard pin.

Trace related Pattern findings into bounded, evidence-backed diagnostic paths.

Copyable checkpoint triggers for common review moments, with advice on stop and advise modes.

What discern creates at start, refreshes at update, and removes after a submitted change lands.

The shared branch accepted work lands on, what moves it, and why work stays off it.

Configure external resources that discern creates, reuses, destroys, and reclaims with each worktree.

How every checkout gets stable names, a deterministic port and test seed, inherited env values, and discoverable resource handles.

How people and agents share a repository while each change stays in its own worktree and branch.

Block until a sibling branch is green, its work lands, or the trunk moves, using a held call instead of guessed polling.

Configure discern across sibling repositories, from local package links and registries to umbrella repos and submodules.

Read the current worktree or fleet dashboard and its next actions without running the Gate.

Start work, open configured coding agents, and supervise every active worktree from discern's interactive fleet view.

Choose another checkout and open a child shell at the matching project-relative directory.

A deterministic teaching line per Desk session, including what it shows, how it is chosen, and where its record lands.

How conversation consent and recorded grants decide whether a submitted commit returns for review or lands directly.

How discern completes or rolls back an interrupted acceptance without replaying authority or overwriting changed checkout data.

Finish a branch, report its Proof for review, wait for approval, and accept the same validated commit.

Prune and the Desk offer to reclaim spent train stages whose commits travel inside a live branch while keeping their branch refs.

How automatic cleanup proves a worktree belongs to discern and verifies that its checkout is gone.

How discern reports and safely cleans files an external program writes into a worktree path after removal.

Restore committed work after discern removes a worktree branch.

Review and record an explicit local integration before required machine validation finishes.

Configure instruction sources and write project rules that every supported coding agent can follow.

Run refresh, inspect the agent files, and keep every configured agent on the current sources.

How Skills give agents task-matched procedures, and when to use one instead of instructions, a script, or documentation.

The registry-checked catalog of task playbooks bundled with discern and materialized for coding agents.

Create a project-specific SKILL.md, make its trigger discoverable, and materialize it for every configured agent.

Eject a bundled Skill into project ownership, override by name, or exclude a bundled or authored Skill from materialization.

Capture a durable lesson from an agent session in instructions, a Skill, a checkpoint, a script, documentation, or an ADR.

How one schema, one paths registry, and one comment-preserving writer read, resolve, and edit discern.toml.

One neutral model in src/lib/docs.ts backs every reader of a documentation tree: discern map, discern docs (terminal and Model Context Protocol, or MCP), exports, the docs site, and its search and machine-readable derivations. The shared model discovers, orders, resolves, searches, and renders Markdown without deciding whether it is reading a configured project map or discern's product manual. src/lib/manual.ts applies the repository manual's closed corpus policy. This is one document engine with two policy models (ADR 0314).

Find the authority for versioned Git-admin records and apply the forward-version rule.

How schema changes advance installed projects while preserving config validity and project-owned content.

How result vocabulary, Zod schemas, generated contracts, and protocol validation stay synchronized.

The one blessed pattern for narration lines, groups, aligned listings, and errors with recovery.

The strict config-only renderer for bundled instructions and bundled-skill Markdown.

The local, metadata-only record of discern's verb starts and completions, including storage, config epochs, and readers.

Locate the exact adapters that may write process streams or terminate the product process.

Sequence promise-like effects or transfer them to an exact lifecycle boundary with synchronous rejection handling.

Route ordinary spawns through the shared capability or an exact ratcheted registry.

Environment-only trials, their activation rules, and the current experiments.

How CLI and MCP command paths declare effects, choose a shared-state boundary, and refuse conflicting writers.

meta.managed_version answers which discern release last successfully adopted the project's managed material. Start with the shared classifier, then the transaction and evidence decision. The programme authority is ADR 0400.

How discern configures instructions, Skills, MCP, hooks, trust, and worktrees for Claude Code.

How discern configures instructions, Skills, MCP, hooks, worktree setup, and Git rules for Codex.

How discern configures instructions, shared Skills, MCP, hooks, and workspace trust for Gemini.

How discern configures instructions, Skills, MCP, hooks, trust, and worktrees for Cursor.

How discern configures shared instructions and Skills, MCP, hooks, and folder trust for GitHub Copilot.

Choose terminal, Markdown, JSON, or MCP delivery for one prepared DiscernResult.

The public MCP tools, resources, DiscernResult envelope, generated schemas, and command exit-code contract.

Where the public compatibility policy lives, which comparators, registries, and guards enforce it, and how members become evolving.

The DSSE-compatible envelope attached to a landed commit, including its payload, signature boundary, and reading rules.

Every project path discern writes or maintains, its edit and overwrite contract, Git treatment, and uninstall behavior.

What discern records about its own verb runs, where the files live, and how to read, archive, reset, or disable them.

How discern reports unexpected internal errors across the CLI and MCP, where it saves local evidence, and what to attach to an issue.

Supported operating systems and architectures, required tools, identity selectors, and worktree command tokens.

How discern fits long-running tool calls inside each coding agent's MCP timeout.

How long operations report progress while they run, the producer progress protocol, and the handle that reads an operation back after a lost call.

What discern writes to your OS temp directory, how long each file lives, where the self-shim resolves, and how everything leaves with the tool.

How owners preview and confirm archive or reset, how sealed history stays recoverable, and how reports select it.

The checkpoint open question states, the declaration and variance flags, and the surfaces that report them.

The versioned DISCERN_CHECKPOINT_INPUT facts, DISCERN_MATCH output, lifecycle, and candidate-worktree execution boundary.

Owner consent, point-in-time write checks, resumable phases, and provider activation during setup.

Journal states and owner-confirmed choices for an interrupted project-authored setup command.

Where authored code may consult the host process, and how deeper code receives those values.

Recovery for discern done failures whose immediate diagnostic needs more context. The routine gate procedure lives in getting-started.md and code-conventions.md.

The engineering inventory of every project-tree path discern writes or maintains, derived from the same registries as the write boundary.

Use measured evidence to remove unreachable code, incidental repetition, and concentrated responsibilities without distorting ownership to improve a number.

The prerequisites, editor settings, and maintainer actions used alongside coding-agent work in this repository.

Cloning, setting up, and running the project locally for the first time.

Locate the membership authorities whose consumers must enroll new members automatically.

How this repository's tests are written, how they run, and which patterns the gate requires.

Run a package-owned application through discern's process and interaction boundaries, and choose the appropriate testing seam.

Capture a real discern command at a fixed terminal size, inspect its visual browser rendering, and hand the rendered evidence to review.

Canon Editor edits the prose registries on their generated pages and proves every save with the canons' guards.

The rules the tooling enforces, and the conventions to follow when writing code here.

How files, subprocess output, caches, and other external values earn the TypeScript types discern uses.

Read discern's clone-group evidence and reduce the repository's held duplicate-line total.

Each expensive test execution should establish a necessary state, exercise a necessary boundary, or observe a distinct transition. A shared helper removes source duplication; calling that helper for every assertion can still repeat expensive work.

The release site answers from authored Markdown records and a validated publication snapshot. ADR 0400 governs the programme, including later CLI, desk, reminder, adoption, and installer work.

Start in site/ui/pages/ for a React page and site/ui/layouts/ for its shared structure. Document.tsx owns the document head, theme bootstrap, and assets. site/ui/components/ holds thin product adapters over the exact published design system. Page-specific styles and progressive enhancements live in site/page-src/; shared browser assets remain authored in site/pages/assets/.

The site's React pages live in site/ui/. Marketing pages render at build time; Releases and the map directory render on the server. Their shared document and layout components use the package's typed React adapters. The browser receives HTML, CSS, and explicit progressive enhancements, with no hydration (ADR 0402). See Authoring site pages for editing locations and the server/browser distinction.

The site consists of one fetch handler and static files. Publishing runs that handler at a public address. Local and production both run site/serve.ts, so the local preview uses the production rendering path.

discern uses one exact @discern-sh/design-system alias. It resolves to an immutable JavaScript Registry (JSR) release through the committed Deno lock. Ordinary commands need no package checkout. The discern-sh/design-system repository authors and releases the package. This repository owns the discern.sh integration and product compositions.

/docs is the authored product manual. /map is a directory of the configured project map, with entries hosted in the source repository. The corpora share neutral discovery and publication primitives while keeping separate reader promises (ADR 0314, ADR 0403).