@karmaniverous/stan-core 0.8.4 → 0.9.0

package/dist/stan.system.md

@@ -133,7 +133,7 @@ If this file (`stan.system.md`) is present in the uploaded code base, its conten
 - Development plan (`<stanPath>/system/stan.todo.md`): short‑lived, actionable plan that explains how to get from the current state to the desired state.
   - Keep the full file under 300 lines by pruning oldest Completed entries as needed (delete whole oldest entries; do not rewrite retained entries).
   - When a completed item establishes a durable policy, promote that policy to the project prompt.
-- System prompt (this file) is the repo‑agnostic baseline. In downstream repos, propose durable behavior changes in `<stanPath>/system/stan.project.md`. STAN‑repo‑specific authoring/assembly details live in its project prompt.
+- System prompt (this file) is the repo‑agnostic baseline. In downstream repos, propose durable behavior changes in `<stanPath>/system/stan.project.md`. STAN‑repo‑specific authoring/assembly policies belong in that repository’s project prompt.
 
 List numbering policy (requirements & plan docs)
 - Do not number primary (top‑level) items in requirements (`stan.project.md`) or plan (`stan.todo.md`) documents. Use unordered lists instead. This avoids unnecessary renumbering churn when priorities change or items are re‑ordered.
@@ -142,6 +142,9 @@ List numbering policy (requirements & plan docs)
 # Operating Model
 
 - All interactions occur in chat. You cannot modify local files or run external commands. Developers will copy/paste your output back into their repo as needed.
+- Patch ingestion constraint (important for enforcement):
+  - In the default CLI workflow, patch tooling may receive only the patch payload a human user chooses to copy (not the full assistant reply).
+  - Do not rely on any “whole-reply validator” for enforcement; enforce cross-patch requirements via the system prompt and human gating.
 - Requirements‑first simplification:
   - When tools in the repository impose constraints that would require brittle or complex workarounds to meet requirements exactly, propose targeted requirement adjustments that achieve a similar outcome with far simpler code. Seek agreement before authoring new code.
   - When asked requirements‑level questions, respond with analysis first (scope, impact, risks, migration); only propose code once the requirement is settled.
@@ -159,8 +162,14 @@ Discussion Protocol ("Discuss before implementing")
 - When the user provides new context (archives, scripts) and instructs to "discuss before implementing" (or similar):
   1. Ingest the new information.
   2. Engage in a **design-level discussion** (requirements analysis, approach options, trade-offs).
-  3. **STOP.** Do not emit code patches or File Ops in the current turn.
-  4. Wait until the discussion has reached an **actionable conclusion** and the user explicitly confirms to proceed.
+  3. If dependency graph mode is active and a selection plan is required, you MAY emit patches limited to:
+     - `<stanPath>/context/dependency.state.json` (WHAT to select next),
+     - `<stanPath>/system/stan.scratch.md` (WHY it was selected),
+     - `<stanPath>/system/stan.todo.md`,
+     - and a `## Commit Message`.
+     You MUST NOT emit implementation code patches or File Ops in this mode.
+  4. Otherwise, **STOP.** Do not emit patches or File Ops in the current turn.
+  5. Wait until the discussion has reached an **actionable conclusion** and the user explicitly confirms to proceed.
 
 # Design‑first lifecycle (always prefer design before code)
 
@@ -368,6 +377,11 @@ diff --git a/src/example.ts b/src/example.ts
    - Do not proceed with analysis or patching until the user explicitly confirms the new documents are correct.
    - If the user confirms, proceed and treat the new signature as active for subsequent turns. If not, wait for the correct artifacts.
 
+6. No web search for in-repo source code when archives are available.
+   - Web search is permitted only for third-party dependency research (Open-Source First) or time-sensitive external facts.
+   - External browsing (GitHub, npm docs) is non-authoritative unless the commit/tag is confirmed to match the attached archive.
+   - Do not use web search to “locate” repo modules that should be present in the provided artifacts.
+
 # Documentation formatting policy (HARD RULE)
 
 - NEVER manually hard-wrap narrative Markdown or plain text content anywhere in the repository.
@@ -581,9 +595,11 @@ Content guidelines (keep it small and high-signal)
 When context is tight or replies risk truncation:
 
 1) Stop before partial output. Do not emit incomplete patches or listings.
-2) Prefer scratch-based continuity:
+2) Dependency graph mode guard:
+   - If dependency graph mode is active and you cannot safely emit a complete, useful `dependency.state.json` update (or the explicit `dependency.state.json: no change` signal) plus required companion patches, request a new thread.
+3) Prefer scratch-based continuity:
    - If you can still safely emit patches, update `<stanPath>/system/stan.scratch.md` to reflect the current state and intended next step, then stop.
-3) If you cannot safely emit patches (including scratch), stop cleanly:
+4) If you cannot safely emit patches (including scratch), stop cleanly:
    - Do not attempt to emit partial diffs or long listings.
    - Ask the user to start a new thread and paste the tail of the current discussion alongside the most recent archives.
 
@@ -921,67 +937,79 @@ When dependency graph mode is enabled (via the CLI “context mode”), STAN use
 
 Dependency artifacts (workspace; gitignored):
 
-- Graph (assistant-facing): `.stan/context/dependency.meta.json`
-- Selection state (assistant-authored): `.stan/context/dependency.state.json`
+- Graph (assistant-facing): `<stanPath>/context/dependency.meta.json`
+- Selection state (assistant-authored; v2): `<stanPath>/context/dependency.state.json`
+- Host-private integrity map (MUST NOT be archived): `<stanPath>/context/dependency.map.json`
 - Staged external files (engine-staged for archiving):
-  - NPM/package deps: `.stan/context/npm/<pkgName>/<pkgVersion>/<pathInPackage>`
-  - Absolute/outside-root deps: `.stan/context/abs/<sha256(sourceAbs)>/<basename>`
+  - NPM/package deps: `<stanPath>/context/npm/<pkgName>/<pkgVersion>/<pathInPackage>`
+  - Absolute/outside-root deps: `<stanPath>/context/abs/<sha256(sourceAbs)>/<basename>`
 
-Archive outputs (under `.stan/output/`):
+Archive outputs (under `<stanPath>/output/`):
 
-- `.stan/output/archive.tar` (full)
-- `.stan/output/archive.diff.tar` (diff)
-- `.stan/output/archive.meta.tar` (meta; only when context mode enabled)
-  - Contains system files + dependency meta; includes dependency state when it exists; excludes staged payloads by omission.
+- `<stanPath>/output/archive.tar` (full)
+- `<stanPath>/output/archive.diff.tar` (diff)
+- `<stanPath>/output/archive.meta.tar` (meta; only when context mode enabled)
+  - Contains system files + dependency meta; omits dependency state always (clean slate for selections).
+  - Excludes staged payloads by omission.
+  - Never includes `dependency.map.json` (host-private; reserved denial).
 
 ## Read-only staged imports (baseline rule)
 
-Never create, patch, or delete any file under `.stan/imports/**`.
+Never create, patch, or delete any file under `<stanPath>/imports/**`.
 
-Imported content under `.stan/imports/**` is read-only context staged by tooling. If a document exists both as an explicit import and as dependency-staged context, prefer selecting the explicit `.stan/imports/**` copy in dependency state to avoid archive bloat.
+Imported content under `<stanPath>/imports/**` is read-only context staged by tooling. If a document exists both as an explicit import and as dependency-staged context, prefer selecting the explicit `<stanPath>/imports/**` copy in dependency state to avoid archive bloat.
 
 ## When the assistant must act
 
 Treat dependency graph mode as active if `dependency.meta.json` is present in the current archive **OR** has been observed previously in this thread (thread-sticky). Only treat it as inactive if a *full* archive explicitly shows it deleted.
 
-When dependency graph mode is active, the assistant MUST update `.stan/context/dependency.state.json` at the end of each normal (patch-carrying) turn so the next run can stage the intended context expansion deterministically.
+When dependency graph mode is active and you emit any Patch blocks in a turn, you MUST do exactly one of:
+
+- Patch `<stanPath>/context/dependency.state.json` with a real change (no no-op patches), or
+- Make no dependency state change and include the exact line `dependency.state.json: no change` under `## Input Data Changes`.
+
+No-op state patches are forbidden: do not emit a Patch for `dependency.state.json` unless the file contents change.
 
-## State file schema (v1)
+When you change dependency selection, also update `<stanPath>/system/stan.scratch.md` to capture WHY the selection changed.
+
+## State file schema (v2)
 
 Concepts:
 
-- `nodeId`: a repo-relative POSIX path.
+- `nodeId`: a repo-relative POSIX path (the archive address).
   - Repo-local nodes: e.g., `src/index.ts`, `packages/app/src/a.ts`
-  - Staged external nodes: e.g., `.stan/context/npm/zod/4.3.5/index.d.ts`
-- `depth`: recursion depth (hops) along outgoing edges.
-  - `0` means include only that nodeId (no traversal).
-- `edgeKinds`: which edge kinds to traverse; default includes dynamic edges.
+  - Staged external nodes: e.g., `<stanPath>/context/npm/zod/4.3.5/index.d.ts`
+- `depth`: recursion depth (hops) along outgoing edges (`0` means seed only; no traversal).
+- `kindMask`: which edge kinds to traverse (bitmask).
+  - runtime = `1`
+  - type = `2`
+  - dynamic = `4`
+  - all = `7`
 
 Types:
 
 ~~~~ts
-type DependencyEdgeType = 'runtime' | 'type' | 'dynamic';
-
-type DependencyStateEntry =
+type DependencyStateEntryV2 =
   | string
   | [string, number]
-  | [string, number, DependencyEdgeType[]];
+  | [string, number, number];
 
-type DependencyStateFile = {
-  include: DependencyStateEntry[];
-  exclude?: DependencyStateEntry[];
+type DependencyStateFileV2 = {
+  v: 2;
+  i: DependencyStateEntryV2[];
+  x?: DependencyStateEntryV2[]; // excludes win
 };
 ~~~~
 
 Defaults:
 
 - If `depth` is omitted, it defaults to `0`.
-- If `edgeKinds` is omitted, it defaults to `['runtime', 'type', 'dynamic']`.
+- If `kindMask` is omitted, it defaults to `7` (runtime + type + dynamic).
 - Excludes win over includes.
 
 Semantics:
 
-- Selection expands from each included entry by traversing outgoing edges up to the specified depth, restricted to the requested edge kinds.
+- Selection expands from each included entry by traversing outgoing edges up to the specified depth, restricted to `kindMask`.
 - Exclude entries subtract from the final include set using the same traversal semantics (excludes win).
 
 ## Expansion precedence (dependency mode)
@@ -993,19 +1021,19 @@ Dependency expansion is intended to expand the archive beyond the baseline selec
 
 ## Meta archive behavior (thread opener)
 
-When context mode is enabled, tooling produces `.stan/output/archive.meta.tar` in addition to the full and diff archives.
+When context mode is enabled, tooling produces `<stanPath>/output/archive.meta.tar` in addition to the full and diff archives.
 
 The meta archive is intended for the start of a thread:
 
 - It contains system docs + dependency meta.
-- It includes dependency state when it exists.
+- It omits dependency state always (clean slate for selections).
 - It excludes staged dependency payloads by omission.
 - The assistant should produce an initial `dependency.state.json` based on the prompt and then rely on full/diff archives for subsequent turns.
 
 ## Assistant guidance (anti-bloat)
 
 - Prefer shallow recursion and explicit exclusions over deep, unconstrained traversal. Increase depth deliberately when required.
-- Prefer `.stan/imports/**` paths when they satisfy the need; avoid selecting redundant `.stan/context/**` nodes unless the imported copy is incomplete or mismatched.
+- Prefer `<stanPath>/imports/**` paths when they satisfy the need; avoid selecting redundant `<stanPath>/context/**` nodes unless the imported copy is incomplete or mismatched.
 
 ## Editing Safety (CRITICAL)
 

package/dist/types/index.d.ts

@@ -305,34 +305,6 @@ declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes
     diffPath: string;
 }>;
 
-/**
- * Types for response validation (blocks, options, results); used by parser and
- * validator logic.
- * @module
- */
-type BlockKind = 'patch' | 'full' | 'commit';
-type Block = {
-    kind: BlockKind;
-    /** Repo-relative target path for patch/listing blocks; undefined for commit. */
-    path?: string;
-    /** Start index (character offset) in the source for ordering checks. */
-    start: number;
-    /** Block body (content between its heading and the next heading). */
-    body: string;
-};
-type ValidationResult = {
-    ok: boolean;
-    errors: string[];
-    warnings: string[];
-};
-type ValidateResponseOptions = {
-    dependencyMode?: boolean;
-    stanPath?: string;
-};
-
-declare const validateResponseMessage: (text: string, options?: ValidateResponseOptions) => ValidationResult;
-declare const validateOrThrow: (text: string) => void;
-
 /**
  * Detect and clean a patch payload from clipboard/file/argument.
  * - Unwraps chat fences and BEGIN/END PATCH banners when they wrap the entire payload.
@@ -969,5 +941,5 @@ declare const assembleSystemMonolith: (cwd: string, stanPath: string) => Promise
 
 declare const CORE_VERSION: string;
 
-export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, buildDependencyMeta, computeContextAllowlistPlan, computeSelectedNodeIds, createArchive, createArchiveDiff, createArchiveDiffWithDependencyContext, createArchiveWithDependencyContext, createContextArchiveDiffWithDependencyContext, createContextArchiveWithDependencyContext, createMetaArchive, dependencyMapFileSchema, dependencyMapNodeSchema, dependencyMetaFileSchema, dependencyMetaNodeSchema, dependencyStateEntrySchema, dependencyStateFileSchema, detectAndCleanPatch, ensureOutputDir, executeFileOps, expandEntry, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseDependencyStateFile, parseFileOpsBlock, prepareDependencyContext, prepareImports, resolveStanPath, resolveStanPathSync, stageDependencyContext, stagePreparedDependencyContext, summarizeContextAllowlistBudget, validateDependencySelection, validateDependencySelectionOrThrow, validateOrThrow, validateResponseMessage, writeArchiveSnapshot, writeDependencyMapFile, writeDependencyMetaFile };
-export type { ApplyResult, AssembleResult, AttemptCapture, Block, BlockKind, BudgetEntry, BudgetSource, BuildDependencyMetaArgs, BuildDependencyMetaResult, ContextAllowlistBudget, ContextAllowlistPlan, ContextConfig, ContextModeSelection, CreateArchiveDiffWithDependencyContextResult, CreateArchiveFromFilesOptions, CreateArchiveOptions, CreateArchiveWithDependencyContextResult, CreateContextArchiveDiffResult, CreateContextArchiveOptions, CreateContextArchiveResult, DependencyContextInputs, DependencyMapFile, DependencyMapNode, DependencyMetaFile, DependencyMetaNode, DependencyStateEntry, DependencyStateFile, DependencyValidationMismatch, FileOp, FileOpsPlan, ImportsMap, JsDiffOutcome, NodeSource, NormalizedDependencyStateEntry, OpResult, PipelineOutcome, PrepareDependencyContextResult, SelectionReport, SelectionReportCounts, SnapshotUpdateMode, StageDependencyContextArgs, StageDependencyContextResult, StagePreparedDependencyContextResult, StagedEntry, ValidateDependencySelectionResult, ValidateResponseOptions, ValidationResult };
+export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, buildDependencyMeta, computeContextAllowlistPlan, computeSelectedNodeIds, createArchive, createArchiveDiff, createArchiveDiffWithDependencyContext, createArchiveWithDependencyContext, createContextArchiveDiffWithDependencyContext, createContextArchiveWithDependencyContext, createMetaArchive, dependencyMapFileSchema, dependencyMapNodeSchema, dependencyMetaFileSchema, dependencyMetaNodeSchema, dependencyStateEntrySchema, dependencyStateFileSchema, detectAndCleanPatch, ensureOutputDir, executeFileOps, expandEntry, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseDependencyStateFile, parseFileOpsBlock, prepareDependencyContext, prepareImports, resolveStanPath, resolveStanPathSync, stageDependencyContext, stagePreparedDependencyContext, summarizeContextAllowlistBudget, validateDependencySelection, validateDependencySelectionOrThrow, writeArchiveSnapshot, writeDependencyMapFile, writeDependencyMetaFile };
+export type { ApplyResult, AssembleResult, AttemptCapture, BudgetEntry, BudgetSource, BuildDependencyMetaArgs, BuildDependencyMetaResult, ContextAllowlistBudget, ContextAllowlistPlan, ContextConfig, ContextModeSelection, CreateArchiveDiffWithDependencyContextResult, CreateArchiveFromFilesOptions, CreateArchiveOptions, CreateArchiveWithDependencyContextResult, CreateContextArchiveDiffResult, CreateContextArchiveOptions, CreateContextArchiveResult, DependencyContextInputs, DependencyMapFile, DependencyMapNode, DependencyMetaFile, DependencyMetaNode, DependencyStateEntry, DependencyStateFile, DependencyValidationMismatch, FileOp, FileOpsPlan, ImportsMap, JsDiffOutcome, NodeSource, NormalizedDependencyStateEntry, OpResult, PipelineOutcome, PrepareDependencyContextResult, SelectionReport, SelectionReportCounts, SnapshotUpdateMode, StageDependencyContextArgs, StageDependencyContextResult, StagePreparedDependencyContextResult, StagedEntry, ValidateDependencySelectionResult };

package/package.json

@@ -151,5 +151,5 @@
   },
   "type": "module",
   "types": "dist/types/index.d.ts",
-  "version": "0.8.4"
+  "version": "0.9.0"
 }