@mstar-harness/engine 3.0.1 → 3.1.1

package/dist/engine.js

@@ -2212,6 +2212,7 @@ function parseFlowArray(raw, filePath) {
 import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "node:fs";
 import { join as join9 } from "node:path";
 var PROJECT_ROADMAP_FILE = "roadmap.md";
+var PROJECT_REFERENCES_DIR = "references";
 var PROJECT_REGISTER_FILE = "residuals.json";
 var _DEFAULT_PROJECT = "_default";
 var ROADMAP_STATUSES = ["active", "paused", "completed"];
@@ -2427,6 +2428,35 @@ function techDebtRollup(projectDir) {
   const overall = "DRIFT";
   return { computed, stored, checks, overall };
 }
+function listProjectReferenceFiles(projectDir) {
+  const root = join9(projectDir, PROJECT_REFERENCES_DIR);
+  let entries;
+  try {
+    entries = readdirSync5(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === PROJECT_ROADMAP_FILE || entry.name === PROJECT_REGISTER_FILE)
+      continue;
+    if (entry.isFile()) {
+      files.push(entry.name);
+    } else if (entry.isDirectory()) {
+      let nested;
+      try {
+        nested = readdirSync5(join9(root, entry.name), { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const child of nested) {
+        if (child.isFile())
+          files.push(`${entry.name}/${child.name}`);
+      }
+    }
+  }
+  return files.sort();
+}
 // src/migrate.ts
 import { copyFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname7, isAbsolute as isAbsolute6, join as join10, relative as relative3, resolve as resolve8, sep as sep2 } from "node:path";
@@ -4615,6 +4645,7 @@ export {
   parseAssignmentBranchForms,
   normalizeSeverity,
   migrateHarnessTree,
+  listProjectReferenceFiles,
   lintStrategySections,
   lintSkillFrontmatter,
   lintLoadOrder,
@@ -4667,6 +4698,7 @@ export {
   QC_REVIEWER_PARAMS,
   PROJECT_ROADMAP_FILE,
   PROJECT_REGISTER_FILE,
+  PROJECT_REFERENCES_DIR,
   NOTES_LEDGER_FILE,
   MSTARC_WORKFLOW_DIR_KEY,
   MSTARC_SECTION,

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export { SddScriptError, assertBaseSha, implementerSessionStickyRules, readProgr
 export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
 export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
 export type { FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
-export { PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, findingsCleanupGate, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
+export { PROJECT_REFERENCES_DIR, PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, findingsCleanupGate, listProjectReferenceFiles, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
 export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, MigrateResult, MigrateRoadmap, MigrateRootV2, MigrateSnapshot, MigrateStep, } from "./migrate.js";
 export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.js";
 export type { CompletenessItem, CompletenessLevel, CompletenessPlaceholder, CompletenessResult, DesignFrontmatter, } from "./design-md.js";

package/dist/project.d.ts

@@ -2,6 +2,8 @@ import { type GateResult, type ValidationResult } from "./core.js";
 import { type ResidualEntry } from "./status.js";
 /** Roadmap file name inside `projects/<id>/` (plan Task 4 — writer contract). */
 export declare const PROJECT_ROADMAP_FILE = "roadmap.md";
+/** Theme-scoped research directory name inside `projects/<id>/` (plan 20260820-project-research-corpus Task 1 — compass ruling 1). */
+export declare const PROJECT_REFERENCES_DIR = "references";
 /** Project register file name inside `projects/<id>/` (plan Task 4). */
 export declare const PROJECT_REGISTER_FILE = "residuals.json";
 /** Fallback project id for project-less flows (plan Task 4 — compass ruling 2). */
@@ -132,3 +134,17 @@ export declare function findingsCleanupGate(register: ProjectRegisterDoc, planId
  * anything.
  */
 export declare function techDebtRollup(projectDir: string): TechDebtRollup;
+/**
+ * List theme-scoped research files under `<projectDir>/references/` (plan
+ * 20260820-project-research-corpus Task 1 — compass ruling 1): top-level
+ * files plus files exactly one subdirectory deep; deeper nesting ignored;
+ * directories never listed; regular files only (`Dirent.isFile()`). Returns
+ * paths relative to the references root with `/` separators, sorted by code
+ * unit. Strays named exactly `roadmap.md` / `residuals.json` at the
+ * references **root** are excluded — project-layer filenames are never
+ * research rows. `projectDir` is the **per-project** directory (the caller
+ * resolves `join(resolveProjectDir(startDir), projectId)`; `_DEFAULT_PROJECT`
+ * is the fallback id), never the projects root. Missing or unreadable
+ * `references/` → `[]`; never throws; never opens a file body.
+ */
+export declare function listProjectReferenceFiles(projectDir: string): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {