novel-writer-cli 0.0.1

package/schemas/platform-profile.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "title": "platform-profile.json",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "platform",
+    "created_at",
+    "word_count",
+    "hook_policy",
+    "info_load",
+    "compliance",
+    "scoring"
+  ],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^_.*$": { "$ref": "#/$defs/comment_value" }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema pointer for editor tooling. Example: schemas/platform-profile.schema.json"
+    },
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Schema version of platform-profile.json (SSOT in schemas/platform-profile.schema.json)."
+    },
+    "platform": {
+      "type": "string",
+      "enum": ["qidian", "tomato"],
+      "description": "Immutable platform binding chosen at init."
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when the profile was created."
+    },
+
+    "word_count": { "$ref": "#/$defs/word_count_policy" },
+    "hook_policy": { "$ref": "#/$defs/hook_policy" },
+    "info_load": { "$ref": "#/$defs/info_load_policy" },
+    "compliance": { "$ref": "#/$defs/compliance_policy" },
+    "scoring": { "$ref": "#/$defs/scoring_policy" },
+
+    "retention": { "$ref": "#/$defs/retention_policy" },
+    "readability": { "$ref": "#/$defs/readability_policy" },
+    "naming": { "$ref": "#/$defs/naming_policy" }
+  },
+  "$defs": {
+    "comment_value": {
+      "description": "Allows _comment/_note style metadata fields for human readability.",
+      "type": ["string", "number", "integer", "boolean", "object", "array", "null"]
+    },
+    "severity_policy": {
+      "type": "string",
+      "enum": ["warn", "soft", "hard"],
+      "description": "warn: advisory; soft: requires revision unless overridden; hard: blocks progression when enabled."
+    },
+    "genre_drive_type": {
+      "type": "string",
+      "enum": ["plot", "character", "suspense", "slice_of_life"]
+    },
+    "word_count_policy": {
+      "type": "object",
+      "required": ["target_min", "target_max", "hard_min", "hard_max"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "target_min": { "type": "integer", "minimum": 0 },
+        "target_max": { "type": "integer", "minimum": 0 },
+        "hard_min": { "type": "integer", "minimum": 0 },
+        "hard_max": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "hook_policy": {
+      "type": "object",
+      "required": ["required", "min_strength", "allowed_types", "fix_strategy"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "required": { "type": "boolean" },
+        "min_strength": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "allowed_types": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "fix_strategy": {
+          "type": "string",
+          "enum": ["hook-fix"],
+          "description": "Bounded enum; unknown values MUST fail validation."
+        }
+      }
+    },
+    "info_load_policy": {
+      "type": "object",
+      "required": ["max_new_entities_per_chapter", "max_unknown_entities_per_chapter", "max_new_terms_per_1k_words"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "max_new_entities_per_chapter": { "type": "integer", "minimum": 0 },
+        "max_unknown_entities_per_chapter": { "type": "integer", "minimum": 0 },
+        "max_new_terms_per_1k_words": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "compliance_policy": {
+      "type": "object",
+      "required": ["banned_words", "duplicate_name_policy"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "banned_words": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "duplicate_name_policy": { "$ref": "#/$defs/severity_policy" },
+        "script_paths": {
+          "type": "object",
+          "description": "Optional mapping for deterministic linters (tool_name -> relative path).",
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "scoring_policy": {
+      "type": "object",
+      "required": ["genre_drive_type", "weight_profile_id"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "genre_drive_type": { "$ref": "#/$defs/genre_drive_type" },
+        "weight_profile_id": { "type": "string", "minLength": 1 },
+        "weight_overrides": {
+          "type": "object",
+          "description": "Optional per-dimension weight overrides (dimension_name -> weight).",
+          "additionalProperties": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "retention_policy": {
+      "type": ["object", "null"],
+      "required": ["title_policy", "hook_ledger"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "title_policy": { "$ref": "#/$defs/title_policy" },
+        "hook_ledger": { "$ref": "#/$defs/hook_ledger_policy" }
+      }
+    },
+    "title_policy": {
+      "type": "object",
+      "required": ["enabled", "min_chars", "max_chars", "forbidden_patterns", "auto_fix"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "min_chars": { "type": "integer", "minimum": 0 },
+        "max_chars": { "type": "integer", "minimum": 0 },
+        "forbidden_patterns": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "required_patterns": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "auto_fix": { "type": "boolean" }
+      }
+    },
+    "hook_ledger_policy": {
+      "type": "object",
+      "required": [
+        "enabled",
+        "fulfillment_window_chapters",
+        "diversity_window_chapters",
+        "max_same_type_streak",
+        "min_distinct_types_in_window",
+        "overdue_policy"
+      ],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "fulfillment_window_chapters": { "type": "integer", "minimum": 1 },
+        "diversity_window_chapters": { "type": "integer", "minimum": 1 },
+        "max_same_type_streak": { "type": "integer", "minimum": 1 },
+        "min_distinct_types_in_window": { "type": "integer", "minimum": 1 },
+        "overdue_policy": { "$ref": "#/$defs/severity_policy" }
+      }
+    },
+    "readability_policy": {
+      "type": ["object", "null"],
+      "required": ["mobile"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "mobile": { "$ref": "#/$defs/mobile_readability_policy" }
+      }
+    },
+    "mobile_readability_policy": {
+      "type": "object",
+      "required": ["enabled", "max_paragraph_chars", "max_consecutive_exposition_paragraphs", "blocking_severity"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "max_paragraph_chars": { "type": "integer", "minimum": 1 },
+        "max_consecutive_exposition_paragraphs": { "type": "integer", "minimum": 1 },
+        "blocking_severity": { "type": "string", "enum": ["hard_only", "soft_and_hard"] }
+      }
+    },
+    "naming_conflict_type": {
+      "type": "string",
+      "enum": ["duplicate", "near_duplicate", "alias_collision"]
+    },
+    "naming_policy": {
+      "type": ["object", "null"],
+      "required": ["enabled", "near_duplicate_threshold", "blocking_conflict_types"],
+      "additionalProperties": false,
+      "patternProperties": { "^_.*$": { "$ref": "#/$defs/comment_value" } },
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "near_duplicate_threshold": { "type": "number", "minimum": 0, "maximum": 1 },
+        "blocking_conflict_types": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/naming_conflict_type" },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "exemptions": {
+          "type": "object",
+          "description": "Optional whitelist/exemptions for intentional overlaps.",
+          "additionalProperties": true
+        }
+      }
+    }
+  }
+}

package/schemas/promise-ledger.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "title": "promise-ledger.json",
+  "type": "object",
+  "required": ["schema_version", "entries"],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^_.*$": { "$ref": "#/$defs/comment_value" }
+  },
+  "propertyNames": {
+    "not": { "enum": ["__proto__", "constructor", "prototype"] }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema pointer for editor tooling. Example: schemas/promise-ledger.schema.json"
+    },
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Schema version of promise-ledger.json (SSOT in schemas/promise-ledger.schema.json)."
+    },
+    "policy": { "$ref": "#/$defs/promise_ledger_policy" },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/promise_ledger_entry" }
+    }
+  },
+  "$defs": {
+    "comment_value": {
+      "description": "Free-form comment fields supported by templates/specs.",
+      "type": ["string", "number", "boolean", "null", "object", "array"]
+    },
+    "promise_ledger_policy": {
+      "type": "object",
+      "required": ["dormancy_threshold_chapters"],
+      "additionalProperties": false,
+      "properties": {
+        "dormancy_threshold_chapters": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Warn when chapters_since_last_touch >= dormancy_threshold_chapters."
+        }
+      }
+    },
+    "promise_ledger_entry": {
+      "type": "object",
+      "required": ["id", "type", "promise_text", "status", "introduced_chapter", "last_touched_chapter"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^_.*$": { "$ref": "#/$defs/comment_value" }
+      },
+      "propertyNames": {
+        "not": { "enum": ["__proto__", "constructor", "prototype"] }
+      },
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": {
+          "type": "string",
+          "enum": ["selling_point", "core_mystery", "mechanism", "relationship_arc"]
+        },
+        "promise_text": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Short, non-spoiler description of the promise."
+        },
+        "status": { "type": "string", "enum": ["promised", "advanced", "delivered"] },
+        "introduced_chapter": { "type": "integer", "minimum": 1 },
+        "last_touched_chapter": { "type": "integer", "minimum": 1 },
+        "delivered_chapter": { "type": ["integer", "null"], "minimum": 1 },
+        "links": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "hook_entry_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+            "foreshadowing_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+          }
+        },
+        "history": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["chapter", "action"],
+            "additionalProperties": false,
+            "properties": {
+              "chapter": { "type": "integer", "minimum": 1 },
+              "action": { "type": "string", "minLength": 1 },
+              "note": { "type": "string" },
+              "at": { "type": "string", "format": "date-time" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/calibrate-quality-judge.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+#
+# QualityJudge calibration against human-labeled dataset (M3).
+#
+# Usage:
+#   calibrate-quality-judge.sh --project <novel_project_dir> --labels <labels.jsonl> [--out <report.json>]
+#
+# Output:
+#   stdout JSON (exit 0 on success)
+#
+# Exit codes:
+#   0 = success (valid JSON emitted to stdout)
+#   1 = validation failure (bad args, missing files, invalid JSON)
+#   2 = script exception (unexpected runtime error)
+#
+# Notes:
+# - Aligns by chapter number.
+# - Uses judge `overall_final` when available; falls back to `overall`.
+
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  calibrate-quality-judge.sh --project <novel_project_dir> --labels <labels.jsonl> [--out <report.json>]
+
+Options:
+  --project <dir>   Novel project directory (must contain evaluations/)
+  --labels <file>   JSONL labels file (eval/datasets/**/labels-YYYY-MM-DD.jsonl)
+  --out <file>      Optional: write report JSON to file (directories created)
+  -h, --help        Show help
+EOF
+}
+
+project_dir=""
+labels_path=""
+out_path=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --project)
+      [ "$#" -ge 2 ] || { echo "calibrate-quality-judge.sh: error: --project requires a value" >&2; exit 1; }
+      project_dir="$2"
+      shift 2
+      ;;
+    --labels)
+      [ "$#" -ge 2 ] || { echo "calibrate-quality-judge.sh: error: --labels requires a value" >&2; exit 1; }
+      labels_path="$2"
+      shift 2
+      ;;
+    --out)
+      [ "$#" -ge 2 ] || { echo "calibrate-quality-judge.sh: error: --out requires a value" >&2; exit 1; }
+      out_path="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "calibrate-quality-judge.sh: unknown arg: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$project_dir" ] || [ -z "$labels_path" ]; then
+  echo "calibrate-quality-judge.sh: --project and --labels are required" >&2
+  usage
+  exit 1
+fi
+
+if [ ! -d "$project_dir" ]; then
+  echo "calibrate-quality-judge.sh: project dir not found: $project_dir" >&2
+  exit 1
+fi
+
+if [ ! -f "$labels_path" ]; then
+  echo "calibrate-quality-judge.sh: labels file not found: $labels_path" >&2
+  exit 1
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "calibrate-quality-judge.sh: python3 is required but not found" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+python3 "$SCRIPT_DIR/lib/calibrate_quality_judge.py" "$project_dir" "$labels_path" "$out_path"
+

package/scripts/compare-regression-runs.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+#
+# Compare two archived regression runs (M3).
+#
+# Usage:
+#   compare-regression-runs.sh <run_dir_a> <run_dir_b> [--out <delta.json>]
+#
+# Output:
+#   stdout JSON (exit 0 on success)
+#
+# Exit codes:
+#   0 = success (valid JSON emitted to stdout)
+#   1 = validation failure (bad args, missing files, invalid JSON)
+#   2 = script exception (unexpected runtime error)
+
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  compare-regression-runs.sh <run_dir_a> <run_dir_b> [--out <delta.json>]
+
+Notes:
+  - Expects each run dir to contain summary.json (generated by scripts/run-regression.sh).
+EOF
+}
+
+out_path=""
+
+if [ "$#" -lt 2 ]; then
+  usage
+  exit 1
+fi
+
+run_a="$1"
+run_b="$2"
+shift 2
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --out)
+      [ "$#" -ge 2 ] || { echo "compare-regression-runs.sh: error: --out requires a value" >&2; exit 1; }
+      out_path="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "compare-regression-runs.sh: unknown arg: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [ ! -d "$run_a" ]; then
+  echo "compare-regression-runs.sh: run_dir_a not found: $run_a" >&2
+  exit 1
+fi
+if [ ! -d "$run_b" ]; then
+  echo "compare-regression-runs.sh: run_dir_b not found: $run_b" >&2
+  exit 1
+fi
+
+summary_a="$run_a/summary.json"
+summary_b="$run_b/summary.json"
+
+if [ ! -f "$summary_a" ]; then
+  echo "compare-regression-runs.sh: missing summary.json: $summary_a" >&2
+  exit 1
+fi
+if [ ! -f "$summary_b" ]; then
+  echo "compare-regression-runs.sh: missing summary.json: $summary_b" >&2
+  exit 1
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "compare-regression-runs.sh: python3 is required but not found" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+python3 "$SCRIPT_DIR/lib/compare_regression_runs.py" "$summary_a" "$summary_b" "$out_path"
+

package/scripts/lib/_common.py

@@ -0,0 +1,131 @@
+"""Shared utilities for M3 evaluation/regression scripts.
+
+Imported by calibrate_quality_judge.py, run_regression.py, compare_regression_runs.py.
+"""
+
+import json
+import math
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Low-level helpers
+# ---------------------------------------------------------------------------
+
+def die(msg: str, exit_code: int = 1) -> None:
+    sys.stderr.write(msg.rstrip() + "\n")
+    raise SystemExit(exit_code)
+
+
+def load_json(path: str, *, missing_ok: bool = False) -> Any:
+    """Load JSON file.  Returns None on missing when *missing_ok*."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        if missing_ok:
+            return None
+        raise
+
+
+def as_float(value: Any) -> Optional[float]:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        v = float(value)
+        return v if math.isfinite(v) else None
+    return None
+
+
+def as_int(value: Any) -> Optional[int]:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return int(value)
+    return None
+
+
+def as_str(value: Any) -> Optional[str]:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def iso_utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+# ---------------------------------------------------------------------------
+# Eval-object extraction (QualityJudge output format)
+# ---------------------------------------------------------------------------
+
+def extract_eval_used(eval_obj: Dict[str, Any]) -> Dict[str, Any]:
+    maybe = eval_obj.get("eval_used")
+    return maybe if isinstance(maybe, dict) else eval_obj
+
+
+def extract_overall(eval_obj: Dict[str, Any]) -> Optional[float]:
+    """Extract overall/overall_final with fallback chain."""
+    for v in [
+        eval_obj.get("overall_final"),
+        extract_eval_used(eval_obj).get("overall_final"),
+        extract_eval_used(eval_obj).get("overall"),
+        eval_obj.get("overall"),
+    ]:
+        n = as_float(v)
+        if n is not None:
+            return n
+    meta = eval_obj.get("metadata")
+    if isinstance(meta, dict):
+        judges = meta.get("judges")
+        if isinstance(judges, dict):
+            n = as_float(judges.get("overall_final"))
+            if n is not None:
+                return n
+    return None
+
+
+def extract_dimension_scores(eval_obj: Dict[str, Any]) -> Dict[str, float]:
+    """Extract per-dimension {key: score} from eval object."""
+    used = extract_eval_used(eval_obj)
+    scores = used.get("scores")
+    if not isinstance(scores, dict):
+        scores = eval_obj.get("scores")
+        if not isinstance(scores, dict):
+            return {}
+    out: Dict[str, float] = {}
+    for key, item in scores.items():
+        if not isinstance(item, dict):
+            continue
+        v = as_float(item.get("score"))
+        if v is not None:
+            out[str(key)] = float(v)
+    return out
+
+
+def extract_contract_verification(eval_obj: Dict[str, Any]) -> Dict[str, Any]:
+    used = extract_eval_used(eval_obj)
+    cv = used.get("contract_verification")
+    if isinstance(cv, dict):
+        return cv
+    cv = eval_obj.get("contract_verification")
+    if isinstance(cv, dict):
+        return cv
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# File discovery
+# ---------------------------------------------------------------------------
+
+def find_eval_files(eval_dir: str) -> List[Tuple[int, str]]:
+    """Find chapter-NNN-eval.json in *eval_dir*.  Returns sorted [(chapter, path)]."""
+    if not os.path.isdir(eval_dir):
+        return []
+    items: List[Tuple[int, str]] = []
+    for name in os.listdir(eval_dir):
+        m = re.match(r"^chapter-(\d+)-eval\.json$", name)
+        if m:
+            items.append((int(m.group(1)), os.path.join(eval_dir, name)))
+    items.sort(key=lambda x: x[0])
+    return items