@karmaniverous/stan-core 0.4.1 → 0.4.3

package/dist/stan.system.md

@@ -643,7 +643,8 @@ This is a HARD GATE: the composition MUST fail when a required documentation pat
 
 - Append‑only logging for Completed:
   - Do NOT modify or rewrite a previously logged Completed item.
-  - If follow‑on context is needed (e.g., clarifications/corrections), log it as a new list entry appended at the bottom of the Completed section (i.e., an amendment to the list, not to the individual item). Keep the original entries intact.
+  - If follow‑on context is needed (e.g., clarifications/corrections), log it as a new list entry appended at the bottom of the Completed section (i.e., an amendment to the list, not edits to prior items). Keep the original entries intact.
+  - These rules are enforced by pre‑send validation (see Response Format). A composition that edits prior Completed entries MUST fail and be re‑emitted as an end‑append only change.
 
 - Prune for relevance:
   - Remove Completed items that are not needed to understand the work in flight (“Next up” and any active follow‑through). Retain only minimal context that prevents ambiguity.
@@ -801,6 +802,57 @@ diff --git a/new/path/to/file/a.ts b/new/path/to/file/a.ts
 - When attaching artifacts for chat, prefer attaching `<stanPath>/output/archive.tar` (and `<stanPath>/output/archive.diff.tar` when present). If `--combine` was not used, you may also attach the text outputs individually.
 - Important: Inside any attached archive, contextual files are located in the directory matching the `stanPath` key from `stan.config.*` (default `.stan`). The bootloader resolves this automatically.
 
+# Facet overlay (selective views with anchors)
+
+This repository supports “facets” — named, selective views over the codebase designed to keep archives small while preserving global context via small anchor documents.
+
+Files (under `<stanPath>/system/`)
+- `facet.meta.json` (durable): facet definitions — name → `{ exclude: string[]; include: string[] }`. The `include` list contains anchor files (e.g., README/index docs) that must always be included to preserve breadcrumbs.
+- `facet.state.json` (ephemeral, should always exist): facet activation for the next run — name → `boolean` (`true` = active/no drop; `false` = inactive/apply excludes). Keys mirror `facet.meta.json`.
+
+Overlay status for the last run
+- The CLI writes a machine‑readable summary to `<stanPath>/system/.docs.meta.json` in a top‑level `overlay` block that records:
+  - `enabled`: whether the overlay was applied this run,
+  - per‑run overrides (`activated`/`deactivated`),
+  - the final `effective` map used for selection,
+  - optional `autosuspended` facets (requested inactive but kept due to missing anchors),
+  - optional `anchorsKept` (paths force‑included as anchors).
+- Always read this block when present; treat selection deltas that follow overlay updates as view changes (not code churn).
+
+Assistant obligations (every turn)
+1) Read facet files first:
+   - Load `facet.meta.json`, `facet.state.json`, and (when present) `.docs.meta.json.overlay`.
+   - Treat large selection changes after overlay edits as view expansion.
+2) Design the view (facets & anchors):
+   - Propose or refine facet definitions in `facet.meta.json` to carve large areas safely behind small anchors (READMEs, indices, curated summaries).
+   - Keep anchor docs useful and current: when code changes public surfaces or invariants, update the relevant anchor docs in the same change set.
+   - Do not deactivate a facet unless at least one suitable anchor exists under the area being hidden. If anchors are missing, add them (and record their paths under `include`) before deactivation.
+3) Set the view (next run):
+   - Toggle `facet.state.json` (`true`/`false`) to declare the intended default activation for the next run. This is the assistant’s declarative control of perspective across turns.
+4) Response format:
+   - Use plain unified diffs to update `facet.meta.json`, anchor docs, and `facet.state.json`. Summarize rationale in the commit message.
+
+Effective activation for a run (informational)
+- A facet is effectively active this run if the overlay is enabled and it resolves `true` after applying CLI precedence:
+  - `-f` overrides (forces active) > `facet.state.json[name] === true` > `-F` overrides (forces inactive) > default active for facets missing in state.
+- If the overlay is disabled (`--no-facets` or naked `-F`), the state still expresses the next‑run default but does not affect the current run’s selection.
+
+Selection precedence (toolchain‑wide; informational)
+- Reserved denials always win; anchors cannot override:
+  - `.git/**`
+  - `<stanPath>/diff/**`
+  - `<stanPath>/patch/**`
+  - `<stanPath>/output/archive.tar`, `<stanPath>/output/archive.diff.tar` (and future archive outputs)
+  - Binary screening (classifier) remains in effect.
+- Precedence across includes/excludes/anchors:
+  - `includes` override `.gitignore` (but not `excludes`).
+  - `excludes` override `includes`.
+  - `anchors` (from facet meta) override both `excludes` and `.gitignore` (subject to reserved denials and binary screening).
+
+Notes
+- Facet files and overlay metadata are included in archives so the assistant can reason about the current view and evolve it. These files do not change Response Format or patch cadence.
+- Keep facets small and purposeful; prefer a few well‑placed anchors over broad patterns.
+
 # Facet‑aware editing guard (think beyond the next turn)
 
 Purpose
@@ -850,6 +902,51 @@ Notes
   - Turn N: enable the facet + log intent.
   - Turn N+1: deliver the content edits once the target is present in archives.
 
+# stanPath discipline (write‑time guardrails)
+
+Purpose
+
+- Ensure all assistant‑emitted patches and file operations target the correct STAN workspace directory for this repository (the configured `stanPath`).
+- Prevent common errors where patches are written to `stan/…` when the repo uses `.stan/…` (or vice‑versa), or where the literal placeholder `<stanPath>` appears in patch paths.
+
+Resolve stanPath first (required)
+
+1. Read `stan.config.yml|yaml|json` and extract `stan-core.stanPath`:
+   - The value MUST be a non‑empty string; when present, treat it as authoritative.
+2. If the config is not present in the archive, derive from observed layout:
+   - Prefer the workspace directory that actually exists in the attached artifacts (e.g., `.stan/system/…`).
+   - If both `.stan/…` and `stan/…` appear (unusual), prefer the one that contains `system/stan.system.md` or `system/` docs.
+3. Fallback default (last resort): `.stan`.
+
+Write‑time rules (hard)
+
+- Always use the resolved `stanPath` for all repo‑relative targets under the STAN workspace:
+  - `/<stanPath>/system/**`
+  - `/<stanPath>/diff/**`
+  - `/<stanPath>/output/**`
+  - `/<stanPath>/patch/**`
+  - Any other STAN paths (imports, dist, etc.).
+- Never write to `stan/…` unless `stanPath === "stan"`.
+- Never write to `.stan/…` unless `stanPath === ".stan"`.
+- Never leave the literal placeholder `<stanPath>` in any patch path or File Ops argument. Compute concrete POSIX repo‑relative paths before emitting.
+
+Pre‑send validation (assistant‑side check)
+
+- Fail composition if any Patch path contains the literal `<stanPath>`.
+- Fail composition if any Patch path refers to `stan/…` when `stanPath === ".stan"`, or `.stan/…` when `stanPath === "stan"`.
+- Paths MUST be POSIX (forward slashes) and repo‑relative.
+
+Input clarity (optional)
+
+- In “Input Data Changes” or the first relevant section of a reply, it is acceptable (not required) to echo the resolved `stanPath` for this run, e.g., “stanPath resolved: `.stan`”. This helps reviewers spot a mismatch early.
+
+Notes
+
+- These rules apply only to assistant‑emitted content (patches and file ops). The bootloader’s read‑side fallbacks (e.g., probing `.stan` then `stan`) exist for compatibility with older archives and do not affect write‑time discipline.
+- The rules compose with other guards:
+  - Reserved denials remain in effect (e.g., do not place content under `/<stanPath>/diff/**`, `/<stanPath>/patch/**`, or archive outputs in `/<stanPath>/output/**`).
+  - The facet‑aware editing guard still applies: do not propose edits under an inactive facet this run; enable the facet first and emit patches next turn.
+
 # Default Task (when files are provided with no extra prompt)
 
 Primary objective — Plan-first
@@ -1075,6 +1172,13 @@ Before sending a reply, verify all of the following:
    - Diagnostics replies: Skip Commit Message; listings‑only for the affected files.
 6. Nested-code templates (hard gate)
    - Any template or example that contains nested fenced code blocks (e.g., the Dependency Bug Report or a patch failure diagnostics envelope) MUST pass the fence‑hygiene scan: compute N = maxInnerBackticks + 1 (min 3), apply that fence, then re‑scan before sending. If any collision remains, STOP and re‑emit. If any check fails, STOP and re‑emit after fixing. Do not send a reply that fails these checks.
+7. Dev plan “Completed” (append‑only; last)
+   - If `.stan/system/stan.todo.md` is patched:
+     - “Completed” is still the final major section of the document.
+     - Only new lines were appended at the end of “Completed”; no existing lines above the append point were modified or re‑ordered.
+     - Corrections/clarifications, if any, are logged as a new one‑line “Amendment:” entry appended at the bottom (the original entries remain intact).
+     - Lists remain unnumbered.
+   - Violations fail composition.
 
 ## Patch policy reference
 
