fix: support memory fragment type and gracefully format validation errors

CHANGELOG.md

@@ -6,7 +6,6 @@
 * add `build --check` to verify vendor files are in sync ([275fe1b](https://github.com/jessn-dev/agentic-scope/commit/275fe1b3ecef9af9cc0365b347125ef99b054552))
 
 # [1.0.0](https://github.com/jessn-dev/agentic-scope/compare/v0.2.1...v1.0.0) (2026-06-24)
-
 First stable release: the CLI surface, MCP tool surface, and manifest schema are
 now stable and versioned under SemVer. Cut as a **major** because the vendor-file
 output format changed (see Changed).

src/cli.ts

@@ -2,11 +2,26 @@
 import { Command } from "commander";
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { ZodError } from "zod";
 import { loadManifest, MANIFEST_FILENAME, isProject } from "./core/manifest.js";
 import { pack, renderPack, oversizedFragments } from "./core/fragments.js";
 import { build, checkBuild, VENDOR_TARGETS, resolveTargets } from "./core/vendor.js";
 import { writeSchema, SCHEMA_PATH } from "./core/schema.js";
 
+function loadManifestOrExit(dir: string) {
+  try {
+    return loadManifest(resolve(dir));
+  } catch (err) {
+    if (err instanceof ZodError) {
+      const msg = err.issues.map((i) => `${i.message}  (path: ${i.path.join(".")})`).join("\n  ");
+      console.error(`✗ ${msg}`);
+    } else {
+      console.error(`✗ ${err instanceof Error ? err.message : err}`);
+    }
+    process.exit(1);
+  }
+}
+
 // Single source of truth for the version: package.json (kept in sync by semantic-release).
 const pkg = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -49,13 +64,7 @@ program
   .argument("[dir]", "Project directory", ".")
   .action((dir: string) => {
     const root = resolve(dir);
-    let loaded;
-    try {
-      loaded = loadManifest(root);
-    } catch (err) {
-      console.error(`✗ ${err instanceof Error ? err.message : err}`);
-      process.exit(1);
-    }
+    const loaded = loadManifestOrExit(dir);
     const problems: string[] = [];
     const ids = new Set<string>();
     for (const f of loaded.manifest.fragment) {
@@ -92,7 +101,7 @@ program
   )
   .option("--check", "Verify vendor files are up to date with .scope/ (no writes); exit 1 if stale/missing")
   .action((dir: string, opts: { target?: string[]; check?: boolean }) => {
-    const loaded = loadManifest(resolve(dir));
+    const loaded = loadManifestOrExit(dir);
     let targets;
     try {
       targets = resolveTargets(opts.target);
@@ -136,7 +145,7 @@ program
       taskWords: string[],
       opts: { dir: string; path?: string[]; budget?: number; exact?: boolean; raw?: boolean },
     ) => {
-      const loaded = loadManifest(resolve(opts.dir));
+      const loaded = loadManifestOrExit(opts.dir);
       const text = taskWords.join(" ");
       const result = pack(loaded, { text, paths: opts.path }, { budget: opts.budget, exact: opts.exact });
       if (opts.raw) {

src/core/types.ts

@@ -6,15 +6,17 @@ import { z } from "zod";
  *  - knowledge: static reference data, loaded lazily
  *  - spec:      current task requirements
  *  - persona:   a swappable agent "hat"
+ *  - memory:    decisions, logs, and state
  */
-export const FragmentType = z.enum(["rule", "knowledge", "spec", "persona"]);
+export const FragmentType = z.enum(["rule", "knowledge", "spec", "persona", "memory"]);
 export type FragmentType = z.infer<typeof FragmentType>;
 
 /** Default precedence used when ordering matched fragments for a pack. */
 export const TYPE_PRECEDENCE: Record<FragmentType, number> = {
-  rule: 3,
-  spec: 2,
-  persona: 1,
+  rule: 4,
+  spec: 3,
+  persona: 2,
+  memory: 1,
   knowledge: 0,
 };
 

src/core/vendor.ts

@@ -49,11 +49,12 @@ export const VENDOR_TARGETS: VendorTarget[] = [
   },
 ];
 
-const ORDER: Fragment["type"][] = ["rule", "persona", "spec", "knowledge"];
+const ORDER: Fragment["type"][] = ["rule", "persona", "spec", "memory", "knowledge"];
 const HEADINGS: Record<Fragment["type"], string> = {
   rule: "Rules (always apply)",
   persona: "Persona",
   spec: "Active specs",
+  memory: "Project memory",
   knowledge: "Reference knowledge",
 };