polydeukes 0.4.0 → 0.6.0

package/dist/explain.js

@@ -0,0 +1,153 @@
+/**
+ * `pdks explain` — render both surfaces' assembled registration sets without judging.
+ *
+ * This module calls the composition roots' OWN assembly functions and renders what they
+ * return, so it reports the table the judgment uses rather than a second opinion about it.
+ *
+ * It never dispatches, never writes telemetry or a baseline, and never opens a transcript
+ * file — the session assembly receives core's `noopTranscript`, which answers queries with
+ * nothing and reads no disk. Every failure throws: an answer that cannot be given is never
+ * given halfway.
+ */
+import { join } from 'node:path';
+import { resolveGitAdapterSettings } from '@polydeukes/adapter-git';
+import { AXIS_NAMES, deriveShape, noopTranscript, RELATION_NAMES } from '@polydeukes/core';
+import { assembleSessionRegistrations } from './claude-code-hook.js';
+import { assembleCommitRegistrations } from './covenant-check.js';
+import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
+import { loadConfig } from './load-config.js';
+/** The three meta-covenant labels: registrations that protect the judging chain itself. */
+const META_LABELS = new Set(['self-mod', 'shell-mod', 'transcript-mod']);
+/**
+ * The description of a declaration entry: its catalogue coordinate (the mechanism, the axes
+ * its sources derive, and the relations its entries decide), then what it routes on, how
+ * large its two regex lists are, how many sources it names and how many of those carry
+ * each non-file kind, whether it carries a valve, and whether the author left a `why`. An
+ * absent scope block admits every world.
+ *
+ * The axes are derived, never read off the declaration: `loadConfig` has already run the
+ * declaration through the validator, so the shape here is the one the catalogue admitted.
+ */
+function declareDescription(entry, enforce) {
+    const declare = entry.declare;
+    const shape = deriveShape(declare);
+    const axes = AXIS_NAMES.filter((axis) => shape.axes.has(axis)).join(',');
+    const relations = RELATION_NAMES.filter((relation) => shape.relations.has(relation)).join(',');
+    const relate = declare.relate.map((relateEntry) => relateEntry.id).join(', ');
+    const scope = declare.scope === undefined ? 'scope every world' : `scope ${declare.scope.source}`;
+    const include = declare.scope?.include?.length ?? 0;
+    const exclude = declare.scope?.exclude?.length ?? 0;
+    const bindings = Object.values(declare.sources ?? {});
+    // A file binding is the unmarked kind, so only the two the surface has to supply are
+    // counted out; a kind nothing binds is left off rather than printed as a zero.
+    const kinds = ['sidecar', 'transcript']
+        .map((kind) => ({ kind, count: bindings.filter((binding) => kind in binding).length }))
+        .filter(({ count }) => count > 0)
+        .map(({ kind, count }) => `${kind} ${count}`);
+    const counted = kinds.length === 0 ? '' : ` (${kinds.join(', ')})`;
+    const sources = `sources ${bindings.length}${counted}`;
+    const valve = declare.witness === undefined ? '—' : '✓';
+    const why = entry.why === undefined ? '—' : '✓';
+    return (`${declare.mechanism} · ${axes} · ${relations} ${relate} · ${scope} · ` +
+        `include ${include} · exclude ${exclude} · ${sources} · valve ${valve} · why ${why}${enforce}`);
+}
+/** One rendered line: the kind column, the label column, then the description. */
+function row(kind, label, width, description) {
+    return `  ${kind.padEnd(8)} ${label.padEnd(width)} ${description}`;
+}
+/** The description of a meta-covenant registration — how much surface it covers. */
+function metaDescription(registration, surface) {
+    if (registration.label === 'transcript-mod') {
+        return 'content predicate · conditional: transcript_path';
+    }
+    return `paths ${registration.protectedPaths.length} (${surface})`;
+}
+/** Render one surface: its header, its tallies, and one line per registration. */
+function renderSurface(spec) {
+    const lines = [];
+    const width = Math.max(...spec.registrations.map((registration) => registration.label.length), ...spec.drafts.map((draft) => draft.id.length));
+    let declare = 0;
+    let skip = 0;
+    let meta = 0;
+    for (const registration of spec.registrations) {
+        if (META_LABELS.has(registration.label)) {
+            meta += 1;
+            const scope = registration.label === 'self-mod' ? spec.selfModScope : 'common';
+            lines.push(row('meta', registration.label, width, metaDescription(registration, scope)));
+            continue;
+        }
+        if (registration.skip !== undefined) {
+            skip += 1;
+            lines.push(row('skip', registration.label, width, registration.skip.reason));
+            continue;
+        }
+        // Every non-meta body registration is one config entry's declaration; a label the config
+        // does not carry is an assembly the renderer was never told about.
+        const entry = spec.disciplines.find((candidate) => candidate.id === registration.label);
+        if (entry === undefined) {
+            throw new Error(`explain: registration '${registration.label}' matches no config entry`);
+        }
+        // The DECLARED level is rendered, never the effective one: an omission stays unmarked
+        // so the default and an author's explicit choice of it never read alike, and the
+        // surface header states what the omission resolves to.
+        const level = entry.enforce === undefined ? '' : ` · enforce: ${entry.enforce}`;
+        declare += 1;
+        lines.push(row('declare', registration.label, width, declareDescription(entry, level)));
+    }
+    for (const draft of spec.drafts) {
+        lines.push(row('draft', draft.id, width, 'unpromoted — no judgment'));
+    }
+    const tally = `  registrations ${meta + declare + skip} · ` +
+        `declare ${declare} · skip ${skip} · meta ${meta} · draft ${spec.drafts.length}`;
+    return [spec.header, tally, ...lines].join('\n');
+}
+/**
+ * Read the config at `repoRoot`, assemble both surfaces, and render them.
+ *
+ * The session assembly is given a transcript path, so its `transcript-mod` registration
+ * exists here exactly as it does under a normal hook payload — the path is never read,
+ * because the injected transcript is the no-op one.
+ */
+export async function explain(spec) {
+    const { config, configPath } = loadConfig({ rootDir: spec.repoRoot });
+    // Resolved and imported exactly as the two runners do, so what this renders is the table
+    // that would judge: a dist those runners would refuse cannot be rendered as if it worked.
+    // The load names the missing module and the recovery command.
+    const covenant = await loadCovenantModule(resolveCovenantDist());
+    const disciplines = config.disciplines ?? [];
+    const drafts = config.drafts ?? [];
+    const session = assembleSessionRegistrations({
+        config,
+        rootDir: spec.repoRoot,
+        covenant,
+        transcriptPath: join(spec.repoRoot, 'transcript.jsonl'),
+        transcript: noopTranscript,
+    });
+    const commit = assembleCommitRegistrations({
+        config,
+        rootDir: spec.repoRoot,
+        covenant,
+    });
+    const gitSettings = resolveGitAdapterSettings({ namespace: config.adapters?.git });
+    const text = [
+        `pdks explain — ${configPath}`,
+        '',
+        renderSurface({
+            header: 'surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block',
+            registrations: session,
+            drafts,
+            disciplines,
+            selfModScope: 'common; includes the config file itself',
+        }),
+        '',
+        renderSurface({
+            header: `surface: commit (git pre-commit) · enforce: ${gitSettings.enforce} · disciplines: advise unless enforce: block`,
+            registrations: commit,
+            drafts,
+            disciplines,
+            selfModScope: 'common ∪ adapters.git; deduped, includes the config file itself',
+        }),
+        '',
+    ].join('\n');
+    return { text };
+}

package/dist/index.d.ts

@@ -3,25 +3,20 @@
  * coding partner.
  *
  * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
- * `pdks` CLI entry point. It owns the config discovery loader (CONFIG-03) and both
- * surfaces' composition roots — `runCovenantCheck` for the commit surface and
- * `runClaudeCodeHook` for the session one — because assembly needs an adapter and the
- * covenant package at once, which no sibling is allowed to depend on. The covenant,
- * ledger, memory, and verify modules live in their own `@polydeukes/*` packages.
+ * `pdks` CLI entry point. It owns the config discovery loader and both surfaces'
+ * composition roots — `runCovenantCheck` for the commit surface and `runClaudeCodeHook`
+ * for the session one — because assembly needs an adapter and the covenant package at
+ * once, which no sibling is allowed to depend on. The covenant, ledger, memory, and verify
+ * modules live in their own `@polydeukes/*` packages.
  *
  * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
- * here would be instantiated by every consumer of any other export — which is exactly how
- * the session adapter ended up on the commit surface's load path (PR #46 review). Keep
- * definitions in their own modules and let importers reach them directly.
+ * here would be instantiated by every consumer of any other export. Keep definitions in
+ * their own modules and let importers reach them directly. A session call enters through
+ * the published `./claude-code` subpath instead, which keeps the commit surface and its git
+ * adapter off that load path.
  *
- * The mirror of that coupling is closed as of DIST-02. `exports` publishes `./claude-code`
- * alongside `"."`, and both delegators — this repository's and the one `pdks init
- * claude-code` generates — enter through it, so a session call no longer instantiates
- * `covenant-check.js` or `@polydeukes/adapter-git`. The window DIST-01 §3-d declared (a
- * workspace missing only that dist failing closed with no telemetry row) is gone with it.
  * See https://github.com/huskyhoochu/polydeukes
  */
 export type { ResolvedConfig } from '@polydeukes/core';
-export { type ClaudeCodeHookSpec, runClaudeCodeHook } from './claude-code-hook.js';
-export { type CovenantCheckSpec, runCovenantCheck } from './covenant-check.js';
-export { type LoadedConfig, loadConfig } from './load-config.js';
+export { type CheckDomain, type CovenantCheckOutcome, type CovenantCheckSpec, runCovenantCheck, } from './covenant-check.ts';
+export { type LoadConfigSpec, type LoadedConfig, loadConfig } from './load-config.ts';

package/dist/index.js

@@ -3,24 +3,19 @@
  * coding partner.
  *
  * Pre-alpha. This package reserves the unscoped `polydeukes` name and is the umbrella /
- * `pdks` CLI entry point. It owns the config discovery loader (CONFIG-03) and both
- * surfaces' composition roots — `runCovenantCheck` for the commit surface and
- * `runClaudeCodeHook` for the session one — because assembly needs an adapter and the
- * covenant package at once, which no sibling is allowed to depend on. The covenant,
- * ledger, memory, and verify modules live in their own `@polydeukes/*` packages.
+ * `pdks` CLI entry point. It owns the config discovery loader and both surfaces'
+ * composition roots — `runCovenantCheck` for the commit surface and `runClaudeCodeHook`
+ * for the session one — because assembly needs an adapter and the covenant package at
+ * once, which no sibling is allowed to depend on. The covenant, ledger, memory, and verify
+ * modules live in their own `@polydeukes/*` packages.
  *
  * This file is a barrel and nothing more. ESM re-exports are eager, so anything defined
- * here would be instantiated by every consumer of any other export — which is exactly how
- * the session adapter ended up on the commit surface's load path (PR #46 review). Keep
- * definitions in their own modules and let importers reach them directly.
+ * here would be instantiated by every consumer of any other export. Keep definitions in
+ * their own modules and let importers reach them directly. A session call enters through
+ * the published `./claude-code` subpath instead, which keeps the commit surface and its git
+ * adapter off that load path.
  *
- * The mirror of that coupling is closed as of DIST-02. `exports` publishes `./claude-code`
- * alongside `"."`, and both delegators — this repository's and the one `pdks init
- * claude-code` generates — enter through it, so a session call no longer instantiates
- * `covenant-check.js` or `@polydeukes/adapter-git`. The window DIST-01 §3-d declared (a
- * workspace missing only that dist failing closed with no telemetry row) is gone with it.
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { runClaudeCodeHook } from './claude-code-hook.js';
-export { runCovenantCheck } from './covenant-check.js';
+export { runCovenantCheck, } from './covenant-check.js';
 export { loadConfig } from './load-config.js';

package/dist/init-claude-code.d.ts

@@ -1,27 +1,40 @@
 /**
- * `initClaudeCode` — the session-surface installer (DIST-02 §3-a/§3-b/§3-g).
+ * `initClaudeCode` — the session-surface installer.
  *
  * One command wires a project into the session surface: prove the package resolves, run the
  * shared project-side scaffold ({@link scaffoldProject}), then add what this distribution
- * path owns — the delegator hook file, its `.claude/settings.json` registration, and the
- * discipline file that tells an agent the docs query exists (DOCS-02 §3-e).
+ * path owns — the delegator hook file, its `.claude/settings.json` registration, the
+ * discipline file that tells an agent the docs query exists, and the classification skill
+ * that turns a described problem into a config entry.
  *
- * Preflight comes first and nothing is written before it clears (§5-d invariant 2). A
- * generated hook whose import can never resolve blocks every call through its own
- * fail-closed catch, and a tree that also has no config and no valve to open cannot be
- * edited back into shape from inside the session — the brick §3-g exists to prevent.
+ * Preflight comes first and nothing is written before it clears. A generated hook whose
+ * import can never resolve blocks every call through its own fail-closed catch, and a tree
+ * that also has no config and no valve to open cannot be edited back into shape from inside
+ * the session.
  *
- * Nothing existing is overwritten (§5-d invariant 1). The settings file in particular is
- * merged, never replaced: a consumer's other PreToolUse registrations and permissions are
- * live configuration, and replacing them would disarm every other tool they wired.
+ * Nothing existing is overwritten. The settings file in particular is merged, never
+ * replaced: a consumer's other PreToolUse registrations and permissions are live
+ * configuration, and replacing them would disarm every other tool they wired. A grok JSON
+ * whose command still names the grok mjs is rewritten to this hook's command so the two
+ * installers do not leave two spawn strings.
  */
