@rungs/cli 0.1.0 → 0.1.2

package/modules/findings/gates/findings.toml

@@ -33,6 +33,24 @@ non_empty = ["Sev", "Pri", "What", "Evidence"]
 enum      = { Sev = ["high", "medium", "low"], Pri = ["now", "next", "someday"] }
 placeholder_ok = ["none — hunch", "unknown"]
 
+# ── findings-self-declared-closure ───────────────────────────────────────────
+
+[self_declared_closure]
+file                    = "{{path}}"
+open_heading            = "Open"
+closed_heading          = "Closed"
+detail_heading          = "Detail"
+id_pattern              = "{{id_prefix}}-\\d{1,4}"
+open_row_pattern        = "^\\|\\s*\\[?({{id_prefix}}-\\d{1,4})\\]"
+detail_heading_pattern  = "^###\\s+({{id_prefix}}-\\d{1,4})\\s+—\\s+"
+exempt_marker           = "closure-ok:"
+declares_fixed          = [
+  "\\*\\*Fixed[.,)*]",
+  "\\*\\*Fixed\\s+(?:in|by|the\\s+same\\s+day|\\d{4}-\\d{2}-\\d{2})",
+  "\\*\\*Implemented in this change\\.?\\*\\*",
+  "\\*\\*fixed in the pass that found it\\*\\*",
+]
+
 # ── self-tests ────────────────────────────────────────────────────────────────
 
 [[self_test]]
@@ -55,6 +73,16 @@ gate    = "findings-disposition-has-reason"
 expect  = "pass"
 fixture = { table = "Open", row = { Id = "{{id_prefix}}-002", Sev = "high", Pri = "now", What = "x", Evidence = "none — hunch" } }
 
+[[self_test]]
+gate    = "findings-self-declared-closure"
+expect  = "fail"
+fixture = { open = ["{{id_prefix}}-001"], detail = "### {{id_prefix}}-001 — x\\n\\n**Fixed.**" }
+
+[[self_test]]
+gate    = "findings-self-declared-closure"
+expect  = "pass"
+fixture = { open = ["{{id_prefix}}-001"], detail = "### {{id_prefix}}-001 — x\\n\\n<!-- closure-ok: the mitigation only -->\\n**Fixed.**" }
+
 # ── findings-ids self-tests ───────────────────────────────────────────────────
 
 [[self_test]]

package/modules/findings/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "findings"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 1
 summary = "A register for what is noticed before it is decided, with a triage path into work items."
 
