renma 0.15.2 → 0.17.0

package/examples/interactive-placeholder/README.md

@@ -0,0 +1,104 @@
+# Interactive Placeholder Example
+
+This small example demonstrates a clarify-before-act interaction described by
+a governed Skill. A consuming agent prepares and inspects a disposable file,
+asks one focused question when a value is missing, waits, applies the validated
+answer with a local CLI, and verifies the result.
+
+A Skill can define a clarify-before-act interaction: inspect the current state,
+ask for missing information, wait, and act only after the user supplies it.
+
+## Responsibility Boundary
+
+Renma:
+
+- discovers and validates the Skill and repository assets;
+- checks workflow clarity, required inputs, helper-command paths, metadata,
+  security policy, and repository structure; and
+- provides deterministic scan and readiness evidence.
+
+Renma does not run the interaction, execute the Node.js tool, ask the user,
+store conversational state, or resume the workflow.
+
+The consuming agent:
+
+- follows [`skills/replace-placeholder/SKILL.md`](skills/replace-placeholder/SKILL.md);
+- runs the fixed local CLI commands;
+- notices the missing replacement, asks one question, and waits;
+- validates the user's answer before applying it; and
+- inspects and reports the result.
+
+The user supplies the missing value, can inspect the resulting file, and
+retains final control over it.
+
+## Prerequisites
+
+- Node.js 22 or newer for the local demonstration.
+- A built Renma checkout for the `node dist/index.js` inspection commands.
+- Run the Renma commands below from the repository root.
+
+## Inspect With Renma
+
+```bash
+npm run build
+node dist/index.js scan examples/interactive-placeholder --fail-on high
+node dist/index.js catalog examples/interactive-placeholder --format markdown
+node dist/index.js readiness examples/interactive-placeholder --format markdown
+node dist/index.js inspect examples/interactive-placeholder/skills/replace-placeholder/SKILL.md
+```
+
+With an installed CLI, the equivalent commands are:
+
+```bash
+renma scan examples/interactive-placeholder --fail-on high
+renma catalog examples/interactive-placeholder --format markdown
+renma readiness examples/interactive-placeholder --format markdown
+renma inspect examples/interactive-placeholder/skills/replace-placeholder/SKILL.md
+```
+
+## Try The Interaction
+
+Change into the example directory, then prepare and inspect the disposable
+output:
+
+```bash
+cd examples/interactive-placeholder
+node tools/placeholder-demo.mjs prepare
+node tools/placeholder-demo.mjs inspect
+```
+
+Expected state:
+
+```text
+State: waiting for a replacement value (<placeholder> remains).
+```
+
+At this boundary, the consuming agent asks for one value matching
+`[A-Za-z0-9_-]{1,32}` and waits without modifying the file. After the user
+supplies a valid value, for example `Renma_017`, the agent passes it as one
+argument and verifies the result:
+
+```bash
+node tools/placeholder-demo.mjs apply Renma_017
+node tools/placeholder-demo.mjs inspect
+```
+
+Expected verification:
+
+```text
+State: complete. Hello, Renma_017!
+```
+
+Run `node tools/placeholder-demo.mjs prepare` at any time to recreate
+`workspace/output.txt` from the immutable `assets/template.txt`. The generated
+output is ignored by Git, so repeating the example does not modify a tracked
+fixture.
+
+## Intentionally Not Demonstrated
+
+This example does not add a Renma runtime feature, Context Asset, Context Lens,
+workflow state machine, platform Plan mode, runtime Skill selection, prompt
+assembly, provider integration, agent execution, automatic question asking,
+automatic resume, network access, uploads, or repository rewriting. It isolates
+one interaction pattern that an external consuming agent can execute from a
+statically governed Skill.

package/examples/interactive-placeholder/assets/template.txt

@@ -0,0 +1 @@
+Hello, <placeholder>!

package/examples/interactive-placeholder/renma.config.json

@@ -0,0 +1,6 @@
+{
+  "fail_on": "high",
+  "format": "text",
+  "globs": ["skills/**/SKILL.md", "tools/**/*", "README.md"],
+  "exclude": ["node_modules", "dist", ".git", "workspace"]
+}

package/examples/interactive-placeholder/skills/replace-placeholder/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: replace-placeholder
+description: Prepare this example's disposable placeholder file, ask for a constrained replacement, then apply and verify it. Use only for interactive-placeholder; do not use for arbitrary text, other files, or unattended edits.
+metadata:
+  renma.id: skill.example.replace-placeholder
+  renma.owner: maintainers
+  renma.allowed-data: '["repo-local-files","disclosed-user-provided-data"]'
+  renma.network-allowed: "false"
+  renma.external-upload-allowed: "false"
+  renma.secrets-allowed: "false"
+  renma.requires-human-approval: "false"
+  renma.forbidden-inputs: '["secrets","credentials","personal-data"]'
+---
+
+# Replace Placeholder
+
+## Routing
+
+Use only in `examples/interactive-placeholder`. The consuming agent follows the
+[local tool guide](../../tools/README.md). Renma validates the repository; the
+agent owns the interaction and tool use.
+
+## Required Inputs And Preflight
+
+- The example files and write permission for `workspace/output.txt`.
+- One user value matching `[A-Za-z0-9_-]{1,32}`, initially missing.
+
+## Clarify-Before-Act Workflow
+
+1. Follow the guide's `prepare` and `inspect` operations.
+2. If inspection shows a missing replacement, ask one focused question for an
+   accepted value, then stop and wait.
+3. Validate the response without changing it.
+4. For a valid response, follow the guide's `apply` and `inspect` operations.
+5. Verify the placeholder is absent and the value is present, then report the
+   inspected result for human review.
+
+## Hard Constraints
+
+- Use only the fixed guide and its anchored paths.
+- If the value is missing, ask one focused question and stop.
+- If the value is invalid, explain the accepted format, ask again, and stop.
+- Never guess, transform, or truncate the value; ask again instead.
+- Do not request or accept secrets, credentials, or personal data; ask for a non-sensitive value instead.
+- Do not apply when `<placeholder>` is absent; stop and report the inspected state.
+- Do not edit the Skill, READMEs, or immutable template; leave them unchanged.
+- Do not access the network, upload data, or write outside the example workspace; stop and report the blocked operation.
+- A human retains final control over the inspected result.
+
+## Completion Criteria
+
+Complete only after the documented `apply` succeeds and `inspect` returns
+`State: complete` with the user value and no `<placeholder>`. Report this
+evidence.

package/examples/interactive-placeholder/tools/README.md

@@ -0,0 +1,48 @@
+# Placeholder Tool Guide
+
+This local tool is the fixed operational contract for the
+`replace-placeholder` Skill. Run it from `examples/interactive-placeholder`.
+It accepts no file path, performs no network or upload operation, and writes
+only the disposable `workspace/output.txt` file.
+
+## Commands
+
+Prepare or reset the output from the immutable template, then inspect it:
+
+```bash
+node tools/placeholder-demo.mjs prepare
+node tools/placeholder-demo.mjs inspect
+```
+
+After a user supplies a value matching `[A-Za-z0-9_-]{1,32}`, pass the
+validated value as exactly one argument and inspect the result:
+
+```bash
+node tools/placeholder-demo.mjs apply EXAMPLE_VALUE
+node tools/placeholder-demo.mjs inspect
+```
+
+Pass the value as an argument, never as interpolated shell source. The tool
+rejects missing, extra, or invalid arguments and never accepts a destination
+path.
+
+## Behavior
+
+- `prepare` creates `workspace/output.txt` from `assets/template.txt`. It also
+  resets a completed output back to the missing-value state.
+- `apply` accepts one constrained value and replaces `<placeholder>` only while
+  that marker is present.
+- `inspect` reports either the waiting state with `<placeholder>` or the
+  complete state with the rendered value.
+- `assets/template.txt` remains immutable, while the ignored workspace output
+  is disposable and safe to remove.
+
+## Failure And Stop Behavior
+
+- If the output is missing, run `prepare` before inspecting or applying.
+- If the value does not match `[A-Za-z0-9_-]{1,32}`, explain the format, ask
+  again, and stop without applying.
+- If `<placeholder>` is absent, stop and report the current state; use
+  `prepare` only when the user wants to reset the demonstration.
+- If the template lacks `<placeholder>` or a local filesystem operation fails,
+  stop and report the error. Leave tracked files unchanged.

