@onedotmint/charterleaf 0.1.0 → 0.2.1

package/AGENTS_SNIPPET.md

@@ -8,7 +8,7 @@ Project specifications live under `specs/`. For non-trivial architectural, behav
 - `specs/changes/` — lightweight active deltas.
 - `specs/constitution.md` — project-wide guardrails only.
 
-When a concrete code path is known, use `charterleaf related <path>` to locate matching living specs plus active changes that affect them. Otherwise use normal code/text search. Use `charterleaf lint` for structural validation and mechanical active-change conflicts. These commands are helpers, not workflow gates.
+When a concrete code path is known, use `charterleaf related <path>` to locate matching living specs plus active changes that affect them. When the relevant code path is not yet known, use `charterleaf map` only to discover available specification scopes; do not read every listed specification. Use normal code navigation to locate the smallest relevant area, then use `charterleaf related <path>`. For broad project-level questions, start with normal project entry documents; do not expand into every spec or project-state document merely because no path was provided. Use `charterleaf lint` for structural validation and mechanical active-change conflicts. These commands are helpers, not workflow gates.
 
 Authority is `Constitution > Active Change > Living Spec > Current Code`. Do not add authority scores or silently rewrite specs to match code.
 
@@ -16,6 +16,14 @@ Keep specs compressed and evidence-based. Prefer durable contracts and pitfalls
 
 Do not create specs for temporary implementation details, current tasks, debugging notes, routine refactors, or trivial fixes with no durable implication. For a durable bug fix, use `Current` / `Expected` when useful and explicitly state what must `PRESERVE`.
 
+After non-trivial implementation or debugging, consider whether durable project knowledge was discovered. If so, record only the durable result:
+
+- observable behavior, contract, invariant, or non-goal → capability spec;
+- long-lived implementation constraint, boundary, recurring pitfall, or required verification practice → engineering spec;
+- important architectural choice, rationale, or revisit condition → decision.
+
+If nothing durable was learned, do not modify specs. Do not record current task status, implementation progress, temporary debugging notes, one-off commands, session history, Todo items, or transient observations. Specs accumulate durable project knowledge, not development activity.
+
 For meaningful durable behavior/contract changes, use one change file with only the needed `ADD`, `MODIFY`, `REMOVE`, and/or `PRESERVE` sections. After acceptance and implementation, merge durable results into living specs and delete the change file. Git is the history.
 
 Charterleaf is a knowledge layer, not a workflow layer. It must not manage tasks, planning, agents, execution, review, memory, compression, semantic search, code/spec verification, release lifecycle, or Git history.

package/README.md

@@ -7,9 +7,10 @@ without workflow orchestration.
 
 > **Keep project intent in the repo, without turning specs into a workflow.**
 
-Charterleaf keeps durable project knowledge in Markdown and provides exactly two deterministic helpers:
+Charterleaf keeps durable project knowledge in Markdown and provides exactly three deterministic helpers:
 
 ```bash
+charterleaf map
 charterleaf related <path>
 charterleaf lint
 ```
@@ -37,10 +38,13 @@ No Pi extension or Pi runtime dependency is used.
 Run from a repository root containing `specs/`:
 
 ```bash
+charterleaf map
 charterleaf related src/auth/session.ts
 charterleaf lint
 ```
 
+`map` shows a deterministic, lightweight index of the `specs/` layer when a relevant code path is not yet known. It lists specification scopes and metadata only; it does not summarize specs or recommend what to read. Use normal code navigation to find the smallest relevant area, then use `related <path>`.
+
 `related <path>` performs deterministic path routing. It matches `applies_to` with `*` and `**`, normalizes repo-relative paths to POSIX form, then appends active changes whose `affects` reference a matched Spec ID. Output is stable; no match is success. It is not semantic search.
 
 `lint` performs mechanical checks only: frontmatter shape, living Spec IDs, duplicate requirement IDs, change references, static `ADD` / `MODIFY` / `REMOVE` references, and conflicting active changes that touch the same requirement ID. It does not judge wording, architecture quality, or semantic code/spec drift.
@@ -74,6 +78,8 @@ Keep specs compressed and evidence-based. Prefer contracts over commentary and r
 
 For bug fixes with durable behavioral implications, clarify `Current`, `Expected`, and `PRESERVE` when that reduces accidental scope. Do not create a spec for trivial fixes with no durable implication.
 
+After non-trivial implementation or debugging, record only genuinely durable knowledge: behavior, contracts, invariants, and non-goals in capabilities; long-lived constraints, boundaries, pitfalls, or verification practices in engineering; and important architectural choices in decisions. If nothing durable was learned, do not modify specs. Specs accumulate durable project knowledge, not development activity.
+
 Load the smallest relevant set; do not read the whole tree by default. After an accepted change is implemented, merge the durable result into living specs and delete the change file. Git is the history.
 
 ## Other agents
@@ -98,7 +104,7 @@ Charterleaf has no:
 - plugin/extension runtime
 - Git/history abstraction
 
-The two CLI commands are helpers, not workflow gates.
+The three CLI commands are helpers, not workflow gates.
 
 ## Development
 

package/lib/charterleaf.js

@@ -225,6 +225,84 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
   return 0;
 }
 
+function writeLivingSpecs(stdout, documents) {
+  for (const document of documents) {
+    const id = typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '';
+    const appliesTo = Array.isArray(document.frontmatter.applies_to)
+      ? document.frontmatter.applies_to.join(', ')
+      : String(document.frontmatter.applies_to || '');
+    write(stdout, `  ${id || '(missing id)'}`);
+    write(stdout, `    ${document.display}`);
+    write(stdout, `    applies_to: ${appliesTo}`);
+  }
+}
+
+function map(cwd = process.cwd(), streams = {}) {
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const specRoot = path.join(cwd, 'specs');
+  if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
+    write(stderr, 'ERROR specs/: not found');
+    return 2;
+  }
+
+  const documents = [];
+  const errors = [];
+  for (const filePath of walkMarkdown(specRoot)) {
+    const display = relativeDisplay(filePath, cwd);
+    try {
+      const { frontmatter } = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
+      documents.push({
+        filePath,
+        display,
+        frontmatter: frontmatter || {},
+        relative: path.relative(specRoot, filePath).replaceAll('\\', '/'),
+      });
+    } catch (error) {
+      errors.push(`ERROR ${display}: ${error.message}`);
+    }
+  }
+  if (errors.length) {
+    for (const error of errors) write(stderr, error);
+    return 2;
+  }
+
+  const constitution = [];
+  const capabilities = [];
+  const engineering = [];
+  const decisions = [];
+  const changes = [];
+  for (const document of documents) {
+    if (document.relative === 'constitution.md') constitution.push(document);
+    else if (document.relative.startsWith('capabilities/')) capabilities.push(document);
+    else if (document.relative.startsWith('engineering/')) engineering.push(document);
+    else if (document.relative.startsWith('decisions/')) decisions.push(document);
+    else if (document.relative.startsWith('changes/')) changes.push(document);
+  }
+
+  write(stdout, 'Constitution');
+  for (const document of constitution) write(stdout, `  ${document.display}`);
+  write(stdout, '');
+  write(stdout, 'Capabilities');
+  writeLivingSpecs(stdout, capabilities);
+  write(stdout, '');
+  write(stdout, 'Engineering');
+  writeLivingSpecs(stdout, engineering);
+  write(stdout, '');
+  write(stdout, 'Decisions');
+  for (const document of decisions) write(stdout, `  ${document.display}`);
+  write(stdout, '');
+  write(stdout, 'Active changes');
+  for (const document of changes) {
+    const affects = Array.isArray(document.frontmatter.affects)
+      ? document.frontmatter.affects.join(', ')
+      : String(document.frontmatter.affects || '');
+    write(stdout, `  ${document.display}`);
+    write(stdout, `    affects: ${affects}`);
+  }
+  return 0;
+}
+
 function isLivingSpec(filePath, specRoot) {
   const relative = path.relative(specRoot, filePath).replaceAll('\\', '/').split('/');
   return relative.length >= 2 && (relative[0] === 'capabilities' || relative[0] === 'engineering');
@@ -306,6 +384,12 @@ function lint(cwd = process.cwd(), streams = {}) {
           ids.set(specId, filePath);
         }
       }
+
+      if (!Object.hasOwn(frontmatter, 'applies_to')) {
+        errors.push([display, 'missing applies_to']);
+      } else if (Array.isArray(frontmatter.applies_to) && frontmatter.applies_to.length === 0) {
+        errors.push([display, 'applies_to must contain at least one path']);
+      }
     }
 
     for (const field of ['applies_to', 'tags']) {
@@ -443,6 +527,7 @@ function helpText() {
     'Usage: charterleaf <command> [args]',
     '',
     'Commands:',
+    '  map             show the specification map',
     '  related <path>  find specs matching a repo-relative code path',
     '  lint            check Charterleaf structural conventions',
   ].join('\n');
@@ -463,6 +548,14 @@ function main(argv = process.argv.slice(2), cwd = process.cwd(), streams = {}) {
   if (!argv.length) return usageError('a command is required', streams);
 
   const [command, ...rest] = argv;
+  if (command === 'map') {
+    if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
+      write(streams.stdout || process.stdout, 'Usage: charterleaf map');
+      return 0;
+    }
+    if (rest.length) return usageError('map takes no arguments', streams);
+    return map(path.resolve(cwd), streams);
+  }
   if (command === 'related') {
     if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
       write(streams.stdout || process.stdout, 'Usage: charterleaf related <path>');
@@ -488,6 +581,7 @@ module.exports = {
   globMatches,
   lint,
   main,
+  map,
   normalizeRepoPath,
   parseFrontmatter,
   related,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onedotmint/charterleaf",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A tiny specification layer for coding agents.",
   "license": "MIT",
   "repository": {

package/skills/charterleaf/SKILL.md

@@ -13,7 +13,17 @@ When a concrete code path is known, run:
 charterleaf related <path>
 ```
 
-Read only the returned living specs and active changes. If the location is unknown, use the host agent's normal search tools; Charterleaf does not provide semantic search.
+Read only the returned living specs and active changes.
+
+When the relevant code path is not yet known, run:
+
+```bash
+charterleaf map
+```
+
+Use the map only to discover available specification scopes. Do not read every listed specification by default. Use normal code navigation to locate the smallest relevant area. Once a concrete path is known, run `charterleaf related <path>`.
+
+For broad project-level questions, start with normal project entry documents. Do not expand into every spec or project-state document merely because no path was provided. `map` is not semantic search.
 
 Use authority in this order:
 
@@ -25,6 +35,14 @@ Keep specs compressed and evidence-based. Prefer contracts over commentary and d
 
 Do not touch specs for renames, lint cleanup, routine refactors, temporary debugging, Todo/status changes, or trivial fixes with no durable implication.
 
+After non-trivial implementation or debugging, consider whether durable project knowledge was discovered. If so, record only the durable result:
+
+- observable behavior, contract, invariant, or non-goal → capability spec;
+- long-lived implementation constraint, boundary, recurring pitfall, or required verification practice → engineering spec;
+- important architectural choice, rationale, or revisit condition → decision.
+
+If nothing durable was learned, do not modify specs. Do not record current task status, implementation progress, temporary debugging notes, one-off commands, session history, Todo items, or transient observations. Specs accumulate durable project knowledge, not development activity.
+
 For a durable bug fix, use `Current` and `Expected` when useful and state what must `PRESERVE`. For other durable behavior/contract changes, keep one `specs/changes/<name>.md` delta with only needed `ADD`, `MODIFY`, `REMOVE`, and/or `PRESERVE` sections.
 
 After editing specs, run: