@ericrisco/rsc 3.0.22 → 3.1.0

package/README.md

@@ -424,6 +424,10 @@ rsc agent-model opencode inherit     # agents use the session's model
 rsc agents status | reset <name>     # installed agents, and the ones you edited
 rsc review consolidate c.md s.md t.md  # merge reviewer findings; serious ones go to finding-verifier
 
+# Documentation
+rsc ingest notas.md --topic crm      # move a file into 02-DOCS/raw/ (verified copy), then document it
+rsc copy rules | check ad.txt        # the phrases this project forbids, and a check before publishing
+
 # Memory and diagnostics
 rsc memory status | off | resume
 rsc doctor                           # harness health and onboarding readiness

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.22",
+  "version": "3.1.0",
   "counts": {
     "skills": 271,
     "agents": 34,
@@ -2310,7 +2310,7 @@
     },
     {
       "id": "harness",
-      "description": "Use when governing a workspace's control plane, code or not — the `01-TOOLS/` tooling layer, the `02-DOCS/` chaos→knowledge wiki, the root Knowledge map. Audits it, migrates legacy `XX-*` folders, scaffolds provider tooling, sweeps the inbox, writes root CLAUDE.md/AGENTS.md. NOT the bootstrap front door (that is `init`, which hands off here).",
+      "description": "Use when governing a workspace's control plane, code or not — the `01-TOOLS/` tooling layer, the `02-DOCS/` chaos→knowledge wiki, the root Knowledge map. Audits it, migrates legacy `XX-*` folders, scaffolds provider tooling, sweeps the inbox, eats a file the person hands over (\\\"cómete este fichero\\\", \\\"guárdalo en la documentación\\\": moved into 02-DOCS/raw/ and documented), writes root CLAUDE.md/AGENTS.md. NOT the bootstrap front door (that is `init`, which hands off here).",
       "tags": [
         "harness",
         "company",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.0.22",
+  "version": "3.1.0",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/lib/ingest-move.js

@@ -0,0 +1,95 @@
+// `rsc ingest <file>`: a document the person hands to the harness ends up in 02-DOCS/raw/ and leaves
+// the place it was dropped.
+//
+// The harness skill already said loose root files MOVE into raw/. The text injected at every session
+// start said "originals are copied, never moved", and an agent obeys what it reads every session: the
+// root kept every file it had already documented. A move that deletes is the kind of step an agent
+// should not improvise, so it lives here, with one rule that makes it safe: the original is removed
+// only after the copy in raw/ is proven byte-identical by its hash. The agent then compiles the wiki
+// from that copy, so nothing it learned depends on the file that was removed.
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+// Never moved: the project's own files, secrets, code, and the harness. Moving any of these would
+// break the project, leak a secret into the docs, or eat the documentation itself.
+const PROTECTED_DIRS = new Set(['02-DOCS', '01-TOOLS', '.git', '.rsc', '.claude', '.worktrees', 'node_modules', '.github', '.codex', '.cursor', '.gemini', '.opencode']);
+const PROTECTED_NAMES = /^(?:package(?:-lock)?\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|readme(?:\.\w+)?|license(?:\.\w+)?|licence(?:\.\w+)?|changelog(?:\.\w+)?|claude\.md|agents\.md|gemini\.md|\.rsc\.json|\.rscignore|\.gitignore|\.gitattributes|\.npmrc|\.nvmrc|makefile|dockerfile|docker-compose\.ya?ml|compose\.ya?ml|tsconfig(?:\.\w+)?\.json|jsconfig\.json|pyproject\.toml|requirements(?:[-.\w]*)?\.txt|setup\.(?:py|cfg)|go\.(?:mod|sum)|cargo\.(?:toml|lock)|composer\.(?:json|lock)|gemfile(?:\.lock)?|pubspec\.(?:yaml|lock)|.*\.config\.\w+)$/i;
+const SECRET = /^\.env(?:\..*)?$|\.(?:pem|key|p12|pfx|keystore|jks)$|^id_(?:rsa|ed25519|ecdsa)/i;
+const CODE = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.kts', '.swift', '.rb', '.php', '.cs', '.c', '.cc', '.cpp', '.h', '.hpp', '.m', '.dart', '.vue', '.svelte', '.sh', '.bash', '.zsh', '.ps1', '.bat', '.lua', '.scala', '.ex', '.exs', '.erl']);
+
+const sha256 = (path) => `sha256:${createHash('sha256').update(readFileSync(path)).digest('hex')}`;
+const posix = (p) => p.split(sep).join('/');
+const today = (now) => now.toISOString().slice(0, 10);
+
+function refusal(root, rel) {
+  const parts = rel.split('/');
+  if (PROTECTED_DIRS.has(parts[0])) return `${parts[0]}/ belongs to the harness or the project; it is never moved`;
+  const name = basename(rel);
+  if (SECRET.test(name)) return 'it looks like a secret; secrets never go into the documentation';
+  if (PROTECTED_NAMES.test(name)) return 'it is a project file the code or the assistant relies on';
+  if (CODE.has(extname(name).toLowerCase())) return 'it is source code; document it without moving it (use --keep)';
+  return null;
+}
+
+/** A free name in raw/ for this content: the same name, or the same content already there, or a dated variant. */
+function rawTarget(rawDir, name, hash, now) {
+  const first = join(rawDir, name);
+  if (!existsSync(first) || sha256(first) === hash) return first;
+  const ext = extname(name), stem = basename(name, ext);
+  const stamp = now.toISOString().replace(/[-:]/g, '').slice(0, 15);
+  for (let i = 0; i < 1000; i++) {
+    const candidate = join(rawDir, `${stem}-${stamp}${i ? `-${i}` : ''}${ext}`);
+    if (!existsSync(candidate) || sha256(candidate) === hash) return candidate;
+  }
+  return null;
+}
+
+function recordInLedger(root, key, entry) {
+  const path = join(root, '02-DOCS', 'wiki', '.ingested.json');
+  let ledger = {};
+  try { ledger = JSON.parse(readFileSync(path, 'utf8')); } catch { /* new or unreadable: start fresh */ }
+  if (!ledger || typeof ledger !== 'object' || Array.isArray(ledger)) ledger = {};
+  ledger[key] = { ...(ledger[key] || {}), ...entry };
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(ledger, null, 2) + '\n');
+  renameSync(tmp, path);
+}
+
+/**
+ * Move (or with keep, copy) one file into 02-DOCS/raw/.
+ * Returns { file, status: 'moved'|'copied'|'refused'|'missing', raw?, hash?, reason? }.
+ */
+export function ingestFile(root, input, { keep = false, topic = '', now = new Date() } = {}) {
+  const projectRoot = resolve(root);
+  const abs = resolve(projectRoot, input);
+  const rel = posix(relative(projectRoot, abs));
+  const out = { file: isAbsolute(input) ? input : posix(input) };
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) return { ...out, status: 'refused', reason: 'it is outside this project' };
+  if (!existsSync(join(projectRoot, '02-DOCS'))) return { ...out, status: 'refused', reason: 'this project has no 02-DOCS/ yet; set up the harness first' };
+  let st;
+  try { st = lstatSync(abs); } catch { return { ...out, status: 'missing', reason: 'no such file' }; }
+  if (st.isSymbolicLink()) return { ...out, status: 'refused', reason: 'it is a link; ingest the file it points to' };
+  if (st.isDirectory()) return { ...out, status: 'refused', reason: 'it is a folder; name the files inside it' };
+  if (!st.isFile()) return { ...out, status: 'refused', reason: 'it is not a regular file' };
+  const why = refusal(projectRoot, rel);
+  if (why) return { ...out, status: 'refused', reason: why };
+
+  const hash = sha256(abs);
+  // raw/<topic>/ is where the wiki convention files a source; choosing it here means the copy is never
+  // moved afterwards, which would leave the ledger pointing at a path that no longer exists.
+  const slug = String(topic || '').trim().toLowerCase().normalize('NFD').replace(/\p{M}/gu, '').replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (topic && !slug) return { ...out, status: 'refused', reason: `'${topic}' is not a usable topic name` };
+  const rawDir = slug ? join(projectRoot, '02-DOCS', 'raw', slug) : join(projectRoot, '02-DOCS', 'raw');
+  mkdirSync(rawDir, { recursive: true });
+  const target = rawTarget(rawDir, basename(rel), hash, now);
+  if (!target) return { ...out, status: 'refused', reason: 'no free name in 02-DOCS/raw/' };
+  if (!existsSync(target)) copyFileSync(abs, target);
+  // The only rule that makes the delete safe: the copy is proven identical before the original goes.
+  if (sha256(target) !== hash) return { ...out, status: 'refused', reason: 'the copy in raw/ did not verify; the original was left in place' };
+  const rawRel = posix(relative(projectRoot, target));
+  recordInLedger(projectRoot, rel, { hash, ingested: today(now), raw: rawRel });
+  if (keep) return { ...out, status: 'copied', raw: rawRel, hash };
+  unlinkSync(abs);
+  return { ...out, status: 'moved', raw: rawRel, hash };
+}

