@try-works/dsh-recursive-mode 0.1.3 → 0.1.5

package/lib/init-templates.d.ts

@@ -0,0 +1,41 @@
+export interface GitContext {
+    baselineType: string;
+    baselineReference: string;
+    comparisonReference: string;
+    normalizedBaseline: string;
+    normalizedComparison: string;
+    normalizedDiffCommand: string;
+    baseBranch: string;
+    worktreeBranch: string;
+    baseCommit: string;
+    notes: string;
+}
+/**
+ * detect_git_context(): canonical parity. Returns {context, error} — never
+ * throws on missing git; error is surfaced in the worktree template note.
+ */
+export declare function detectGitContext(repoRoot: string): {
+    context: Partial<GitContext>;
+    error: string | null;
+};
+/**
+ * requirements_content(run_id, template, from_issue): byte-identical to the
+ * canonical recursive-init.py function (LF, template flavor in Scope note).
+ */
+export declare function requirementsContent(runId: string, template?: string, fromIssue?: string): string;
+/**
+ * worktree_content(run_id, repo_root, git_context, prefill_error): byte-identical
+ * to the canonical recursive-init.py function.
+ */
+export declare function worktreeContent(runId: string, repoRoot: string, git: Partial<GitContext>, prefillError: string | null): string;
+/**
+ * Later-phase template: required sections (canonical get_artifact_required_
+ * sections) as ## headings + TODO + FAIL gates. Structural scaffold: the phase
+ * author fills each section; lint stays FAIL until Coverage/Approval are set.
+ */
+export declare function laterPhaseContent(runId: string, fileName: string, workflowProfile?: string): string;
+/**
+ * Scaffold dirs under a run (addenda/subagents/router-prompts/evidence + subs).
+ * Mirrors canonical recursive-init.py's ensure_directory sequence.
+ */
+export declare const RUN_SCAFFOLD_DIRS: string[];

package/lib/live-route.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Live recursive board/strip route (SP2 R1): host HTTP + SSE serving the
+ * filesystem fold, keyed per-WORKSPACE. The board/strip read this instead of
+ * useProjection('recursive'); cold resume and every GET are a fresh fs read.
+ *
+ * Keying (creator steer): the client passes its session cwd verbatim; the HOST
+ * resolves the recursive control-plane root server-side (cwd == workspace root,
+ * cwd == subdir, cwd == repo root). Multiple sessions in one workspace collapse
+ * to one fold; a workspace switch shows the new root.
+ *
+ * R9 read-only: GET state + GET events only. No POST/action route; the client
+ * never mutates the host.
+ *
+ * Registration is mountOnce-global because apply() runs PER-SESSION while
+ * WebServer.register throws on a duplicate (kind, path). The first mount wins;
+ * later mounts no-op (the state is per-workspace, so per-session registration
+ * would be both wrong and a crash).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RecursiveProjection } from './types.ts';
+/** API prefix the board/strip fetch. */
+export declare const RECURSIVE_API_PREFIX = "/.recursive/api";
+/** The host seam the route builder needs: root resolution + the fs fold + a revision. */
+export interface RecursiveRouteHost {
+    /**
+     * Resolve the recursive control-plane root. sessionId is PRIMARY (the host
+     * prefers the attached session header cwd — never trusts a client path); cwd
+     * is a fallback hint only while the session is hydrating / for headless callers.
+     */
+    resolveRoot(sessionId: string | undefined, cwd: string): Promise<string | null>;
+    /** Fresh filesystem fold for one workspace root (per-workspace state). */
+    snapshot(root: string): Promise<RecursiveProjection> | RecursiveProjection;
+    /** Monotone revision; bump whenever the fs fold changes (SSE frame + state). */
+    revision(root: string): number;
+}
+/** The state payload the board/strip read. */
+export interface RecursiveStatePayload {
+    root: string | null;
+    projection: RecursiveProjection;
+    revision: number;
+}
+/**
+ * Build the two read-only routes. Returns [state, events] in registration order.
+ * @param host - the resolved-root + fs-fold seam (the RecursiveRuntime adapter).
+ */
+export declare function makeRecursiveRoutes(host: RecursiveRouteHost): readonly {
+    kind: 'exact';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}[];
+export interface WebServerLike {
+    register(route: {
+        kind: string;
+        path: string;
+        handler: unknown;
+    }): () => void;
+}
+/**
+ * mountOnce wrapper for the route registration. Returns the disposer of the
+ * registration (or a no-op for a later mount).
+ * @param packageName - npm package identity (every install source shares it).
+ * @param makeRoutes - builds the routes (called once, on the first mount).
+ * @param webServer - the host webserver service (or a structural fake).
+ */
+export declare function mountRecursiveRoutesOnce(packageName: string, makeRoutes: () => readonly {
+    kind: string;
+    path: string;
+    handler: unknown;
+}[], webServer: WebServerLike): () => void;

package/lib/phase-rules.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Phase rules (R5): canonical parity port of lint-recursive-run.py's
+ * get_artifact_required_sections + workflow/audit constants. Single source of
+ * truth for per-phase required section headings and audit extras; consumed by
+ * initRun templates, renderRecursivePolicy, and the pre-step lint-rules
+ * injection. Values are byte-identical to the canonical linter (recursive-
+ * mode-audit-v2).
+ */
+export declare const CURRENT_WORKFLOW_PROFILE = "recursive-mode-audit-v2";
+export declare const STRICT_WORKFLOW_PROFILE = "recursive-mode-audit-v1";
+export declare const COMPAT_WORKFLOW_PROFILE = "memory-phase8";
+export declare const STRICT_WORKFLOW_PROFILES: Set<string>;
+export declare const LATE_PHASE_ARTIFACTS: string[];
+export declare const AUDITED_PHASE_FILES: Set<string>;
+export declare const PRIOR_RECURSIVE_EVIDENCE_FILES: Set<string>;
+export declare const DIFF_AUDITED_FILES: Set<string>;
+export declare const TRACEABILITY_REQUIRED_FILES: Set<string>;
+export declare const AUDIT_REQUIRED_HEADINGS: string[];
+export declare const DIFF_BASIS_FIELDS: string[];
+/**
+ * get_artifact_required_sections(file_name, workflow_profile): canonical-parity
+ * required section headings for a phase artifact. Defaults to TODO + Coverage
+ * Gate + Approval Gate for unknown files. Audited phases in strict profiles get
+ * the audit headings appended (plus Prior Recursive Evidence Reviewed for the
+ * prior-evidence file set).
+ */
+export declare function getArtifactRequiredSections(fileName: string, workflowProfile?: string): string[];
+/**
+ * Compact lint-rules message for the pre-step injection (R5): this phase's
+ * required sections + phase-specific gate notes, derived from the canonical
+ * artifact-template sections. Kept short enough to prepend as a system-style
+ * reminder without bloating the step context.
+ */
+export declare function phaseLintRulesMessage(fileName: string, workflowProfile?: string): string;

package/lib/policy.d.ts

@@ -3,7 +3,7 @@ import type { EnforcementConfig } from './enforcement.ts';
 export interface PolicyContext {
     worktreeRoot: string;
     runId: string;
-    folded: RecursivePhaseState | null;
+    folded?: RecursivePhaseState | null;
     config?: EnforcementConfig;
 }
 /**

package/lib/runtime.d.ts

@@ -7,7 +7,6 @@ import { type SubagentProviderLike, type RouteDecision, type CapabilityProbe } f
 import { type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference } from './delegation.ts';
 import { type PhaseTransitionIntent, type SessionEventLike, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts';
 import { type EnforcementConfig, type PreStepGateDecision, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts';
-import { type RecursiveEventLike, type RecursiveFoldState } from './projection.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         recursive: RecursiveRuntime;
@@ -154,11 +153,19 @@ export declare class RecursiveRuntime extends Service {
         };
     } | null): Promise<string | null>;
     /**
-     * Emit a recursive/* event into the session whose control-plane root matches
-     * `root` (additive log-only; the projection drives from these). Falls back to
-     * the agent's session when passed, else the session store list.
+     * SP2 R1 route adapter: resolve the control-plane root for the live route.
+     * sessionId PRIMARY — the host looks up the attached session header cwd and
+     * resolves the root from THAT; the client-passed cwd is a fallback hint only
+     * (hydration / headless callers). Two sessions in one workspace collapse to
+     * one root; a subdir cwd resolves up to the workspace root.
      */
-    private emitToSession;
+    resolveRootForRoute(sessionId: string | undefined, cwd: string, sessionsStore?: {
+        get?: (id: string) => {
+            header?: {
+                cwd?: string;
+            };
+        } | undefined;
+    } | null): Promise<string | null>;
     status(runId?: string, agent?: {
         session?: {
             header?: {
@@ -167,8 +174,12 @@ export declare class RecursiveRuntime extends Service {
         };
     } | null): Promise<RecursiveStatusResult | null>;
     /**
-     * Scaffold a run directory with stub artifact headers (no-op if exists).
-     * Returns the run dir + created artifacts.
+     * Scaffold a run directory with FULL per-phase templates (no-op if exists).
+     * 00-requirements.md + 00-worktree.md are byte-identical to canonical
+     * recursive-init.py (incl. git-context prefill); later phases carry every
+     * required section (get_artifact_required_sections) + TODO + FAIL gates.
+     * Also scaffolds addenda/subagents/router-prompts/evidence dirs. Returns the
+     * run dir + created artifacts.
      */
     initRun(runId: string, agent?: {
         session?: {
@@ -196,8 +207,12 @@ export declare class RecursiveRuntime extends Service {
     /** Reopen a LOCKED artifact to DRAFT (delete LockedAt/LockHash, invalidate downstream receipts). */
     private reopenArtifact;
     /**
-     * Lint an artifact for phase-specific issues. Minimal structural checks:
-     * gates present, TODO section, Status field, LockHash consistency.
+     * Lint an artifact with FULL canonical parity: shells out to the vendored
+     * lint-recursive-run.py (byte-identical to canonical) and parses its
+     * [FAIL]/[WARN] lines + Summary counts. `errors` = FAIL lines, `warnings` =
+     * WARN lines, `passed` = no FAIL (WARN-only passes, matching the canonical
+     * non-strict verdict). Falls back to the structural check only if the vendored
+     * script is unavailable (e.g. bundled lib without references/).
      */
     lintArtifact(runId: string, artifact?: string, agent?: {
         session?: {
@@ -227,14 +242,6 @@ export declare class RecursiveRuntime extends Service {
         code: string;
         message: string;
     }): boolean;
-    /** Phase D R1: append a recursive/* event through the host session adapter (worktree-keyed). */
-    emitRecursiveEvent(session: unknown, type: string, data: Record<string, unknown>): void;
-    /** Phase D R2/R9: fold a session log into the worktree-grouped projection. */
-    foldRecursiveProjection(events: readonly RecursiveEventLike[], workspaceRoot?: string): RecursiveFoldState;
-    /** Phase D R2: the registered projection unit (key 'recursive'). */
-    get projectionUnit(): import("@deepseek-ai/dsh-session-projection").ProjectionDefinition<"recursive", RecursiveFoldState>;
-    /** Phase D R9: whether a worktreeRoot is inside the workspace control-plane root. */
-    isInsideWorkspace(worktreeRoot: string, workspaceRoot: string): boolean;
     /** Phase C R7: resolve the enforcement config (strict|advisory, default advisory). */
     get enforcementConfig(): EnforcementConfig;
     setEnforcementConfig(config: unknown): EnforcementConfig;

package/lib/snapshot.d.ts

@@ -0,0 +1,11 @@
+import type { RecursiveProjection, RecursiveRunCard } from './types.ts';
+/**
+ * Fold one run directory into a RecursiveRunCard (the wire shape the board renders).
+ * Runs that no longer exist on disk are omitted (the fs is the source of truth).
+ */
+export declare function foldRunCard(runDir: string, runId: string, worktreeRoot: string): RecursiveRunCard;
+/**
+ * Fold every run under <root>/.recursive/run/ into the projection, grouped by
+ * worktree root then runId. A fresh fs read on every call (cold-resume live).
+ */
+export declare function snapshotWorkspace(root: string): RecursiveProjection;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + recursive_status tool",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -23,7 +23,8 @@
     "cordis.patch.yml",
     "src",
     "preset",
-    "scripts"
+    "scripts",
+    "references"
   ],
   "license": "MIT",
   "dsh": {
@@ -78,7 +79,7 @@
     "zod": "^4.4.3"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsdown",
+    "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
     "bundle": "tsdown",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"

package/preset/recursive/agent.cordis.yml

@@ -33,6 +33,12 @@
 # The recursive workflow realm: per-session isolated RecursiveRuntime service +
 # the recursive_* tools + the /recursive command + the policy prompt section.
 # isolate.recursive keeps `provide('recursive')` from colliding across sessions.
+#
+# R2 (02-to-be-plan.addendum-r4-r2-mount-resolution.md): the server-surface row
+# is a PLACEHOLDER here; scripts/install-preset.js replaces it with an ABSOLUTE
+# file URL into the profile-installed package so its own @deepseek-ai/* imports
+# resolve through the profile flat-fallback junctions (Service identity intact).
+# commands.ts is bundled INTO lib/index.js, so a single row is sufficient.
 - id: recursive-realm
   name: cordis:group
   group: true
@@ -40,10 +46,7 @@
     recursive: true
   config:
     - id: recursive
-      name: '@try-works/dsh-recursive-mode/src/index.ts'
-
-    - id: recursive-command
-      name: '@try-works/dsh-recursive-mode/src/commands.ts'
+      name: '@@RECURSIVE_SERVER_ENTRY@@'
 
 # The recursive:policy prompt section is registered in code (Stage A,
 # src/index.ts via ctx.systemPrompt.section) — see plan-mode's pattern.

package/preset/recursive/preset.yml

@@ -1,3 +1,3 @@
 name: Recursive 模式
-description: recursive-mode 工作流代理：在会话的当前工作区内运行递归工作流（Phase A: status/spec/worktree/init/lock/qa/closeout/addendum/review/scratch + 全局 bootstrap/list/help）。
+description: 'recursive-mode 工作流代理：在会话的当前工作区内运行递归工作流（Phase A: status/spec/worktree/init/lock/qa/closeout/addendum/review/scratch + 全局 bootstrap/list/help）。'
 order: 5

package/references/agents-block.md

@@ -0,0 +1,95 @@
+## recursive-mode bridge
+
+This repository uses `recursive-mode`.
+
+The single canonical workflow spec lives in `/.recursive/RECURSIVE.md`.
+Read that file before starting or resuming any recursive-mode work.
+
+For Codex, the primary AGENTS bridge target is `/.codex/AGENTS.md`.
+If the repo also carries other `AGENTS.md` files, they may mirror this same bridge block.
+
+Bridge guidance only:
+
+- Treat this file as a harness adapter, not as a second workflow spec.
+- If this file conflicts with `/.recursive/RECURSIVE.md`, follow `/.recursive/RECURSIVE.md`.
+- Control-plane docs live under `/.recursive/`.
+- Runs live under `/.recursive/run/<run-id>/`.
+- Durable memory lives under `/.recursive/memory/`.
+- If recursive-mode is invoked in a repo that does not yet contain the `/.recursive/` scaffold, bootstrap it automatically with the supported install script before continuing. Do not require the user to run a separate manual bootstrap step unless no supported runtime is available.
+
+How users can invoke the skill:
+
+- Treat short prompts such as `Implement the run`, `Implement run 75`, `Implement the plan`, `Create a new run based on the plan`, and `Start a recursive run` as valid recursive-mode entry commands.
+- If a run id is given, use that run.
+- If no run id is given and exactly one active/incomplete run exists, resume that run.
+- If the user asks to implement/start based on a plan, create a new run only when a unique source plan or requirements artifact can be identified from repo docs or immediate task context.
+- If the command is ambiguous, ask for the run id or the repo path of the source plan/requirements artifact.
+- Prompts are still commands, not specifications: read the repo docs that define the run before proceeding.
+
+Required recursive-mode audit behavior:
+
+- Audited phases must follow `draft -> audit -> repair -> re-audit -> pass -> lock`.
+- When subagents are unavailable, perform the same audit as `self-audit`; do not weaken or skip it.
+- Delegate audits only when you can provide the full context bundle:
+  - phase name and artifact path
+  - upstream artifact paths reread for the audit
+  - diff basis from `00-worktree.md`
+  - changed file list and targeted code references
+  - phase-specific audit questions/checklist
+- If the context bundle is incomplete, do not delegate; perform the audit yourself and record `Audit Execution Mode: self-audit`.
+- If subagents are available and the context bundle is complete, delegated audit/review is the default path.
+- If subagents are available but the controller still chooses `self-audit`, record a concrete `Delegation Override Reason`.
+- Do not set `Coverage: PASS` or `Approval: PASS` for an audited phase unless the artifact ends with `Audit: PASS`.
+- Record `Subagent Capability Probe` and `Delegation Decision Basis` in every audited phase.
+- If meaningful subagent work contributes to a phase, require a durable action record under `/.recursive/run/<run-id>/subagents/` and verify it against actual files, actual recursive artifacts, and the actual diff before acceptance. For review/audit delegation, prefer a stable reviewed artifact for `Current Artifact`.
+- Store routed assistant output, raw transcripts, stdout/stderr captures, and invocation metadata under `/.recursive/run/<run-id>/evidence/router/`; cite them from action records rather than placing raw transcript Markdown directly under `subagents/`.
+- Store initial routed prompt bundles only under run-scoped paths such as `/.recursive/run/<run-id>/router-prompts/`; do not bootstrap top-level `/.recursive/router-prompts/`.
+- Treat `success: false` or any nonzero routed-assistant exit code as a failed attempt: preserve diagnostics, instruct the bounded routed role to repair owned issues when applicable, rerun the route, then verify the result before acceptance or record an explicit fallback.
+- If delegated work is accepted after main-agent checks reveal issues, record the concrete repair performed after verification; do not accept stale delegated context silently.
+- For Phase 3, declare `TDD Mode: strict|pragmatic`. Strict mode requires RED and GREEN evidence paths. Pragmatic mode requires an explicit exception rationale plus compensating evidence.
+- For Phase 5, declare `QA Execution Mode: human|agent-operated|hybrid`. Human and hybrid require user sign-off. Agent-operated and hybrid require execution metadata plus evidence paths.
+- For delegated review, prefer `recursive-review-bundle` and record `Review Bundle Path` in Phase 3.5 when review is delegated.
+- Treat addenda as authoritative effective inputs. If relevant addenda exist, list them in `Inputs`, re-read them, and reconcile them explicitly.
+- Review bundles should include relevant addenda automatically, and the written review should cite upstream artifacts, relevant addenda, prior recursive evidence, and changed files/code refs from that bundle in the review narrative.
+- Audited phases must include machine-checkable `Requirement Completion Status` entries for every in-scope `R#`; Traceability alone is not enough.
+- `implemented` and `verified` requirement dispositions must cite concrete `Changed Files`, and `verified` also requires distinct verification evidence.
+- `00-worktree.md` is the source of truth for diff basis. Record baseline type/reference, comparison reference, normalized baseline/comparison, and normalized diff command; do not silently substitute a different basis later.
+- Diff audit ignores incidental runtime byproducts such as `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, and `.ruff_cache/` unless the repo intentionally tracks them.
+- Treat Phase 6, Phase 7, and Phase 8 receipts as concise delta receipts that point to final control-plane docs instead of duplicating them.
+- Phase 8 should capture run-local skill usage and update skill memory under `/.recursive/memory/skills/` when the run teaches the repo something durable about skill availability, skill fit, delegated-review quality, or skill-discovery outcomes.
+- If a run needs missing specialized capability, prefer the `find-skills` skill when available. Otherwise use the Skills CLI (`npx skills find`, `npx skills add`, `npx skills check`, `npx skills update`) and record the outcome when skill usage is relevant.
+- When working inside a reusable skill/workflow repo, do not leave committed run residue such as concrete `/.recursive/run/<run-id>/` folders, evidence logs, review bundles, action records, or temp-path references unless they are intentional fixtures or examples.
+
+Useful helpers:
+
+Invoke these helper names from the installed recursive-mode skill directory or the source package checkout:
+
+- `install-recursive-mode`
+- `recursive-init`
+- `recursive-status`
+- `lint-recursive-run`
+- `recursive-review-bundle`
+- `recursive-closeout`
+- `recursive-subagent-action`
+- `recursive-training-grpo`
+- `recursive-training-extract`
+- `recursive-training-phase8-trigger`
+- `recursive-training-sync`
+- `recursive-training-loader`
+- `recursive-training-mcp`
+- `recursive-lock`
+- `verify-locks`
+- `check-reusable-repo-hygiene`
+
+Diff ownership rules:
+
+- Phase 2 owns planned product/worktree scope only.
+- Phase 3, Phase 3.5, and Phase 4 own actual product/worktree drift reconciliation.
+- Phase 6 owns `/.recursive/DECISIONS.md`.
+- Phase 7 owns `/.recursive/STATE.md`.
+- Phase 8 owns `/.recursive/memory/**`.
+- Do not treat later control-plane or memory churn as retroactive invalidation of earlier locked phases.
+
+Locking rule:
+
+- Use `recursive-lock` as the primary supported way to write `Status: LOCKED`, `LockedAt`, and `LockHash`.