@@ -1084,6 +1188,14 @@ Optional Full Listings — Normal replies only: when explicitly requested by the
 Diagnostics replies (after patch‑failure envelopes) MUST provide Full, post‑patch listings as described above (no patches, union across envelopes, no commit message).
 Skip listings for deletions.
 
+Dev plan Completed enforcement (pre‑send)
+- If `<stanPath>/system/stan.todo.md` is patched in this turn, enforce late‑append semantics for the “Completed” section:
+  - “Completed” MUST remain the final major section of the document.
+  - Only append new lines at the end of “Completed”. Do NOT modify existing lines above the final append point (no edits, no insertions, no re‑ordering).
+  - If a correction/clarification is needed for a prior item, append a new one‑line “Amendment:” entry at the bottom instead of editing the original item.
+  - Lists remain unnumbered.
+  - Violations MUST fail composition; re‑emit with an end‑append only change.
+
 ## File Ops (optional pre‑ops; structural changes)
 
 Use “### File Ops” to declare safe, repo‑relative file and directory operations that run before content patches. File Ops are for structure (moves/renames, creates, deletes), while unified‑diff Patches are for editing file contents.

package/package.json

@@ -10,7 +10,6 @@
     "url": "https://github.com/karmaniverous/stan-core/issues"
   },
   "dependencies": {
-    "@vitest/eslint-plugin": "^1.3.15",
     "diff": "^8.0.2",
     "fast-glob": "^3.3.3",
     "fs-extra": "^11.3.2",
@@ -19,49 +18,51 @@
     "package-directory": "^8.1.0",
     "picomatch": "^4.0.3",
     "yaml": "^2.8.1",
-    "zod": "^4.1.11"
+    "zod": "^4.1.12"
   },
   "description": "Engine for STAN — programmatic archiving/diffing/snapshotting, patch application, config loading, selection, and imports staging. No CLI/TTY concerns.",
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.51.0",
-    "@eslint/js": "^9.37.0",
+    "@eslint/js": "^9.38.0",
     "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-commonjs": "^28.0.8",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.4",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@types/eslint-config-prettier": "^6.11.3",
     "@types/fs-extra": "^11.0.4",
     "@types/glob-parent": "^5.1.3",
-    "@types/node": "^24.6.2",
+    "@types/node": "^24.9.1",
     "@types/picomatch": "^4.0.2",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.0.2",
+    "@vitest/eslint-plugin": "^1.3.23",
     "auto-changelog": "^2.5.0",
-    "eslint": "^9.37.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.38.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsonc": "^2.21.0",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.4.0",
-    "happy-dom": "^19.0.2",
+    "happy-dom": "^20.0.8",
     "jsonc-eslint-parser": "^2.4.1",
-    "knip": "^5.64.1",
-    "lefthook": "^1.13.6",
+    "knip": "^5.66.2",
+    "lefthook": "^2.0.0",
     "prettier": "^3.6.2",
     "release-it": "^19.0.5",
     "rimraf": "^6.0.1",
-    "rollup": "^4.52.4",
+    "rollup": "^4.52.5",
     "rollup-plugin-dts": "^6.2.3",
     "tar": "^7.5.1",
     "tslib": "^2.8.1",
     "tsx": "^4.20.6",
-    "typedoc": "^0.28.13",
-    "typedoc-plugin-mdn-links": "^5.0.9",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-mdn-links": "^5.0.10",
     "typedoc-plugin-replace-text": "^4.2.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.45.0",
-    "vitest": "^3.2.4"
+    "typescript-eslint": "^8.46.2",
+    "vitest": "^4.0.2"
   },
   "engines": {
     "node": ">=20"
@@ -141,15 +142,15 @@
     "changelog": "auto-changelog",
     "docs": "typedoc",
     "knip": "knip",
-    "lint": "eslint .",
     "lint:fix": "npm run lint -- --fix .",
-    "release": "dotenvx run -f .env.local -- release-it",
+    "lint": "eslint .",
     "release:pre": "npm run release -- --no-git.requireBranch --github.prerelease --preRelease",
+    "release": "dotenvx run -f .env.local -- release-it",
     "relink": "npm uninstall -g @karmaniverous/stan-core && npm run build && npm link",
     "test": "vitest --run --coverage --silent",
     "typecheck": "tsc"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.4.1"
+  "version": "0.4.3"
 }