package/scripts/rsc.js

@@ -46,7 +46,7 @@ if (['--version', '-v', 'version'].includes(rawArgv[0])) {
   process.exit(0);
 }
 const GENERAL_HELP = [
-  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | agent-model <target> <model|inherit|status> | agents [status|reset <name|--all>] | memory <on|off|status|save|resume|learn|metrics> | review consolidate [reports…] | copy check <file> | copy rules | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
+  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | agent-model <target> <model|inherit|status> | agents [status|reset <name|--all>] | memory <on|off|status|save|resume|learn|metrics> | review consolidate [reports…] | ingest <file...> | copy check <file> | copy rules | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
   'Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)',
   '   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.',
 ].join('\n');
@@ -75,9 +75,9 @@ const PURGE_HELP = [
 // `--accompaniment` stays listed although the dial is retired: old scripts and agents still pass it,
 // and its value must keep being skipped rather than read as a command or a skill id.
 const GLOBAL_VALUE_FLAGS = new Set([
-  '--target', '--technical-level', '--accompaniment', '--project-kind', '--goal', '--goal-base64', '--software-scope', '--workflow', '--accept-plan',
+  '--topic', '--target', '--technical-level', '--accompaniment', '--project-kind', '--goal', '--goal-base64', '--software-scope', '--workflow', '--accept-plan',
 ]);
-const COMMANDS = new Set(['copy', 'onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'git-permissions', 'agent-model', 'agents', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'review', 'sello', 'repair', 'uninstall', 'purge']);
+const COMMANDS = new Set(['ingest', 'copy', 'onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'git-permissions', 'agent-model', 'agents', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'review', 'sello', 'repair', 'uninstall', 'purge']);
 function positionalTokens(input) {
   const out = [];
   for (let i = 0; i < input.length; i++) {
@@ -1181,6 +1181,27 @@ async function main() {
       say('Use: npx @ericrisco/rsc registry refresh | registry status');
       return;
     }
+    case 'ingest': {
+      // "Eat this file": into 02-DOCS/raw/, verified, then gone from where it was dropped (lib/ingest-move.js).
+      const USE = 'Use: npx @ericrisco/rsc ingest <file...> [--topic <topic>] [--keep] [--json]\n  Moves each file into 02-DOCS/raw/ (the copy is verified first, then the original is removed) and records it in 02-DOCS/wiki/.ingested.json.\n  --keep copies without removing. Project files, code and secrets are refused.';
+      const rest = argv.slice(1);
+      const files = rest.filter((a, i) => !a.startsWith('--') && rest[i - 1] !== '--topic');
+      if (!files.length) { say(USE); process.exitCode = 1; return; }
+      const { ingestFile } = await import('./lib/ingest-move.js');
+      const topic = flag('topic') || '';
+      const results = files.map((f) => ingestFile(process.cwd(), f, { keep: argv.includes('--keep'), topic }));
+      if (argv.includes('--json')) say(JSON.stringify(results, null, 2));
+      else {
+        const lines = results.map((r) => r.status === 'moved' ? `RSC_INGEST_MOVED ${r.file} → ${r.raw}`
+          : r.status === 'copied' ? `RSC_INGEST_COPIED ${r.file} → ${r.raw}`
+          : r.status === 'missing' ? `RSC_INGEST_MISSING ${r.file}: ${r.reason}`
+          : `RSC_INGEST_REFUSED ${r.file}: ${r.reason}`);
+        if (results.some((r) => r.raw)) lines.push('Next: read each raw/ copy and compile it into 02-DOCS/wiki/ (update before create, cross-links, wiki/index.md, wiki/log.md), then tell the person where it lives now.');
+        say(lines.join('\n'));
+      }
+      if (results.some((r) => r.status === 'refused' || r.status === 'missing')) process.exitCode = 1;
+      return;
+    }
     case 'copy': {
       // The phrases this project forbids in what it publishes (targets/copy-rules.mjs). `check` is the
       // gate the copy skills run before delivering text; the Claude Stop hook runs the same check.

package/skills/harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: harness
-description: "Use when governing a workspace's control plane, code or not — the `01-TOOLS/` tooling layer, the `02-DOCS/` chaos→knowledge wiki, the root Knowledge map. Audits it, migrates legacy `XX-*` folders, scaffolds provider tooling, sweeps the inbox, writes root CLAUDE.md/AGENTS.md. NOT the bootstrap front door (that is `init`, which hands off here)."
+description: "Use when governing a workspace's control plane, code or not — the `01-TOOLS/` tooling layer, the `02-DOCS/` chaos→knowledge wiki, the root Knowledge map. Audits it, migrates legacy `XX-*` folders, scaffolds provider tooling, sweeps the inbox, eats a file the person hands over (\"cómete este fichero\", \"guárdalo en la documentación\": moved into 02-DOCS/raw/ and documented), writes root CLAUDE.md/AGENTS.md. NOT the bootstrap front door (that is `init`, which hands off here)."
 tags: [harness, company, ops, docs, wiki, connect, tools, knowledge]
 recommends: [init, connect-tool]
 profiles: [minimal, core, full]
@@ -27,6 +27,14 @@ The **harness** is the control plane of a workspace. A workspace need not be cod
   Ingest relocates, never deletes: a loose file at the workspace root moves into `raw/`; a file
   inside a folder the user maintains is copied, and consolidating that folder needs explicit consent.
 
+  **When the person hands you a file** ("cómete este fichero", "guárdalo en la documentación",
+  "ingest this"): run `npx @ericrisco/rsc ingest <file> --topic <topic>`. It moves the file into
+  `02-DOCS/raw/<topic>/` only after the copy is verified, and records it in `wiki/.ingested.json`.
+  Never move or rename that raw copy afterwards: the ledger points at it. Then compile from the raw copy
+  into `wiki/` (update before create, cross-links, `index.md`, `log.md`) and say in one line where it
+  lives now. The file must not stay in the root. A refused file (project file, code, secret) stays
+  where it is: say why; `--keep` documents it without moving it.
+
   The `wiki/` is simultaneously an OKF-v0.1 bundle
   ([Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf))
   and an Obsidian-native vault: markdown links, YAML frontmatter, readable filenames, `.base` views

package/skills/harness/references/wiki-protocol.md

@@ -522,7 +522,8 @@ Un-ingested = path absent OR hash changed. `inbox/` files still move to
 - **Clean-as-you-go.** Loose root-level files and `inbox/` contents are **moved**
   into `raw/` after a verified ingest (the repo stays clean); files nested in a
   user-maintained folder are **copied** and consolidation is proposed with consent.
-  A move never precedes the original being safely written to `raw/`.
+  A move never precedes the original being safely written to `raw/`: use
+  `npx @ericrisco/rsc ingest <file>`, which verifies the copy by hash before removing the original.
 - **Never delete.** The original is relocated into `raw/`, never destroyed.
   Removing an emptied/redundant folder is quoted-consent only.
 - **Ambiguity is proposed, not grabbed.**

package/targets/session-start.mjs

@@ -179,7 +179,9 @@ if (existsSync(join(root, '02-DOCS', 'wiki')) && existsSync(inbox)) {
 Un-ingested material is waiting in 02-DOCS/inbox/.
 ACTION: run the Auto-Ingest Sweep now — ingest inbox/, then scan the workspace
 (minus .rscignore) for un-ingested documents, recording them in wiki/.ingested.json.
-Originals are copied, never moved; deleting an emptied folder needs explicit consent.
+Loose root files and inbox/ files move into raw/ with \`npx @ericrisco/rsc ingest <file>\`
+(verified copy, then removed); files inside the person's own folders are copied; deleting a
+folder needs explicit consent.
 ===========================
 `);
   }