-import { type ScaffoldReport } from './scaffold-project.js';
-/** `initClaudeCode` input (DIST-02 §3-g) — the target tree and the preflight seam. */
+import { type ScaffoldReport } from './scaffold-project.ts';
+/**
+ * The generated classification skill — the procedure that turns a described problem into a
+ * registered entry. A classification procedure an agent never learns about is one that never
+ * runs, so it ships as an artifact of the install rather than as prose in a README.
+ *
+ * Its advise-consumption section is the delivery path for advised rows: the session surface
+ * lets an advised call through with exit 0, and the reason never reaches the model at call
+ * time — reading the telemetry log at task boundaries is the only way it arrives.
+ */
+export declare const GENERATED_SKILL = "---\nname: discipline-draft\ndescription: Turn a described discipline problem into a registered entry in polydeukes.config \u2014 a judged entry when the current families can express it, a draft entry otherwise. Use when the user describes a recurring problem they want promised away (\"I keep...\", \"stop X from happening\", \"we should never...\", \"how do I enforce Y\").\n---\n\n# discipline-draft \u2014 from a problem description to a registered discipline\n\nThis project is judged by Polydeukes. A discipline starts as prose and climbs a ladder \u2014\n`draft` (registered, read, never judged) \u2192 `advise` (judged, recorded, never stops a call) \u2192\n`block` (stops the call; the user's explicit choice, never the default). This skill walks a\nproblem description down to the right first rung and registers it.\n\n## Procedure\n\n### 1. Restate the problem as a promise\n\nRewrite the description as one sentence of the form \"X must not happen\" or \"when A happens,\nB must also happen\". If the sentence needs \"unless\" more than once, split it into two\npromises and classify each separately.\n\n### 2. Classify the shape\n\nAsk these questions in order; the first yes decides.\n\n| # | Question | Entry key |\n| --- | --- | --- |\n| 1 | Is the promise about content newly ADDED to a file (a pattern that must not appear in new lines)? | `declare` (mechanism `added-only`) |\n| 2 | Is it about a whole path that must not be modified or deleted (creating it once stays allowed)? | `declare` (mechanism `self-absolution-ban`) |\n| 3 | Is it about the shell command line itself, regardless of files? | `declare` (mechanism `forbidden-command`, reading the `command` source) |\n| 4 | Does it require that something else was already done earlier in the session (a tool call that must precede this one)? | `declare` (mechanism `precedent`, reading a `transcript` source) |\n| 5 | None of the above | `draft: true` (step 4b) |\n\nAn `added-only` declaration forgives existing occurrences \u2014 only what the edit adds breaks\nthe promise. That is usually what you want: a discipline adopted today should not indict\nyesterday's code.\n\nOne path-shaped promise takes no `disciplines:` entry at all: a path nobody may touch\nbelongs in the top-level `protectedPaths:` list \u2014 its own config block, never an entry key.\n\n### 3. Check the observation boundary\n\nTwo kinds of promise cannot be judged here, whatever their shape:\n\n- **Destruction outside the repository** \u2014 judgment observes the project root only. Register\n  nothing; use the agent's own permission deny policy for commands like `rm -rf ~`.\n- **Writes by child processes** \u2014 a test runner or script writing files is invisible to the\n  session surface, which judges declared tool calls only. Say so to the user; the commit\n  surface will still see the result as a staged diff.\n\n### 4a. Expressible now \u2014 register a judged entry\n\nAdd the entry to the `disciplines:` array in `polydeukes.config.yaml`. Advise is the default\nlanding \u2014 a break is recorded as `advised` and the call goes on \u2014 and the `enforce: advise`\nline below only spells that default out. NEVER write `enforce: block` from this skill:\npromotion to block is the user's own choice, made after the advise measurements have been\nread.\n\nThe examples below are whole documents, so `languages:` \u2014 the schema's one required block \u2014\nappears alongside the entry; in a config that already has one, copy the entry only.\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'no-focused-tests'\n    why: 'a committed .only silently shrinks the suite to one test'\n    declare:\n      mechanism: 'added-only'\n      scope: { source: 'target.path', include: ['^src/'] }\n      supply: { pre: 'empty', post: 'empty' }\n      extract:\n        before:\n          - { op: 'source', of: 'pre' }\n          - { op: 'lines' }\n          - { op: 'keyByPattern', re: '(\\.only\\()' }\n        after:\n          - { op: 'source', of: 'post' }\n          - { op: 'lines' }\n          - { op: 'keyByPattern', re: '(\\.only\\()' }\n        added:\n          - { op: 'onlyIn', of: 'after', notIn: 'before' }\n      relate:\n        - id: 'nothing-added'\n          relation: { op: 'empty', of: 'added' }\n          message: 'adds {key}: {value}'\n    enforce: advise\n```\n\nA command-line ban reads the fixed source `command` and scopes on it \u2014 the scope is part of\nthe mechanism's shape, so a `forbidden-command` entry without it is refused at load time:\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'no-force-push'\n    why: 'a force push rewrites history nobody reviewed'\n    declare:\n      mechanism: 'forbidden-command'\n      scope: { source: 'command' }\n      extract:\n        hits:\n          - { op: 'source', of: 'command' }\n          - { op: 'lines' }\n          - { op: 'matches', re: 'git push\\\\b.*--force(?![\\\\w-])' }\n      relate:\n        - { id: 'no-force', relation: { op: 'empty', of: 'hits' }, message: '{value}' }\n    enforce: advise\n```\n\n**Write the regex yourself \u2014 the user states the promise, you author the pattern.** The\npattern is the part users find hardest, so never hand the prose back and ask for one. Three\nauthoring traps, each measured on a live config:\n\n- **A pattern answers a syntactic question only.** \"Is this string a forbidden word\" is\n  syntax; \"is this a new dependency version\" is meaning, and a regex leaks both ways on a\n  semantic question. When the question is semantic, narrow the declaration's own `scope`\n  block to the files where any match IS a break, or accept \"editing this file at all\" as\n  the trigger.\n- **`^` means what the preceding step left.** After a `lines` step a declaration's\n  pattern sees one line at a time, so `^` anchors to that line; over an unsplit source it\n  anchors to the whole text and matches the first line only. A ban over the command line\n  puts `lines` before its `matches` for exactly that reason.\n- **Author both directions.** Before registering, write down one string the pattern must\n  match and one nearby string it must not (`only(` vs `only_helper(`, a flag vs its\n  substring). A pattern checked in only the breaking direction over-fires in review-proof\n  ways.\n\n### 4b. Not expressible yet \u2014 register a draft\n\nA draft is prose with a handle: `id`, `why`, and the literal marker `draft: true` \u2014 no other\nkeys. It produces no judgment and no telemetry; `pdks explain` lists it as unpromoted.\nRecord the SHAPE of the promise inside `why`, so the promotion destination is already\nwritten down when a later engine can express it. Name the shape in these terms:\n\n| Shape | The promise reads like |\n| --- | --- |\n| pairing | every element of set A has a counterpart in set B (translation keys, i18n) |\n| companion | if X appears in a unit, Y must appear with it |\n| ordered | a sequence must keep its order (migration journals, version ladders) |\n| fingerprint | a derived artifact must match the hash/stamp of its source |\n| producer-owned | only a designated generator may write this artifact |\n| self-absolution | the party being judged must not write its own verdict field |\n| actor-scope | the same action is fine for one actor and a break for another |\n| phase-order | several precedents, in a fixed order |\n| turn-locality | the evidence must be in the same turn or time window |\n| stated-ground | the reason must be written down before the action |\n| controlled-vocabulary | only an enumerated set of words/values is allowed |\n| naming-convention | names must match a pattern per kind |\n| irreversible-marker | once present, a marker may never be removed |\n| delegation-scope | a delegated task may touch only its granted scope |\n| scope-valve | a defined exception valve, judged rather than ad hoc |\n| claim-verification | the claim must be re-run/measured, not trusted |\n\n```yaml\nlanguages:\n  placeholder:\n    productionGlob: 'src/**'\n    testCmd: 'echo \"set a verification command for {scope}\"'\ndisciplines:\n  - id: 'locale-files-move-together'\n    why: 'pairing \u2014 en.json and ko.json must change in the same commit; one side alone is a break'\n    draft: true\n```\n\n### 5. Prove it fires, then close\n\nRun `pdks explain` and confirm the new entry is listed (a judged entry with its mechanism\nand surfaces; a draft as unpromoted).\n\nFor a judged entry, registration is not the finish \u2014 a pattern that never fires protects\nnothing while looking installed. Fire it once for real, with the proof run the declaration's\nown mechanism can actually reach:\n\n| Mechanism | Break it once | The entry's id shows up in |\n| --- | --- | --- |\n| a file-reading one (`added-only`, `naming`, \u2026) | one scratch edit matching the must-match direction | `pdks covenant check --worktree` output \u2014 the exit stays 0 at advise, the id is the proof |\n| `forbidden-command` | run one harmless command matching the pattern | the telemetry log tail \u2014 at advise the call proceeds and its row records the id |\n| `precedent` | one in-scope edit made without the required precedent | the telemetry log tail \u2014 a declaration reading the session judges on the session surface only (the commit surface has none, so its `supply` policy records it `skipped`) |\n\nThen undo the scratch break, repeat the same run, and confirm silence on the\nmust-NOT-match direction. Close by telling the user which rung the entry landed on and\nthat `enforce: block` is theirs to add later if the advise record earns it.\n\n## Reading the advise record\n\nAn `advised` row means a promise was broken and the call went through anyway. Rows land in\nthe telemetry log at the path configured by `telemetry.logPath` (default\n`.polydeukes/roi.log`). The hook's stderr note is not shown to you, so consult the log at\ntask boundaries: before committing, or after a batch of edits, read the tail and act on any\n`advised` row \u2014 fix the break, or tell the user why it should stand. An advisory nobody\nreads measures nothing.\n";
+/** `initClaudeCode` input — the target tree and the preflight seam. */
 export type InitClaudeCodeSpec = {
     /** Project root to install into — every write below is relative to it. */
     projectRoot: string;
     /**
-     * §3-g preflight seam: throws when the package cannot be resolved from the given root.
+     * Preflight seam: throws when the package cannot be resolved from the given root.
      * ABSENT uses the real resolution, anchored at that root and nowhere else — anchoring it
      * at the installer's own module would answer for the installer's install graph rather
      * than the target project's, which is precisely the case that must fail.
@@ -29,11 +42,11 @@ export type InitClaudeCodeSpec = {
     resolvePolydeukes?: (projectRoot: string) => void;
 };
 /**
- * Install the session surface into `spec.projectRoot` (DIST-02 §3-a), skipping whatever is
- * already there and reporting both halves per artifact.
+ * Install the session surface into `spec.projectRoot`, skipping whatever is already there
+ * and reporting both halves per artifact.
  *
- * Throws before any write when the package cannot be resolved from that root (§3-g) or when
- * two config spellings already coexist there (§3-a third disposition) — both leave zero
- * files. Translating a throw into exit 2 with the install command is the bin's job.
+ * Throws before any write when the package cannot be resolved from that root or when two
+ * config spellings already coexist there — both leave zero files. Translating a throw into
+ * exit 2 with the install command is the bin's job.
  */
 export declare function initClaudeCode(spec: InitClaudeCodeSpec): ScaffoldReport;