@@ -45,6 +45,14 @@ A finding closed without a written reason is indistinguishable from one nobody l
 is the same observation the next session will record again. The reason is what the register is for.
 """
 
+[[gates]]
+id     = "findings-self-declared-closure"
+kind   = "declared"
+engine = "self-declared-closure"
+table  = "gates/findings.toml"
+tier   = "fast"
+why    = "An open finding whose own detail says it is fixed contradicts the register; this narrow text check catches drift without pretending to prove code-level closure."
+
 # ── skills ────────────────────────────────────────────────────────────────────
 
 [skills.record-finding]

package/modules/gates/gates/structural.toml

@@ -70,6 +70,20 @@ gate   = "gates-links-resolve"
 expect = "pass"
 input  = "See [this table](./structural.toml)."
 
+# WI-008. A `${{token}}` used to exempt the whole file, so a document explaining templating stopped
+# being link-checked entirely — 16 files here, eight of them shipped. These two fix the boundary:
+# a broken link is caught even with a token elsewhere in the file, and a link that is *itself* a
+# template is not.
+[[self_test]]
+gate   = "gates-links-resolve"
+expect = "fail"
+input  = "Set `${{repo.dirname}}` first, then see [the plan](./does-not-exist.md)."
+
+[[self_test]]
+gate   = "gates-links-resolve"
+expect = "pass"
+input  = "The module writes [its readme](${{path}}/README.md) once installed."
+
 [[self_test]]
 gate   = "gates-paths-exist"
 expect = "pass"

package/modules/instructions/files/AGENTS.md

@@ -11,12 +11,6 @@ procedure belongs in a skill. Both load only when relevant, and this file has a
 
 <!-- One paragraph: what the project does, for whom, and the one property that must not break. -->
 
-## Repo map
-
-<!-- rungs:begin repo-map -->
-<!-- Generated. Run `rungs render` after moving directories. -->
-<!-- rungs:end repo-map -->
-
 ## Validation matrix
 
 **Run the narrowest validation that covers what you touched**, then the standard gates. Running

package/modules/instructions/fragments/AGENTS.md

@@ -0,0 +1,12 @@
+<!-- rungs:begin instructions@1.1.0 -->
+## Repo map
+
+<!-- rungs:begin repo-map -->
+<!-- Generated. Run `rungs render` after moving directories. -->
+<!-- rungs:end repo-map -->
+## Execution boundary
+
+Before an agent command runs, name the execution unit, what filesystem/environment/credential/network
+surfaces cross into it, and which controls are absent. This repository guidance declares boundaries;
+it does not install a sandbox, transport, rollback, or least-privilege runtime.
+<!-- rungs:end instructions -->

package/modules/instructions/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "instructions"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 0
 summary = "The agent entry point, the harness bridge, path-scoped rule sources, and the render pipeline. The one module every repo installs."
 
@@ -14,7 +14,11 @@ modules = []
 
 [params.project_name]
 description = "Name used in the entry document's first line"
-default     = ""            # inferred from the repo directory when blank
+default     = "{{repo.dirname}}"
+# `repo` is the reserved namespace, not a module — see modules/README.md rule 9b. This default was
+# `""` with a comment saying it was inferred from the directory, which nothing implemented, so every
+# scaffold's first line read `# AGENTS.md — ` with a dangling dash. Stating the inference where the
+# default is read is what makes it checkable (WI-001).
 
 [params.harnesses]
 description  = "Which coding agents to emit for. Drives the ADR-0001 render matrix."
@@ -103,7 +107,7 @@ paths   = { claude = ".claude/", copilot = ".github/instructions/", cursor = ".c
 # ── provenance (required, validated) ──────────────────────────────────────────
 
 [provenance]
-sources  = ["axiom-mesh", "hexguard", "hexguard-templates", "rift-forge"]
+sources  = ["axiom-mesh", "hexguard", "hexguard-templates", "rift-forge", "openhands"]
 patterns = [
   "entry-point",
   "agents-md-bridge",
@@ -116,6 +120,7 @@ patterns = [
   "comms-style",
   "shell-editing-rules",
   "instruction-hardening",
+  "isolation-boundary-declaration",
 ]
 incident = """
 All four source repos converged on a single canonical entry document, and all four put content in
@@ -124,4 +129,7 @@ targets was a dead redirect. hexguard-templates' repo map grew five duplicated e
 every session reads first, in the repo whose conventions forbid restating scope. rift-forge reached
 1513 lines with no path scoping at all, while hexguard had solved that with applyTo globs a month
 earlier. Nobody had both completeness and scope.
+OpenHands adds the missing execution boundary: a repository instruction can name the execution unit,
+the filesystem/environment/credential/network crossings, and the controls it does not supply, but
+it cannot install a sandbox or a rollback guarantee.
 """

package/modules/session/files/{{path}}

@@ -1,7 +1,8 @@
 # Session state
 
 The live handoff. **Rewritten as work moves, not appended to.** Everything here is present tense;
-history belongs in [`{{archive}}/`](archive/README.md).
+history belongs in [`{{archive}}/`](archive/README.md). This is narrative continuity, not a
+checkpoint, event stream, conversation memory, or audit record.
 
 Keep it short. This document is read at the start of every session, and a long one is skimmed.
 

package/modules/session/fragments/AGENTS.md

@@ -1,6 +1,9 @@
-<!-- rungs:begin session@1.0.0 -->
+<!-- rungs:begin session@1.1.0 -->
 ## Session state
 
 Read [`{{path}}`]({{path}}) first. Treat **Active constraints — do not reopen** as binding:
 settled decisions, not suggestions. Close a session with **`/close-session`**.
+The handoff is narrative continuity, not a checkpoint, event stream, conversation memory, or audit
+record. Events and archived notes remain inputs to accountability; they do not prove actor identity,
+retention, access control, request binding, or decision reasons by themselves.
 <!-- rungs:end session -->

package/modules/session/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "session"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 1
 summary = "A handoff document carrying state between sessions: resume point, active constraints, and a dated archive."
 
@@ -61,12 +61,15 @@ paths = [
 markers = ["rungs:begin session"]
 
 [provenance]
-sources  = ["axiom-mesh"]
-patterns = ["session-handoff", "settled-decisions-lock", "dated-session-archive"]
+sources  = ["axiom-mesh", "microsoft-agent-framework", "openhands"]
+patterns = ["session-handoff", "settled-decisions-lock", "dated-session-archive", "event-stream-not-audit-log"]
 incident = """
 axiom-mesh kept 21 dated handoff notes and a live session document with fixed sections, and its
 resume state is genuinely readable cold — the only repo of the four where a new session can start
 without reconstructing context from git. The section that earns its keep is "Active constraints /
 decisions since last archive", whose wording is a standing instruction not to reopen settled
 questions: "do not reopen helper ownership, topology, host-boundary … unless explicitly re-planned."
