com.blockether.vis.internal.context.agents — com.blockether/vis 0.2.30

Project-guidance discovery — internal, no extension required.

STACKED context files, pi-style: guidance is collected from THREE layers and all of them ride into the PROJECT-INSTRUCTIONS system block, outermost first:

1. user-global ~/.vis/AGENTS.md (or ~/.vis/CLAUDE.md)
2. ancestors AGENTS.md / CLAUDE.md in every ancestor directory of the workspace root (outermost first)
3. workspace AGENTS.md / CLAUDE.md at the workspace root
4. added roots AGENTS.md / CLAUDE.md at each ADDED filesystem root's own directory (folders granted beyond the primary workspace — no ancestor walk)

Per DIRECTORY precedence is strict: AGENTS.md wins; CLAUDE.md is only consulted when AGENTS.md is absent in that directory. Across directories nothing is dropped — nearer files are rendered LATER so they positionally override outer rules on conflict.

Size policy: NO truncation. Every file goes into the system prompt verbatim. Provider prompt caching amortizes the cost across every iter in the session; trimming would risk dropping the very rule the user is testing. The cwd + per-file (path, mtime, length) marker cache below ensures files are re-read at most once per change.

Failure modes (file unreadable, permissions, I/O error) land in the read-warning vec, NOT in the rendered prompt. The model isn't bound by rules it can't see, but the host knows something is broken.

This namespace replaces the foundation-core/environment/agents.clj that used to live in the extension. Project-guidance discovery is core functionality (drives the system prompt + slim ctx digest); the extension layer no longer owns it.

added-root-guidance-index clj

(added-root-guidance-index)

Return metadata for guidance available at added filesystem roots without reading file contents. Each row is {:root path :path guidance-path :source}.

current clj

(current)

Return the cached scan, recomputing when cwd or any stacked AGENTS.md/CLAUDE.md marker changes. Common path is stat-only — content is re-read only when a marker changes.

instructions clj

(instructions)

Return the structured map behind (vis/main-agent-instructions). Always a map. :found? discriminates present vs absent.

present: {:found? true :files [{:scope :source :path :bytes :content} …] :source <legacy kw> :path "…" :bytes N :content "…"} absent: {:found? false}

:files is the stacked view (user-global → ancestors → workspace root, outermost first). The top-level :source/:path describe the INNERMOST file and :content is the combined origin-headed render — the legacy single-file consumers keep working unchanged.

No truncation: every :content is the full file verbatim. Caller-side display limits (e.g. tape pretty-printing) are caller business.

origin-label clj

(origin-label {:keys [scope source]})

Human label for a stacked-file entry: file name + scope qualifier.

primary-instructions clj

(primary-instructions)

Read guidance for the primary workspace chain only. Added-root files are intentionally excluded so unrelated sessions do not pay their prompt cost.

reload! clj

(reload!)

Revalidate project guidance and return the current scan result.

scan clj

(scan)

Scan the user-global ~/.vis dir, the active workspace root's ancestor chain, and each added filesystem root's own directory for project-guidance files (stacked).

scan-in clj

(scan-in root)

Scan root for project-guidance files. Pure I/O. Single-directory, legacy result shape (:source :repo / :repo:claude-md-fallback); the stacked multi-file scan is scan-roots / scan. Exposed for testing against fixture roots.

scan-roots clj

(scan-roots global-dir workspace-root)

(scan-roots global-dir workspace-root extra-roots)

Stacked scan: guidance file in global-dir first (when non-nil), then AGENTS.md / CLAUDE.md from every ancestor of workspace-root (outermost first) down to the workspace root itself, then each added extra-root's OWN directory (no ancestor walk — only what the user granted). Pure I/O; exposed for testing against fixture roots.

Primary-chain precedence is render order: user-global → ancestors → workspace root. Nearer files land later and override broader files in that same filesystem scope. Added-root entries are separately path-scoped; their rules apply only beneath that root and do not join the primary precedence chain. A duplicate guidance-file path is dropped.

Returns {:result r :warnings [...]} where r is:

present: {:found? true :files [{:scope :global|:ancestor|:project|:extra-root :source :agents-md|:claude-md :path "…" :bytes N :content "…"} …] ;; legacy single-file view (innermost file + combined content) :source <legacy kw> :path "…" :bytes <total> :content "…"} absent: {:found? false}