package/examples/interactive-placeholder/tools/placeholder-demo.mjs

@@ -0,0 +1,99 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PLACEHOLDER = "<placeholder>";
+const VALUE_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+const TOOL_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const EXAMPLE_ROOT = path.resolve(TOOL_DIRECTORY, "..");
+const TEMPLATE_PATH = anchoredPath("assets", "template.txt");
+const WORKSPACE_PATH = anchoredPath("workspace");
+const OUTPUT_PATH = anchoredPath("workspace", "output.txt");
+
+const [command, ...args] = process.argv.slice(2);
+
+try {
+  if (command === "prepare") {
+    requireArgumentCount(command, args, 0);
+    await prepare();
+  } else if (command === "apply") {
+    requireArgumentCount(command, args, 1);
+    await apply(args[0]);
+  } else if (command === "inspect") {
+    requireArgumentCount(command, args, 0);
+    await inspect();
+  } else {
+    fail(
+      "Usage: node tools/placeholder-demo.mjs <prepare|apply VALUE|inspect>",
+    );
+  }
+} catch (error) {
+  if (error instanceof Error) fail(error.message);
+  fail("Unexpected local filesystem error.");
+}
+
+function anchoredPath(...segments) {
+  const candidate = path.resolve(EXAMPLE_ROOT, ...segments);
+  const relative = path.relative(EXAMPLE_ROOT, candidate);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Refusing a path outside the example directory.");
+  }
+  return candidate;
+}
+
+function requireArgumentCount(selectedCommand, values, expected) {
+  if (values.length !== expected) {
+    throw new Error(`Invalid arguments for ${selectedCommand}.`);
+  }
+}
+
+async function prepare() {
+  const template = await readFile(TEMPLATE_PATH, "utf8");
+  if (!template.includes(PLACEHOLDER)) {
+    throw new Error("Immutable template does not contain <placeholder>.");
+  }
+  await mkdir(WORKSPACE_PATH, { recursive: true });
+  await writeFile(OUTPUT_PATH, template, "utf8");
+  process.stdout.write(
+    "Prepared workspace/output.txt: replacement value is missing (<placeholder>).\n",
+  );
+}
+
+async function apply(value) {
+  if (!VALUE_PATTERN.test(value ?? "")) {
+    throw new Error("Invalid value: expected [A-Za-z0-9_-]{1,32}.");
+  }
+  const output = await readOutput();
+  if (!output.includes(PLACEHOLDER)) {
+    throw new Error("Cannot apply: workspace/output.txt has no <placeholder>.");
+  }
+  await writeFile(OUTPUT_PATH, output.replaceAll(PLACEHOLDER, value), "utf8");
+  process.stdout.write(`Applied value ${value} to workspace/output.txt.\n`);
+}
+
+async function inspect() {
+  const output = await readOutput();
+  if (output.includes(PLACEHOLDER)) {
+    process.stdout.write(
+      "State: waiting for a replacement value (<placeholder> remains).\n",
+    );
+    return;
+  }
+  process.stdout.write(`State: complete. ${output.trim()}\n`);
+}
+
+async function readOutput() {
+  try {
+    return await readFile(OUTPUT_PATH, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error("workspace/output.txt is missing; run prepare first.");
+    }
+    throw error;
+  }
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renma",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "description": "Manage human-curated context assets for LLMs and agents in Git.",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,12 @@
   "files": [
     "dist",
     "scripts",
+    "docs",
+    "examples",
+    "architecture.md",
+    "design.md",
+    "plan.md",
+    "plan-discovery.md",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -44,6 +50,7 @@
     "format:check": "prettier --check \"**/*.{ts,js,mjs,json}\"",
     "lint": "eslint \"{src,test}/**/*.ts\" \"{scripts,tools}/**/*.mjs\" \"eslint.config.js\"",
     "lint:fix": "eslint --fix \"{src,test}/**/*.ts\" \"{scripts,tools}/**/*.mjs\" \"eslint.config.js\"",
+    "verify:package": "npm run build && node scripts/verify-package.mjs",
     "split-reference": "node scripts/split-reference.mjs",
     "suggest-semantic-split": "node dist/index.js suggest-semantic-split"
   },
@@ -55,5 +62,8 @@
     "prettier": "^3.5.3",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.61.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }