@mstar-harness/dsh 3.0.1 → 3.1.1

package/dist/gates/agent-flow.d.ts

@@ -514,6 +514,14 @@ export declare function recordWorkflowVerdict(input: WorkflowVerdictInput): void
  * <id>`), never the harness root — the dir parameter IS the workflow dir
  * (the catalog passes `join(harnessDir, selection.dir)`; the writer appends
  * there via `resolveAgentFlowWriteDir`).
+ *
+ * Large-file reads (plan `20260820-dsh-ledger-tail-read`): ledgers above
+ * `AGENT_FLOW_TAIL_READ_THRESHOLD_BYTES` are read as a bounded latest-first
+ * tail — seek from EOF, aligned to a line boundary, doubling backward until
+ * the window holds `limit` complete lines — so the catalog pays O(window) at
+ * the byte layer instead of parsing every historical line. Both paths feed
+ * the SAME parse funnel below (`ledgerContent` yields a `content` string),
+ * so tail/full parity is structural.
  * @param workflowDir - the workflow dir whose `agent-flow.jsonl` is read.
  * @param limit - explicit window bound: `undefined` → `AGENT_FLOW_DEFAULT_LIMIT`;
  * otherwise `Math.max(0, Math.floor(limit))` — `0` requests the EMPTY window.

package/dist/gates/system-prompt.d.ts

@@ -37,10 +37,13 @@
  *   re-registration, in zero-config and explicit-config deployments alike.
  * - The context provider reuses the catalog's unified machine-summary
  *   source (`buildCatalogSources` — the SAME builder the engine-status
- *   pre-step catalog row uses) and projects a BOUNDED subset: watermark +
- *   iteration gate + compact state line. Full catalog content
- *   (residual detail, agent-flow events, knowledge digest, branch/policy
- *   anchors) stays out. v3 (plan `20260819-workflow-dsh-viz` Task 3): the
+ *   pre-step catalog row uses) and projects the SLIM digest (plan
+ *   `20260820-dsh-engine-status-slim` Task 2): the version watermark
+ *   ALWAYS, plus ONE `workflow … | plans: …` line only when the active set
+ *   selects a lifecycle (`state.selection.kind === 'active'`). Harness dir
+ *   and enforcement live in `mstar:harness-rules`; residuals / leases /
+ *   direction / iteration-gate detail stay exclusive to the pre-step row.
+ *   v3 (plan `20260819-workflow-dsh-viz` Task 3): the
  *   digest reads ONLY the catalog row (`state` — itself aggregated from the
  *   SELECTED workflow snapshot + project registers) — no direct
  *   status.json / snapshot file reads to change. The build is TTL-memoized

package/dist/index.js

@@ -4193,7 +4193,7 @@ import { join as join11 } from "node:path";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 
 // src/gates/agent-flow.ts
-import { appendFileSync, existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync7, renameSync as renameSync2, rmdirSync, statSync as statSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { appendFileSync, closeSync, existsSync as existsSync11, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync7, readSync, renameSync as renameSync2, rmdirSync, statSync as statSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join10 } from "node:path";
 
 // src/gates/dispatch.ts
@@ -4812,6 +4812,7 @@ var AGENT_FLOW_FILE = "agent-flow.jsonl";
 var AGENT_FLOW_MAX_EVENTS = 500;
 var AGENT_FLOW_DEFAULT_LIMIT = 50;
 var AGENT_FLOW_SIZE_GATE_BYTES = 64 * 1024;
+var AGENT_FLOW_TAIL_READ_THRESHOLD_BYTES = 64 * 1024;
 var WORKFLOW_LEDGER_MAX_ID_LENGTH = 512;
 var WORKFLOW_LEDGER_MAX_LABEL_LENGTH = 512;
 var WORKFLOW_LEDGER_MAX_NAME_LENGTH = 1024;
@@ -5296,14 +5297,49 @@ function summaryOf(events) {
     return { role, outcome, count };
   }).sort((a, b) => b.count - a.count || a.role.localeCompare(b.role) || a.outcome.localeCompare(b.outcome));
 }
+function ledgerContent(file, n) {
+  const size = statSync5(file).size;
+  if (size <= AGENT_FLOW_TAIL_READ_THRESHOLD_BYTES) {
+    return readFileSync7(file, "utf8");
+  }
+  let windowBytes = AGENT_FLOW_TAIL_READ_THRESHOLD_BYTES;
+  const fd = openSync(file, "r");
+  try {
+    for (;; ) {
+      const start = Math.max(0, size - windowBytes);
+      const buffer = Buffer.alloc(size - start);
+      let read = 0;
+      while (read < buffer.length) {
+        const got = readSync(fd, buffer, read, buffer.length - read, start + read);
+        if (got === 0)
+          break;
+        read += got;
+      }
+      let content = buffer.toString("utf8");
+      if (start > 0) {
+        const firstNewline = content.indexOf(`
+`);
+        content = firstNewline >= 0 ? content.slice(firstNewline + 1) : "";
+      }
+      const completeLines = content.split(`
+`).length - 1;
+      if (start === 0 || completeLines >= n)
+        return content;
+      windowBytes *= 2;
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
 function readAgentFlow(workflowDir, limit) {
   const file = join10(workflowDir, AGENT_FLOW_FILE);
   if (!existsSync11(file)) {
     return { events: [], summary: [] };
   }
+  const n = limit === undefined ? AGENT_FLOW_DEFAULT_LIMIT : Math.max(0, Math.floor(limit));
   let content;
   try {
-    content = readFileSync7(file, "utf8");
+    content = ledgerContent(file, n);
   } catch {
     return null;
   }
@@ -5320,7 +5356,6 @@ function readAgentFlow(workflowDir, limit) {
       continue;
     }
   }
-  const n = limit === undefined ? AGENT_FLOW_DEFAULT_LIMIT : Math.max(0, Math.floor(limit));
   const latestFirst = events.reverse().slice(0, n);
   return {
     events: latestFirst.map(eventView),
@@ -5621,6 +5656,8 @@ function harnessStateSource(harnessDir) {
     const executionPolicy = asRecord(snapshot.execution_policy);
     return {
       selection,
+      workflowType: str(snapshot.type),
+      workflowStatus: str(snapshot.status),
       plans,
       residuals,
       residualFindings,
@@ -5643,6 +5680,8 @@ function harnessStateSource(harnessDir) {
 function selectionErrorState(selection, rollup, harnessDir, compass) {
   return {
     selection,
+    workflowType: null,
+    workflowStatus: null,
     plans: [],
     residuals: [],
     residualFindings: null,
@@ -8087,24 +8126,25 @@ function engineStatusProvider(ctx, resolver, bootHarnessDir) {
     return engineStatusSummary(entry.source);
   };
 }
+var DIGEST_PLAN_CAP = 8;
+function joinCapped(items, cap, separator, render) {
+  const visible = items.slice(0, cap).map(render);
+  if (items.length > cap)
+    visible.push(`+${items.length - cap} more`);
+  return visible.join(separator);
+}
 function engineStatusSummary(source) {
-  const lines = [
-    `mstar engine status: v${source.version} | harness ${stripInterpolationHazard(source.harnessDir ?? "none")} | enforcement ${source.enforcement.hard ? "hard" : "soft"}`
-  ];
-  const iteration = source.iteration;
-  if (iteration !== undefined) {
-    const gate2 = iteration.gate;
-    const codes = gate2.violations.map((v) => v.code).join(", ");
-    lines.push(`iteration ${stripInterpolationHazard(iteration.iterationId)}: gate ${gate2.ok ? "PASS" : `FAIL (${codes})`} | transition ${gate2.transition} | all plans done ${gate2.all_plans_done}`);
-  }
+  const lines = [`mstar engine status: v${source.version}`];
   const state = source.state;
   if (state !== null) {
-    const plans = state.plans.length === 0 ? "none" : state.plans.map((p) => `${stripInterpolationHazard(p.id)}(${stripInterpolationHazard(p.status)})`).join(" ");
-    const residuals = state.residuals.length === 0 ? "none" : state.residuals.map((r) => `${r.severity} ${r.count}`).join(", ");
-    const leases = state.leases.length === 0 ? "none active" : state.leases.map((l) => `${stripInterpolationHazard(l.planId)} → ${stripInterpolationHazard(l.holder)}`).join("; ");
-    lines.push(`plans: ${plans} | residuals: ${residuals} | leases: ${leases}`);
-    if (state.direction !== null)
-      lines.push(`direction: ${stripInterpolationHazard(state.direction)}`);
+    const selection = state.selection;
+    if (selection.kind === "active") {
+      const pending = state.plans.filter((p) => p.status !== "Done");
+      const plans = pending.length === 0 ? "none" : joinCapped(pending, DIGEST_PLAN_CAP, " ", (p) => `${stripInterpolationHazard(p.id)}(${stripInterpolationHazard(p.status)})`);
+      const workflowType = stripInterpolationHazard(state.workflowType ?? "unknown");
+      const workflowStatus = stripInterpolationHazard(state.workflowStatus ?? "unknown");
+      lines.push(`workflow ${stripInterpolationHazard(selection.workflowId)} (${workflowType}) ${workflowStatus} | plans: ${plans}`);
+    }
   }
   return lines.join(`
 `);

package/dist/types.d.ts

@@ -199,6 +199,20 @@ export interface MstarHarnessState {
      * read).
      */
     readonly selection: WorkflowSelectionView;
+    /**
+     * The selected workflow snapshot's top-level `type` (`plan` / `iteration`),
+     * projected loose (`string`) like `HarnessPlanView.status`. ALWAYS-present
+     * nullable scalar (lossless JSON, never omitted): missing/empty → `null`;
+     * `null` on selection error (no snapshot read). Added for the slim
+     * `mstar:engine-status` digest (plan `20260820-dsh-engine-status-slim`).
+     */
+    readonly workflowType: string | null;
+    /**
+     * The selected workflow snapshot's top-level lifecycle `status`
+     * (`running` / `paused`; a terminal word for a stale-but-registered entry,
+     * decision D3). Same ALWAYS-present nullable discipline as `workflowType`.
+     */
+    readonly workflowStatus: string | null;
     /** Registered plan rows (`plan_id`/`id` + `status`), snapshot plans[] order. */
     readonly plans: readonly HarnessPlanView[];
     /** Open `residual_findings` counts by severity (non-zero only). */

package/harness-skills/mstar-plan-artifacts/references/knowledge-and-designs.md

@@ -15,6 +15,7 @@
 | **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap — **跨迭代长期权威** | 产品/API 规范性最高权威；**iteration-start** 由 product/architect 主写 |
 | **`{ITERATION_DIR}`**（可选） | **`<iteration-id>/` package**（`delivery-compass.md` + `guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
 | **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker — **经 `mstar-compound` 结晶** | Agent handoff；**不**在 iteration-start 由 product/architect 新增 |
+| **`{PROJECT_DIR}/<id>/references/`**（可选） | 主题化研究：surveys、epic roadmaps、第三方 notes — **与项目绑定**，非跨迭代 corpora | 项目所有者 / operator；engine 只列文件名，**无 markdown schema** |
 | **`{PLAN_DIR}/`** | 单 plan 主文件、durable gate summary、可选 `residuals/` | 计划执行与长期决策留档 |
 
 
@@ -43,6 +44,14 @@
 - 可选：目录级 `**{KNOWLEDGE_DIR}/AGENTS.md**` 承载命名、维护节奏、与 `{SPECS_DIR}` 的权威边界（Nexus 模式）；harness 宽规则仍以 `mstar-plan-conventions` 与本 reference 为准。
 - 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
 
+## `{PROJECT_DIR}/<id>/references/`（可选·主题化研究语料）
+
+- **物理路径**：`**{PROJECT_DIR}/<id>/references/**`（默认 `{HARNESS_DIR}/projects/<id>/references/`；`.mstarc` `project_dir` 声明时用声明值）。
+- **放什么**：**主题化研究** — surveys、epic roadmaps、第三方 notes，与拥有它的项目（`<id>`）绑定（compass ruling 1）。项目缺失用 `_default`（`{PROJECT_DIR}/_default/references/`）。
+- **不放什么**：冻结规格 / ADR（→ `{SPECS_DIR}/`）；compound 结晶的实现 SSOT（→ `{KNOWLEDGE_DIR}/`）；迭代内 ranking notes 与草稿 spec（→ `{ITERATION_DIR}/<id>/guides|specs/`）。研究**不**迁入这三处 corpora，三处内容也**不**迁入 `references/`。
+- **engine 职责边界**：`listProjectReferenceFiles(projectDir)` 只返回**文件名**（相对路径、`/` 分隔、code-unit 排序；跳过根级 `roadmap.md` / `residuals.json`；缺失目录 → `[]`）；**不**读文件正文，**不**做 markdown schema 校验 — 归属语义是本 reference（技能散文）契约，不是 engine 校验。
+- **历史 dump**：harness 根 `.mstar/references/` 已退役（dogfood 后缺省或仅一行 redirect）；当前路径由 `mstar-project-governance` Scope 表与 `mstar-plan-conventions` `references/artifact-storage-paths.md` 命名。
+
 ## 文件命名
 
 - 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
@@ -74,6 +83,7 @@
 - `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与 project register `entries[<plan-id>]` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
 - `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
 - `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
+- `**{PROJECT_DIR}/<id>/references/**`：偏 **主题化研究**（surveys、epic 备注、第三方 notes），随项目绑定；与 specs / knowledge / iteration guides 职责不混写。
 - review bundle、gate summary、residuals、knowledge、iterations 可互链，但职责不混写。
 
 ---

package/harness-skills/mstar-plan-conventions/references/artifact-storage-paths.md

@@ -20,6 +20,7 @@
 | **workflow notes ledger** | `{HARNESS_DIR}/workflows/<id>/notes.jsonl`（gitignored；append-only 运行时笔记） | `mstar-plan-artifacts`、`mstar-iteration` |
 | **project roadmap** | `.mstar/projects/<id>/roadmap.md`（gitignored；frontmatter `{project_id, title, status, created_at, milestones[]?, residuals_ref?}` + 正文约定） | `mstar-plan-artifacts`、`mstar-iteration` |
 | **project register** | `.mstar/projects/<id>/residuals.json`（gitignored；open residual SSOT：`entries[<plan-id>]` 数组；项目缺失用 `_default`） | `mstar-plan-artifacts`、`mstar-review-qc` |
+| **project references（研究语料）** | `.mstar/projects/<id>/references/`（gitignored；主题化 surveys / epic 备注 / 第三方 notes，与项目绑定；与 `{SPECS_DIR}` / `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` 不同） | `mstar-project-governance`、`mstar-plan-artifacts` |
 | **迭代 package** | `.mstar/iterations/<iteration-id>/`（gitignored；`delivery-compass.md`、`guides/`、`specs/`、可选 `README.md`） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读；默认排除 compass） |
 | **迭代索引** | `.mstar/iterations/README.md`（gitignored；一行 = 一次迭代） | `mstar-iteration`（读写） |
 | **规格** | `{HARNESS_DIR}/specs/`（默认 tracked；解析见 `mstar-plan-conventions`） | `mstar-plan-artifacts` |

package/harness-skills/mstar-project-governance/SKILL.md

@@ -19,6 +19,7 @@ description: Morning Star 项目治理层约定 —— `projects/<id>/roadmap.md
 |------|------|
 | `roadmap.md` | 项目方向与目标（frontmatter machine-checkable + body 约定） |
 | `residuals.json` | 项目 register：open residual 的 **SSOT**（`entries[<plan-id>]` 数组） |
+| `references/` | 主题化研究语料（surveys / epic 备注 / 第三方 notes）。与 `{SPECS_DIR}`（冻结规格/ADR）、`{KNOWLEDGE_DIR}`（compound 结晶实现 SSOT）、`{ITERATION_DIR}`（迭代 package）**不同**；engine 只列文件名（`listProjectReferenceFiles`），**不做** markdown schema 校验 |
 
 - **`_default` 回退**：无项目流程（未指定 project id 的 plan / 单 plan / hotfix）落到 **`projects/_default/`**（engine `_DEFAULT_PROJECT`）。项目归属由 plan 的 project id 决定；未归属即 `_default`。
 - 本 skill 的 schema 事实与 **`packages/engine/src/project.ts`** 逐字一致（`validateRoadmap` / `validateProjectRegister` / `findingsCleanupGate` / `techDebtRollup`）；技能文本是语义 SSOT，engine 是确定性校验。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/dsh",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "description": "Morning Star harness dsh (DeepSeek Harness) cordis function plugin — in-process engine gates (status/dispatch/lease) with hard refusal channels.",
   "keywords": [
     "dsh",