+The framework comparison narrows this handoff to narrative continuity: events and persisted history
+may inform an archive, but they are not an audit record without durability, retention, access control,
+actor identity, request binding, and decision reasons.
 """

package/modules/session/skills/close-session/SKILL.md

@@ -13,6 +13,10 @@ description: >-
 The test for everything below: **could a session starting cold tomorrow, with no memory of this
 conversation, pick up from the document alone?** If not, it is not closed.
 
+The handoff is narrative continuity, not a checkpoint, conversation memory, event stream, or audit
+record. An archive can point to evidence, but events and persisted history do not establish actor
+identity, retention, access control, request binding, or decision reasons by themselves.
+
 ## 1. Write the archive note
 
 `{{archive}}/YYYY-MM-DD_session-NN_<what-closed>-and-<what-is-next>.md`. The filename carries both

package/modules/skills/fragments/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- rungs:begin skills@1.0.0 -->
+<!-- rungs:begin skills@1.1.0 -->
 ## Skills
 
 Multi-step procedures live in [`{{dir}}/`]({{dir}}/) and load only when used. Authoring rules are

package/modules/skills/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "skills"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 2
 summary = "Skill-authoring discipline and the gates that hold it: spec-pure frontmatter, descriptions that route, neighbours named, and output that lands somewhere."
 
@@ -78,12 +78,15 @@ an open standard, so the portability objection that justified staying with plain
 """
 
 [provenance]
-sources  = ["rift-forge", "axiom-mesh", "hexguard"]
-patterns = ["invocable-procedure", "skill-neighbours", "prompt-writes-artifact", "operating-skills", "prompt-index-routing"]
+sources  = ["rift-forge", "axiom-mesh", "hexguard", "openai-agents-sdk", "microsoft-agent-framework"]
+patterns = ["invocable-procedure", "skill-neighbours", "prompt-writes-artifact", "operating-skills", "prompt-index-routing", "agent-facing-interface", "explicit-output-designation"]
 incident = """
 axiom-mesh wrote 21 prompt playbooks, several with no equivalent anywhere else, and gave them no
 invocation surface at all — they must be found, opened and pasted. hexguard-templates shipped the
 best decision procedure in the corpus behind a placeholder table. rift-forge, at 13 skills, had to
 invent the neighbour-naming convention because descriptions alone had stopped disambiguating
 /curate-mechanic from /curate-champion from /patch-ingest.
+The framework synthesis strengthens that convention: a skill must state who owns continuation, what
+state crosses its boundary, what it may mutate, what bounded output/status it leaves, and where an
+empty or failed result is recorded.
 """

package/modules/skills/rules/skill-authoring.md

@@ -59,6 +59,14 @@ A skill that only produces conversation evaporates. **Say in the body where the
 register row, a document at a known path, a status field. This is what makes a skill set compound
 instead of being re-derived every session.
 
+## Make the agent-facing contract explicit
+
+Describe the action shape, the state and observations the agent can see, and the bounded forms of
+empty, truncated, and failed output. Name who owns continuation, what state crosses the skill
+boundary, and what the skill may mutate. Public output is an allow-list of artifacts and statuses;
+internal tool visibility, graph connectivity, and event emission do not make something public by
+accident. If the skill delegates a capability, name the protocol or callback escape hatch.
+
 ## Write standing instructions, not one-time steps
 
 The rendered body enters the conversation once and stays for the session; it is not re-read on

package/modules/workflows/fragments/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- rungs:begin workflows@1.0.0 -->
+<!-- rungs:begin workflows@1.1.0 -->
 ## Planning
 
 Handed something larger than one change? **`/decompose`** — split into technical concerns, decide

package/modules/workflows/module.toml

@@ -1,6 +1,6 @@
 [module]
 name    = "workflows"
-version = "1.0.0"
+version = "1.1.0"
 rung    = 2
 summary = "Decision procedures: how to decompose work, whether to reuse or build, and how much planning a piece of work earns."
 
@@ -54,7 +54,7 @@ paths   = ["docs/plans/**/*.md", "docs/**/plan-*.md", "docs/.ai/backlog/plan-*.m
 markers = ["rungs:begin workflows"]
 
 [provenance]
-sources  = ["hexguard-templates", "hexguard", "rift-forge"]
+sources  = ["hexguard-templates", "hexguard", "rift-forge", "swe-agent", "pydantic-ai", "openai-agents-sdk", "microsoft-agent-framework"]
 patterns = [
   "reuse-decision-table",
   "second-consumer-threshold",
@@ -65,6 +65,13 @@ patterns = [
   "phase-checklist",
   "lifecycle-verbs",
   "controlled-performance-comparison",
+  "agent-facing-interface",
+  "bounded-agent-loop",
+  "ownership-changing-handoff",
+  "protocol-with-escape-hatch",
+  "resumable-approval-state",
+  "approval-bound-to-request",
+  "explicit-output-designation",
 ]
 incident = """
 hexguard-templates wrote the best decision procedure in the corpus — a nine-step workflow whose
@@ -72,4 +79,8 @@ tier table is introduced with "Use this table instead of 'use judgment'" — and
 invocation surface at all. Its AGENTS.md prompts table reads, verbatim: "No custom prompts or
 agents defined yet for this repo. This table is a placeholder for future additions." The procedure
 loads only when a matching file is edited, which is after the decisions it governs have been made.
+The framework synthesis adds an invocation contract: bounded work must expose its terminal artifact
+and status, handoffs must name continuation ownership and mutation rights, approval must bind to the
+exact pending request, and small protocols must state their escape hatch rather than imply that the
+repository owns runtime transport or authority.
 """

package/modules/workflows/rules/bounded-invocation.md

@@ -0,0 +1,21 @@
+---
+description: >-
+  How to put explicit iteration, cost, time, context, and retry bounds around an agentic invocation,
+  and how to name the terminal artifact and status for each bound. Loads when planning work that
+  invokes an agent, tool loop, evaluator, or other potentially open-ended procedure.
+paths:
+  - "{{plan_path}}/**/*.md"
+  - "{{path}}/**/*.md"
+enforcement: review-only
+---
+
+# Bound the invocation
+
+“Until done” is not a procedure. Before implementation, declare the limits that actually apply:
+iterations or turns, cost or token budget, wall time, context size, and retries. A bound that is
+only documented in a provider default is not a repository contract.
+
+For every limit, name the terminal artifact and status it produces: completed output, partial
+output with a resumable point, a refusal, or an explicit failure. Record what the caller can inspect
+after the bound fires and who owns the next continuation. Empty, truncated, and error results are
+part of the agent-facing interface, not exceptional prose to be invented at the end.

package/modules/workflows/rules/invocation-boundaries.md

@@ -0,0 +1,27 @@
+---
+description: >-
+  How to specify invocation ownership, state crossings, protocol escape hatches, approval identity,
+  and the allow-list of public outputs. Loads when a workflow calls another agent, pauses for a human,
+  delegates a capability, or exposes progress to a caller.
+paths:
+  - "{{plan_path}}/**/*.md"
+  - "{{path}}/**/*.md"
+enforcement: review-only
+---
+
+# Invocation boundaries
+
+Treat a composed invocation as a contract, not as a tool-shaped call:
+
+- **Ownership:** name who owns continuation, which state crosses the boundary, what the callee may
+  mutate, and whether its result returns to the caller.
+- **Protocol:** name the protocol, callback, adapter, or capability check that handles cases the
+  local abstraction does not own. A small interface without an escape hatch is a closed assumption.
+- **Approval:** persist a stable pending request id and the exact validated arguments; bind the
+  authorized decision server-side, expose an explicit approve/deny response path, and consume it
+  once. A caller-supplied boolean is not proof that the surfaced action was approved.
+- **Output:** declare an allow-list of caller-facing artifacts and statuses. Graph connectivity,
+  tool visibility, or event emission must not disclose internal progress by accident.
+
+These rules describe repository-facing workflow contracts. They do not provide an approval service,
+transport, event stream, sandbox, or authority model.

package/modules/workflows/skills/decompose/SKILL.md

@@ -5,7 +5,8 @@ description: >-
   extend upstream / hand-roll), pick the planning tier, and sequence by dependency. Use when handed
   something larger than a single change, when asked to "plan this", "how should we approach this",
   "break this down", "scope this out", or before starting work whose shape is not obvious. Also use
-  across a batch of related work to catch shared concerns once. Executing a tracked item is
+  across a batch of related work to catch shared concerns once. For agentic or delegated work, it
+  also names the bounds, continuation owner, state crossings, and terminal output/status. Executing a tracked item is
   /work-item; recording an out-of-scope observation is /record-finding.
 ---
 
@@ -60,12 +61,19 @@ out of time for.
 
 Following the repo's engineering guidance, not this skill.
 
+For an agentic invocation, implementation is not complete until the plan or work item records the
+iteration/cost/time/context/retry bounds, the continuation owner, the state and mutation boundary,
+and the terminal artifact/status for completion, truncation, empty output, and failure.
+
 ## 9. Close
 
 Reconcile: does the spec still describe what was built? Did any concern's branch change during
 execution, and is that recorded with its reason? A plan that silently stopped matching reality
 reads as verified.
 
+Name the public output allow-list and any protocol escape hatch in the close reconciliation. Internal
+events or connected tools are not public output unless the contract says they are.
+
 ## Two failure modes to watch for
 
 - **Resolving the story instead of the concerns.** One search, one answer, four concerns

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@rungs/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Installs and maintains a repository's agentic development system, composed from modules.",
   "author": "Antoine Dancre",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ThroughTheWind/rungs.git"
   },
