dsh-novel-write-engine 0.1.1 → 0.1.3

package/briefs/P3.md

@@ -10,6 +10,10 @@
 - 不写 Markdown：禁 `#`、`**`、`---`、`>`、表格。
 - 不写「Day 1」「第X卷」「读者」「作者」这类出戏标签。
 
+## 上下文
+
+P3 brief 的 `context.world_plan` 是 P1 的本章约束；`context.characters` 是本章活跃角色的完整档案，`context.other_characters` 只是压缩索引。先读 `world_plan` 与 `characters` 再落笔；不要在正文里临时发明未申报的世界规则或人物。
+
 ## 写法
 
 1. 一段一个信息点。先动作，后反应，最后才允许一句心理。

package/briefs/P4.md

@@ -70,5 +70,8 @@
 
 - `blocker` 必须修；`advisory` 可改可不改。
 - 每条 issue 写清 `problem` 与 `fix`，fix 要是可执行动作。
+- `dimension` 必须是本任务书十五维之一（`R-W-01`…`R-W-15` 的实际集合）；`location` 必须是「第 N 段」，且 N 在本章实际段落范围内。
+- `blocker` 不能在 P4 或 P5 标记为 `waived`；只能修好后带正文证据标记 `fixed`。
+- 判断不了是否「作者故意」时，先按普通问题处理；0.1.3 不提供自动豁免。
 
 完成后：仍有 blocker → P5 修订；全部清零 → P6 校验。

package/briefs/P5.md

@@ -5,9 +5,10 @@
 ## 规则
 
 1. 每条 `blocker` issue 必须变成 `fixed`，并给 `evidence`——修订后正文里的**逐字引用**，引擎会回查。
-2. `blocker` 不许 `waived`；只有 advisory 可以带理由豁免。
-3. 改完字数仍要 ≥ {{min_words}}，格式要求同 P3。
-4. 改动会抬高或压低评分时，不要自己改分；下一轮 P4 重新评。
+2. `issues` 里只能改 `status` 与 `evidence`；`dimension`、`location`、`problem`、`fix`、`severity` 是评审归属，改写会被拒绝。新发现留到下一轮 P4。
+3. `blocker` 不许 `waived`；只有 advisory 可以带理由豁免。
+4. 改完字数仍要 ≥ {{min_words}}，格式要求同 P3。
+5. 改动会抬高或压低评分时，不要自己改分；下一轮 P4 重新评。
 
 ## 提交
 

package/briefs/P6.md

@@ -33,8 +33,14 @@
 
 ## 判定
 
+- 调用时可以传 `scope`：默认 `["content","integrity"]`；只跑 `content` 或只跑 `integrity` 是合法的，空数组/未知值会被拒绝。只跑一类时另一类规则不参与本次 check，但**不会**进入 `ready_to_archive`：管线停在 P6 并返回 `CHECK_SCOPE_PARTIAL`，必须再跑一次完整 scope。
+- 完整 scope 全过 → 管线进入 `ready_to_archive`，先 `novel_brief P8` 领取终审任务书，再调用 `novel_archive`。
 - 任一项 `fail` → 校验不过，先重新领取 `novel_brief P6`（check 已改变上下文，旧 digest 会失效），再调用 `novel_revise` 修订并回到 P4 重评（轮次 +1）。
-- 全过 → 管线进入 `ready_to_archive`，先 `novel_brief P8` 领取终审任务书，再调用 `novel_archive`。
+
+## 损坏与恢复
+
+- 如果 `novel_status` 返回 `state_errors` 或 `STATE_UNREADABLE`，不要手改文件；plan/review/check 按 `next` 指向的 `novel_rollback` 回到重建点；八个 ledger 则按 `next` 调 `novel_amend`，先用 `novel_state` 取 raw 文档再提交完整替换。
+- 如果 `novel_archive` 报 review 没有 `review_digest`，回退到 P4 重新 `novel_review`；不要编辑 `state/pipeline.yaml`。
 
 ## 不许做的
 

package/lib/client.js

@@ -102,6 +102,10 @@ window.__ModuleLoader__.load({
 		const stageLabel = (stage) => STAGE_LABELS[stage] ?? stage;
 		const platformLabel = (platform) => PLATFORM_LABELS[platform] ?? platform;
 		const toolLabel = (tool) => TOOL_LABELS[tool] ?? "继续";
+		const volumeLabel = (summary) => {
+			if (summary.volume === void 0) return "";
+			return ` · ${summary.volume_name === void 0 ? `第${summary.volume}卷` : summary.volume_name}${summary.act === void 0 ? "" : ` · ${summary.act}${summary.act_progress === void 0 ? "" : ` ${summary.act_progress}`}`}`;
+		};
 		/**
 		* Project the wire payload into strings. Version mismatch wins over everything
 		* else: a stale panel must never render data from another schema as if it were
@@ -146,14 +150,15 @@ window.__ModuleLoader__.load({
 				};
 			});
 			const scored = rows.filter((row) => row.tone === "ok");
-			const average = scored.length === 0 ? 0 : scored.reduce((sum, row) => sum + row.scoreValue, 0) / scored.length;
+			const rowAverage = scored.length === 0 ? 0 : scored.reduce((sum, row) => sum + row.scoreValue, 0) / scored.length;
+			const average = summary.averageScore !== void 0 && Number.isFinite(summary.averageScore) ? summary.averageScore : rowAverage;
 			const next = summary.next;
 			const finished = summary.finished === true;
 			const doneLabel = summary.stage === "done" ? finished ? "全书完成" : "本章已归档" : stageLabel(summary.stage);
 			return {
 				state: "ready",
 				title: `《${summary.title}》`,
-				subtitle: summary.stage === "done" ? `${summary.genre} · ${platformLabel(summary.platform)} · ${finished ? `共 ${summary.totalChapters} 章` : `下一章 第 ${summary.chapter} 章`}` : `${summary.genre} · ${platformLabel(summary.platform)} · 第 ${summary.chapter} 章`,
+				subtitle: summary.stage === "done" ? `${summary.genre} · ${platformLabel(summary.platform)} · ${finished ? `共 ${summary.totalChapters} 章` : `下一章 第 ${summary.chapter} 章`}${volumeLabel(summary)}` : `${summary.genre} · ${platformLabel(summary.platform)} · 第 ${summary.chapter} 章${volumeLabel(summary)}`,
 				stageLabel: doneLabel,
 				finished,
 				revisionLabel: `第 ${summary.revision} 次修订`,
@@ -577,7 +582,7 @@ window.__ModuleLoader__.load({
 			}, stat("已归档", String(view.stats.chapters), "章"), stat("总字数", view.stats.words.toLocaleString("zh-CN"), "字"), stat("平均评分", view.stats.chapters === 0 ? "—" : String(view.stats.averageScore), "/150"), stat("待处理", String(view.stats.blocking), "项")) : null, view.state === "loading" ? loadingState() : null, view.state === "error" || view.state === "empty" || view.state === "outdated" ? statePanel(view.state, view, loading, onRefresh) : null, ready ? phases(view) : null, ready && view.nextTitle !== "" ? (0, react.createElement)("section", {
 				className: "nwe-next",
 				"aria-label": "下一步"
-			}, (0, react.createElement)("div", { className: "nwe-next-icon" }, arrowIcon()), (0, react.createElement)("div", null, (0, react.createElement)("div", { className: "nwe-next-kicker" }, "NEXT MOVE"), (0, react.createElement)("div", { className: "nwe-next-title" }, view.nextTitle), (0, react.createElement)("div", { className: "nwe-next-detail" }, view.nextDetail)), view.nextTool === "" ? null : (0, react.createElement)("code", { className: "nwe-next-tool" }, view.nextTool)) : null, ready ? (0, react.createElement)("section", { className: "nwe-section" }, (0, react.createElement)("div", { className: "nwe-section-head" }, (0, react.createElement)("h2", { className: "nwe-section-title" }, "章节"), (0, react.createElement)("span", { className: "nwe-section-note" }, `${view.rows.length} 条记录${view.rows.length > 30 ? " · 显示最近 30 条" : ""}`)), view.rows.length === 0 ? (0, react.createElement)("div", {
+			}, (0, react.createElement)("div", { className: "nwe-next-icon" }, arrowIcon()), (0, react.createElement)("div", null, (0, react.createElement)("div", { className: "nwe-next-kicker" }, "NEXT MOVE"), (0, react.createElement)("div", { className: "nwe-next-title" }, view.nextTitle), (0, react.createElement)("div", { className: "nwe-next-detail" }, view.nextDetail)), view.nextTool === "" ? null : (0, react.createElement)("code", { className: "nwe-next-tool" }, view.nextTool)) : null, ready ? (0, react.createElement)("section", { className: "nwe-section" }, (0, react.createElement)("div", { className: "nwe-section-head" }, (0, react.createElement)("h2", { className: "nwe-section-title" }, "章节"), (0, react.createElement)("span", { className: "nwe-section-note" }, `${view.stats.chapters} 条记录${view.stats.chapters > view.rows.filter((row) => row.tone === "ok").length ? ` · 显示最近 ${view.rows.length} 条` : ""}`)), view.rows.length === 0 ? (0, react.createElement)("div", {
 				className: "nwe-empty",
 				style: {
 					marginTop: 12,

package/lib/index.d.ts

@@ -171,6 +171,14 @@ interface CheckDocument {
   };
   verdict: 'pass' | 'fail';
 }
+/** Every persisted document whose damage status/panel can report. */
+type StateErrorCode = 'PROJECT_UNREADABLE' | 'PLAN_UNREADABLE' | 'WORLD_PLAN_UNREADABLE' | 'REVIEW_UNREADABLE' | 'CHECK_UNREADABLE' | 'CHAPTERS_UNREADABLE' | 'CHARACTERS_UNREADABLE' | 'WORLD_UNREADABLE' | 'LOCKS_UNREADABLE' | 'TIMELINE_UNREADABLE' | 'FORESHADOWS_UNREADABLE' | 'RELATIONSHIPS_UNREADABLE' | 'HANDOFF_UNREADABLE';
+/** A state document that exists but cannot be read safely. */
+interface StateError {
+  path: string;
+  code: StateErrorCode;
+  message: string;
+}
 /** Word statistics with the single engine-wide counting rule. */
 interface WordMetrics {
   total_word_count: number;
@@ -497,6 +505,14 @@ interface WorldPlanInput {
   }>;
   continuity_notes: string[];
 }
+/** A character the chapter plan puts on stage; no new persisted schema. */
+interface ChapterCastMember {
+  name: string;
+  entry_state?: string;
+  goal?: string;
+  knowledge?: string[];
+  exit_change?: string;
+}
 /** Chapter plan (`plans/chNNN.chapter.yaml`). */
 interface ChapterPlanInput {
   chapter: number;
@@ -507,6 +523,8 @@ interface ChapterPlanInput {
   opening: string;
   ending: string;
   target_words: [number, number];
+  /** Optional in 0.1.3: older plans remain readable; new plans may name 1–8 actors. */
+  cast?: ChapterCastMember[];
 }
 /** Draft submission payload. */
 interface DraftInput {
@@ -557,6 +575,8 @@ interface GateInput {
   summaryProvided?: boolean;
   review: ReviewDocument | null;
   check: CheckDocument | null;
+  /** When set, result-bearing gates run only the named check scopes. */
+  scope?: string[];
   semantic: SemanticItem[];
   proof: ReadingProof | null;
   rounds: RoundCounters;
@@ -608,7 +628,14 @@ interface StatusReport {
   stage: Stage;
   rounds: RoundCounters;
   blocking: BlockingItem[];
+  /** plan/review/check/ledger files that exist but cannot be read safely. */
+  state_errors: StateError[];
   metrics: WordMetrics | null;
+  /** Inherited handoff labels; absent before the first archive. */
+  volume?: number;
+  volume_name?: string;
+  act?: string;
+  act_progress?: string;
   next: {
     tool: string;
     args: Record<string, unknown>;
@@ -623,6 +650,7 @@ interface AdviceReport {
   args: Record<string, unknown>;
   reason: string;
   blocking: BlockingItem[];
+  state_errors: StateError[];
 }
 /** One history row derived from the journal. */
 interface AuditRow {
@@ -863,6 +891,10 @@ interface PanelSnapshot {
     check: number;
   };
   blocking: BlockingItem[];
+  volume?: number;
+  volume_name?: string;
+  act?: string;
+  act_progress?: string;
   /** Recommended next action; lets the panel explain a stage with no blockers. */
   next?: StatusReport['next'];
   /** True only when the configured total chapter target has been reached. */
@@ -872,6 +904,8 @@ interface PanelSnapshot {
   draft?: PanelDraft | null;
   /** Total words across the index, for the header. */
   totalWords: number;
+  /** Book-wide archived average, not just the panel's capped rows. */
+  averageScore?: number;
   /** The nine-phase strip state, derived from the pipeline stage. */
   phases: Array<{
     id: string;
@@ -890,6 +924,12 @@ interface PanelSummaryDto {
   revision: number;
   totalWords: number;
   totalChapters: number;
+  /** Book-wide archived average; absent on older payloads. */
+  averageScore?: number;
+  volume?: number;
+  volume_name?: string;
+  act?: string;
+  act_progress?: string;
   phases: Array<{
     id: string;
     done: boolean;
@@ -1073,6 +1113,10 @@ interface ExportInput {
 interface StateQueryInput {
   kind: DocKind | 'novel' | 'planWorld' | 'planChapter';
   chapter?: number;
+  /** Chapter index defaults to a compact read; opt in to the full summaries. */
+  include_summary?: boolean;
+  /** Inclusive chapter range for the `chapters` index. */
+  chapter_range?: [number, number];
   root?: string;
 }
 interface WordCountInput {
@@ -1089,6 +1133,8 @@ declare class EngineService {
   private readonly stores;
   private readonly mutex;
   private readonly replay;
+  /** Status, panel and gates ask for the same stage context repeatedly. */
+  private readonly briefContextCache;
   private readonly briefs;
   private readonly now;
   /** The project this process last touched; the panel follows it without a workspace hint. */
@@ -1128,6 +1174,12 @@ declare class EngineService {
     chapter: number;
     stage: Stage;
   }>>;
+  /**
+   * Read-only paths must surface a committed-journal mismatch. The write path
+   * already fails closed; without this, status recommends the next write and
+   * the model only learns about the mismatch when that write aborts.
+   */
+  private journalBlocking;
   getStatus(input?: StatusInput): Promise<OpResult<StatusReport>>;
   countWords(input?: WordCountInput): Promise<OpResult<WordMetrics>>;
   queryState(input: StateQueryInput): Promise<OpResult<unknown>>;
@@ -1140,6 +1192,7 @@ declare class EngineService {
     args: Record<string, unknown>;
     reason: string;
     blocking: BlockingItem[];
+    state_errors: StateError[];
   }>>;
   getBrief(input: BriefInput): Promise<OpResult<{
     stage: string;
@@ -1275,11 +1328,32 @@ declare class EngineService {
     applied: boolean;
   }>>;
   private panelSnapshot;
+  /**
+   * The archive stage has only one legal operation, so a status/panel that
+   * recommends it without checking the same gates as the archive creates a
+   * loop. Evaluate the real archive gates through `gateInput`, then add the
+   * machine pass and semantic evidence that archive re-checks separately.
+   */
+  private archivePreflight;
   private nextStep;
   /** A computed blocker for the retry budget the next operation would consume. */
   private roundsLimitBlock;
   /** Pipeline blockers plus budget exhaustion, so status/panel cannot say "all clear". */
   private effectiveBlocking;
+  /**
+   * A review that exists but cannot be tied to the pipeline digest would let a
+   * hand-edited review pass archive. Archive already fails closed; status and
+   * next must surface the same repair path instead of pointing at the archive
+   * command forever.
+   */
+  private reviewDigestProblem;
+  private stateErrors;
+  /** The earliest rebuild point for the current state damage. */
+  private recoveryFor;
+  /** Never point at a stage later than the current one; rollback only moves backward. */
+  private clampRollbackTarget;
+  /** State damage that makes this operation unsafe to start. */
+  private stateGateBlock;
   /** Whether the stored brief still signs the current snapshot. */
   private briefIsCurrent;
   /** Arguments valid for the tool `STAGE_NEXT` recommends at this stage. */
@@ -1292,10 +1366,20 @@ declare class EngineService {
   private briefContextFor;
   private briefDigest;
   private briefVariables;
+  /**
+   * The one place a gate input is assembled. Archive preflight evaluates the
+   * same object as the real archive, so a gate cannot pass preflight and then
+   * fail the write (the old PG-06/scope holes did exactly that).
+   */
+  private gateInput;
   private assertGates;
   private assertChapterParameter;
   private assertChapter;
   private load;
+  /** A repair may bypass the journal hash only when the document is unreadable. */
+  private stateDocIsUnreadable;
+  /** Read a review/check without letting one corrupt file wedge every read. */
+  private recoverableDoc;
   private mutate;
   private invalidateReplay;
   private emptySnapshot;
@@ -1342,4 +1426,4 @@ declare const Config: Schema<Config>;
  * created lazily per project root.
  */
 declare function apply(ctx: Context, config: Config): void;
-export { AdviceReport, ArchiveHandoff, AuditRow, BlockingItem, BriefDocument, BriefLibrary, BriefStage, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, Deduction, DeltaAction, DiffReport, DraftInput, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, HandoffDocument, LocksDocument, MachineMetrics, NovelProject, OPERATIONS, OpResult, Operation, PLATFORMS, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ReviewDocument, ReviewInput, ReviewIssue, RevisionInput, RoundCounters, SCENE_TYPES, SCHEMA_VERSION, SceneType, ScoreDimension, SemanticItem, Severity, Stage, StateDelta, StatusReport, TimelineDelta, TimelineDocument, Violation, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, verifyReference };
+export { AdviceReport, ArchiveHandoff, AuditRow, BlockingItem, BriefDocument, BriefLibrary, BriefStage, ChapterCastMember, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, Deduction, DeltaAction, DiffReport, DraftInput, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, HandoffDocument, LocksDocument, MachineMetrics, NovelProject, OPERATIONS, OpResult, Operation, PLATFORMS, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ReviewDocument, ReviewInput, ReviewIssue, RevisionInput, RoundCounters, SCENE_TYPES, SCHEMA_VERSION, SceneType, ScoreDimension, SemanticItem, Severity, Stage, StateDelta, StateError, StateErrorCode, StatusReport, TimelineDelta, TimelineDocument, Violation, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, verifyReference };