-  "homepage": "https://github.com/ThroughTheWind/rungs#readme",
+  "homepage": "https://docs.rungscli.com",
   "bugs": {
     "url": "https://github.com/ThroughTheWind/rungs/issues"
   },
   "type": "module",
   "bin": {
-    "rungs": "./src/cli.ts"
+    "rungs": "dist/cli.js"
   },
   "publishConfig": {
     "access": "public"
@@ -22,12 +22,18 @@
     "node": ">=22.18"
   },
   "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
     "rungs": "node src/cli.ts",
-    "test": "node --test test/"
+    "test": "node --test test/*.test.js"
   },
   "files": [
+    "dist",
     "src",
-    "modules"
+    "modules",
+    "LICENSE",
+    "README.md"
   ],
   "keywords": [
     "agents",
@@ -38,5 +44,8 @@
   "license": "MIT",
   "dependencies": {
     "smol-toml": "^1.8.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.12"
   }
 }

package/src/add.ts

@@ -262,7 +262,14 @@ export function writeInstallRecord(
   wroteByModule?: Map<string, Set<string>>,
 ) {
   const lines = [
-    '# Installed by `rungs`. Edit parameters here and re-run `rungs render`.',
+    '# Installed by `rungs`. This is a record of what was written, not a control panel:',
+    '# editing a parameter here does not rewrite a file that already exists. `rungs render`',
+    '# re-emits path-scoped rules from `.ai/rules/`, and `rungs upgrade --apply` replaces',
+    '# module files you have not edited — neither re-substitutes parameters. AGENTS.md,',
+    '# CLAUDE.md, .gitignore, .gitattributes and .ai/gates.toml are shared between modules,',
+    '# so only their `rungs:begin`/`rungs:end` blocks are ever updated; anything outside a',
+    '# block, including the entry document\'s title, is yours to edit directly.',
+    '#',
     '# Hashes are what rungs emitted; a file whose hash no longer matches is a',
     '# divergence rungs reports and never overwrites.',
     '',

package/src/check.ts

@@ -141,7 +141,7 @@ let paramCache: { root: string; params: Params } | null = null;
 /** Parameters as the repo installed them, falling back to module defaults. */
 function installedParams(repoRoot: string): Params {
   if (paramCache?.root === repoRoot) return paramCache.params;
-  const defaults = resolveParams(loadAllModules(MODULES));
+  const defaults = resolveParams(loadAllModules(MODULES), {}, repoRoot);
   const recordPath = join(repoRoot, '.ai', 'rungs.toml');
   if (existsSync(recordPath)) {
     try {
@@ -168,6 +168,7 @@ const tableKey = (engine: string) =>
     'id-integrity': '__whole__',
     'render-freshness': 'render_freshness',
     'register-schema': 'register_schema',
+    'self-declared-closure': 'self_declared_closure',
     'filename-schema': 'filename_schema',
     'cross-reference': 'cross_reference',
     'git-status-reconcile': 'merged_status',