renma 0.18.0 → 0.18.2

package/docs/user-manual.md

@@ -73,17 +73,20 @@ support paths:
 
 The same reserved names apply under `.agents/skills/**`.
 
-These Skill-local support directories are valid. Keep material local when it is
-specific to one Skill. Promote reusable source-of-truth knowledge to an owned
-Context Asset, or a helper shared across workflows to `tools/**`, only when
-repository evidence supports that change; Renma does not move files
+These valid support paths are structurally Skill-local. Keep material local when
+it is specific to one Skill. Promote reusable source-of-truth knowledge to an
+owned Context Asset, or a helper shared across workflows to `tools/**`, only
+when repository evidence supports that change; Renma does not move files
 automatically.
 
-Skill-local support belongs only to the nearest Skill directory. When a local
-support artifact does not declare an owner, ownership, Readiness, graph, Trust
-Graph, and BOM reporting use the nearest Skill's owner as deterministic
-effective ownership and mark it as inherited. This does not invent ownership
-for shared Context Assets or unrelated repository files.
+Renma claims a parent only after repository evidence resolves exactly one Skill
+entrypoint. When that resolved local support artifact does not declare an owner,
+ownership, Readiness, graph, Trust Graph, and BOM reporting may use the parent
+Skill's owner as deterministic effective ownership and mark it as inherited.
+Missing or ambiguous parents never inherit. See
+[classification evidence](diagnostics.md#how-to-read-classification-evidence)
+for the detailed contract. This does not invent ownership for shared Context
+Assets or unrelated repository files.
 
 Only files marked Markdown-parser eligible contribute frontmatter metadata,
 headings, links, code fences, and repeated-context evidence. Text scripts and
@@ -162,6 +165,61 @@ Review the Skill with this platform's standard Skill authoring guidance, then us
 Start by running `renma --help` and use command-specific help to choose the appropriate workflow. Make only evidence-backed changes. Do not invent owners, references, product rules, or source-of-truth claims. Preserve existing semantics unless a diagnostic or explicit requirement supports a change. Run `renma scan . --fail-on high` after editing, fix relevant diagnostics, rerun it, and summarize both resolved and remaining findings.
 ```
 
+Recommended evidence-first preflight:
+
+1. Run `renma scan . --fail-on high --format json`.
+2. Run `renma inspect <SKILL.md> --format json`.
+3. Inspect relevant local resources and referenced Context Assets.
+4. Use `renma suggest-metadata` only when retrofit or migration evidence exists.
+5. Prepare the smallest intended patch.
+6. Rerun `renma scan . --fail-on high --format json`.
+7. Stop without manufacturing work when `suggest-metadata` reports
+   `decisionStatus: "no-change-recommended"`; this currently uses
+   `suggestedMode: "no-proposal"`.
+8. Report unresolved human decisions.
+
+For one classification question, `renma inspect <target> --format json` may be
+the initial preflight. Repository-wide work should normally start with `scan`.
+
+## Context Asset Discovery Boundary
+
+`contexts/**` is the preferred independent Context Asset root and `context/**`
+remains supported. Nested directory names never override a recognized root.
+Files under canonical Skill `references/`, `profiles/`, `examples/`, `scripts/`,
+and `assets/` directories are structurally Skill-local. Renma claims one parent
+and possible inherited governance only after repository evidence resolves
+exactly one Skill under `skills/**` or `.agents/skills/**`. Supported explicit
+local metadata remains valid but is not required. See
+[classification evidence](diagnostics.md#how-to-read-classification-evidence)
+for the detailed contract.
+
+Top-level `references/**` is not a Context root. `tools/**` contains shared
+repository implementation, not Context knowledge, and `skills/**/tools/**` is
+not a canonical local support directory. Skill-local executable support belongs
+under `scripts/`.
+
+```text
+contexts/foo/references/policy.md
+  -> independent Context Asset
+
+skills/foo/references/policy.md
+  -> Skill-local Reference
+
+references/policy.md
+  -> outside the Context root
+
+tools/helper.mjs
+  -> repository implementation
+
+skills/foo/tools/helper.mjs
+  -> not canonical Skill-local support
+```
+
+Placement as independent Context is a human decision about ownership,
+lifecycle, reuse, and source of truth. Classification after placement is
+deterministic. Renma never moves a file based on content. A successful
+`no-proposal` result means no edit should be manufactured.
+
 ## User Story: Create A New Skill With Scaffold
 
 Use this flow when adding a new agent-facing Skill. Platform-native guidance
@@ -640,7 +698,19 @@ renma inspect contexts/testing/boundary-value-analysis.md --format json
 renma inspect skills/testing/spec-review/SKILL.md --lines L10-L42
 ```
 
-Use this when editing one skill or context file and you want a deterministic outline without reading the whole repository catalog. Without `--lines`, output includes file size, line count, frontmatter range, headings, code fences, links, asset relationships, and a concise Context Lens governance summary when repository context can be inferred. Use `--lines <range>` for an exact source slice; ranges can look like `L10-L42` or `10-42`.
+Use this when editing one skill or context file and you want a deterministic outline without reading the whole repository catalog. Without `--lines`, output includes file size, line count, frontmatter range, headings, code fences, links, asset relationships, and a concise Context Lens governance summary when repository context can be inferred. It also always includes `classification` with `kind`, `scope`, `matchedRule`, `reasonCode`, root or parent evidence, and concise competing rules. A Skill-local path exposes `parentAssetCandidatePath`; `parentAssetPath` appears only when `parentResolution` is `resolved`, while `missing` and `ambiguous` remain explicit fail-closed states. `governance` is separate and reports ownership, policy, and metadata provenance only from repository evidence. Unknown files and repository tools still receive classification. Use `--lines <range>` for an exact source slice; ranges can look like `L10-L42` or `10-42`. `--lines` output itself is unchanged.
+
+JSON also includes `repositoryBoundary`. Resolved results record the root,
+repository-relative path, and resolution source. Unresolved results retain a
+stable reason code and `candidateRoots`; structural ambiguity uses
+`repository-boundary-ambiguous` instead of selecting a broad ancestor.
+
+For a file target, Renma resolves a repository root from an explicit caller root,
+the nearest safe `.git` file/directory or Renma config marker, or an unambiguous
+structural boundary, in that order. Current-working-directory containment alone
+does not establish a repository. This keeps nested repositories and absolute
+targets outside the current directory deterministic without scanning an
+unrelated parent tree.
 
 ### `readiness`
 
@@ -711,7 +781,9 @@ Renma does not infer owners automatically. If an asset is unowned, choose an own
 
 ### `scaffold`
 
-Creates a starter skill or context asset.
+Creates starter assets with distinct responsibilities: a Skill is a focused
+workflow entrypoint, Context is durable reusable knowledge, and a Context Lens
+is purpose-specific interpretation of one or more declared Context Assets.
 
 ```bash
 renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform
@@ -720,7 +792,17 @@ renma scaffold context_lens lenses/testing/spec-review-boundary-values.md --owne
 renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform --format prompt
 ```
 
-`scaffold --format file` writes a starter file, `--format prompt` emits an authoring prompt, and `--format json` emits structured scaffold data. The generated content is intentionally minimal; fill in metadata, dependencies, and verification steps before depending on it in automation.
+`scaffold --format file` writes a starter file, `--format prompt` emits an
+authoring prompt, and `--format json` emits structured scaffold data. The
+generated content is intentionally minimal; fill in metadata, dependencies, and
+verification steps before depending on it in automation.
+
+For a Context Lens, replace every placeholder `purpose`, `applies_to`, `focus`,
+and `expected_outputs` value with repository-grounded content. Every
+`applies_to` target must resolve to a real Context Asset. Do not use a Lens as
+generic persona storage, a prompt template, or a runtime routing rule, and do
+not create one when there is no Context Asset to interpret. See the
+[Context Lens guide](context-lens.md) for the canonical decision model.
 
 For a Skill, use platform-native authoring guidance before and after scaffolding.
 File mode prints concise Skill-only next steps after the `Created` line. Prompt
@@ -751,7 +833,17 @@ workflow, constraints, and completion criteria with platform-native guidance;
 apply only intended metadata or migration changes; run
 `renma scan . --fail-on high`; fix relevant diagnostics; and rerun the scan.
 Context Asset output does not receive this Skill-specific authoring guidance.
-JSON retains the existing structured suggestion shape.
+JSON adds `classification`, `decisionStatus`, structured `decision` evidence,
+and safe `nextActions` to the existing suggestion fields. Each action has
+`kind` and `invocation`; execute `invocation.command` with the exact
+`invocation.args` array. `invocation.display` is for people and must not be
+parsed as the machine contract, including on paths with spaces, quotes, or
+Windows separators.
+
+When no repository root resolves, `decisionStatus` is `blocked` and Renma does
+not emit an executable `scan .` action. Establish the repository root with an
+explicit root or repository marker before verification; the caller's current
+directory is not assumed to contain the target.
 
 For Skill targets using the pre-0.16 Renma Skill format, the 0.16.0 metadata
 migration path is one-way: recognized governance and security frontmatter
@@ -759,6 +851,8 @@ becomes Agent Skills identity plus `metadata.renma.*`. Separately, `skill.md` an
 report any required entrypoint rename or move, even when their frontmatter
 already uses Agent Skills fields. For a canonical Agent Skill, `--owner` may
 instead propose an owner metadata retrofit; it never causes reverse migration.
+Skill migration `sourcePath` and `targetPath` values are repository-relative,
+including when the user invokes Renma from the parent of a nested repository.
 The normative behavior is documented in
 [Agent Skills Compatibility and Migration](agent-skills-compatibility.md).
 
@@ -773,7 +867,35 @@ invalid evidence, confirm the Skill's intent with platform-native authoring
 guidance, correct the source evidence, rerun `suggest-metadata`, then validate
 intended corrections with `renma scan . --fail-on high`.
 
-Owner metadata remains recommended but not required. Without `--owner`, `suggest-metadata` blocks owner as a suggested addition and says not to add one unless the asset already declares an owner or a maintainer provides one. With `--owner <owner>`, the command may include that owner because it was explicitly provided. If an existing asset already declares an owner, `suggest-metadata` preserves it; a different `--owner` value is treated as a human-review ownership change, not an automatic metadata suggestion. Renma does not infer owners from Git history, file paths, prose, or authors.
+Owner metadata remains recommended but not required. Without `--owner`, Renma
+does not invent an owner. With `--owner <owner>`, the command may include that
+owner because it was explicitly provided. If an existing asset already
+declares an owner, `suggest-metadata` preserves it; a different `--owner` value
+is treated as conflicting evidence and blocks a candidate. Renma does not infer
+owners from Git history, file paths, prose, or authors.
+If the explicit owner equals the existing canonical `metadata.renma.owner`, the
+result is `suggestedMode: "no-proposal"` with
+`decisionStatus: "no-change-recommended"`; no candidate metadata, canonical
+frontmatter, or patch instruction is emitted.
+
+Ordinary Skill-local support returns `suggestedMode: "no-proposal"` and
+`decisionStatus: "no-change-recommended"` when it can inherit governance from
+one resolved parent Skill. Its `candidateMetadata` is empty. A missing or
+ambiguous parent returns `decisionStatus: "blocked"`, leaves governance
+unowned or unresolved, and provides a scan/layout action instead of claiming
+inheritance. Existing explicit local owner or policy metadata is preserved
+under `skill-local-existing-metadata-preserved`; an explicit `--owner` can still
+request a supported intentional override after the parent resolves. Prompt and
+JSON output both distinguish the observed path fact, deterministic
+interpretation, recommendation, and remaining human decision. Repository tools
+and unknown paths never receive fabricated Context metadata candidates.
+
+`decisionStatus` is authoritative: `blocked` never authorizes a patch,
+`no-change-recommended` stops without a patch, `human-confirmation-required`
+identifies what must be confirmed before applying only the candidate fields,
+and `deterministic` permits the reviewed candidate. Consumers should include a
+conservative default for unknown future `suggestedMode` values rather than
+assuming every non-`no-proposal` value is applicable.
 
 ### `suggest-semantic-split`
 

package/examples/context-lens/README.md

@@ -15,9 +15,11 @@ It includes:
   [`SKILL.md`](skills/testing/spec-review/SKILL.md) with static required and
   optional Lens relationships.
 
-The Skill is a thin routing and workflow layer. The Context Asset owns reusable
-boundary-value knowledge. Each Lens explains how to apply that knowledge for a
-particular purpose without copying it into the Skill.
+The Skill is a complete focused workflow entrypoint: it defines selection
+boundaries, inputs, ordered review steps, output, validation, and completion.
+The Context Asset owns reusable boundary-value knowledge. Each Lens explains
+how to interpret that knowledge for a particular purpose without copying it
+into the Skill.
 
 ```text
 Skill -> Context Lens -> Context Asset
@@ -71,6 +73,9 @@ Review the boundary-value Context for ambiguity and missing limits.
 ```
 
 The supported Lens schema version is `1`; the supported scope is `context`.
+Structural validity is only the starting point. A useful Lens also defines
+concrete questions, risks, checks, evidence, and expected outputs. Persona-only
+wording such as “Act as a senior QA engineer” is not sufficient by itself.
 
 ## Diagnostic Illustration
 

package/examples/context-lens/contexts/testing/boundary-value-analysis.md

@@ -18,6 +18,10 @@ requires_human_approval: false
 ---
 # Boundary Value Analysis
 
-Boundary value analysis is reusable testing knowledge. It should stay as a base context asset because it can support spec review, test design, regression planning, onboarding, and other skills.
+Boundary value analysis is reusable testing knowledge. It should stay as a base
+Context Asset because it can support spec review, test design, regression
+planning, onboarding, and other Skills.
 
-Keep task-specific interpretation in context lens assets instead of copying this content into each skill.
+When several workflows need reusable purpose-specific interpretation, keep that
+interpretation in Context Lenses instead of copying this knowledge into each
+Skill. A Skill may reference this Context directly when no Lens adds value.

package/examples/context-lens/lenses/testing/spec-review-boundary-values.md

@@ -11,8 +11,15 @@ tags:
 purpose: spec_review
 applies_to:
   - context.testing.boundary-value-analysis
-focus: ambiguity, missing boundary, source of truth, confirmation questions
-expected_outputs: unresolved questions, risk notes, spec clarification suggestions
+focus:
+  - ambiguity
+  - missing boundary
+  - source of truth
+  - confirmation questions
+expected_outputs:
+  - unresolved questions
+  - risk notes
+  - spec clarification suggestions
 allowed_data:
   - repo-local-files
 network_allowed: false
@@ -22,8 +29,23 @@ requires_human_approval: false
 ---
 # Spec Review Lens for Boundary Values
 
-Use this lens when reading boundary value analysis context during spec review.
+Interpret the applied boundary-value Context from the perspective of an
+experienced QA reviewer responsible for finding specification risk before
+implementation.
 
-Emphasize whether the spec defines exact lower and upper bounds, inclusive or exclusive behavior, empty or zero cases, overflow handling, retry limits, and ownership of the source of truth.
+## Interpretation Criteria
 
-The lens should help produce review questions and risk notes. It should not duplicate the base boundary value analysis context or become a prompt template.
+- Determine whether each material limit has an exact value and an identified
+  source of truth.
+- Check whether lower and upper bounds are inclusive or exclusive and whether
+  empty, zero, overflow, and retry-limit behavior is specified.
+- Identify conflicting requirements, undefined ownership, and assumptions that
+  could lead implementations or tests to disagree.
+- Distinguish documented facts from inferred behavior and unresolved decisions.
+
+## Evidence And Output
+
+Cite the specification section or repository source behind every conclusion.
+Produce prioritized unresolved questions, risk notes, and clarification
+suggestions. Do not duplicate the base Context, define the Skill workflow, or
+turn this Lens into a prompt template.

package/examples/context-lens/lenses/testing/test-design-boundary-values.md

@@ -11,8 +11,15 @@ tags:
 purpose: test_design
 applies_to:
   - context.testing.boundary-value-analysis
-focus: inclusive limits, empty and zero values, overflow behavior, retry limits
-expected_outputs: test cases, edge-case checklist, coverage notes
+focus:
+  - inclusive limits
+  - empty and zero values
+  - overflow behavior
+  - retry limits
+expected_outputs:
+  - test cases
+  - edge-case checklist
+  - coverage notes
 allowed_data:
   - repo-local-files
 network_allowed: false
@@ -22,8 +29,23 @@ requires_human_approval: false
 ---
 # Test Design Lens for Boundary Values
 
-Use this lens when turning boundary value analysis context into concrete test coverage.
+Interpret the applied boundary-value Context for test design that provides
+reviewable evidence of behavior at and around material limits.
 
-Emphasize lower and upper bounds, inclusive and exclusive behavior, empty input, zero values, overflow, maximum retries, and expected failure modes.
+## Interpretation Criteria
 
-The lens should help produce test cases and coverage notes. It should not select runtime context, assemble a prompt, or duplicate the base boundary value analysis context.
+- Map each declared limit to cases below, at, and above the boundary when those
+  states are valid for the system.
+- Distinguish inclusive from exclusive behavior and cover empty input, zero
+  values, overflow, maximum retries, and expected failure modes when applicable.
+- Trace each proposed case to a stated requirement and identify any expected
+  result that the specification leaves unresolved.
+- Prefer deterministic cases whose setup, assertion, and failure evidence can
+  distinguish product behavior from a test defect.
+
+## Evidence And Output
+
+Produce test cases, an edge-case checklist, and coverage notes with requirement
+citations. Keep unresolved expected results explicit. Do not select runtime
+Context, assemble a prompt, define the Skill workflow, or duplicate the base
+Context.

package/examples/context-lens/skills/testing/spec-review/SKILL.md

@@ -19,7 +19,15 @@ metadata:
 
 Use this skill to review a specification before implementation or test design.
 
-The skill stays thin. It declares the reusable base context and the purpose-oriented lens, while the detailed knowledge remains in context assets and lens assets.
+This Skill owns the focused review workflow. The declared Context Asset owns
+reusable boundary-value knowledge, and the declared Lenses own purpose-specific
+interpretation of that knowledge.
+
+## Selection Boundaries
+
+Use this workflow when a specification needs evidence-backed analysis of
+implementation or test-design boundaries. Do not use it to implement the
+change, approve product decisions, or perform unrelated editorial review.
 
 ## Required Inputs
 
@@ -28,9 +36,28 @@ The skill stays thin. It declares the reusable base context and the purpose-orie
 
 ## Instructions
 
-1. Read the declared context assets.
-2. Apply the declared context lens to focus the review.
-3. Produce unresolved questions, risk notes, and clarification suggestions.
+1. Confirm that the supplied specification and its sources are available. If a
+   required source is missing, record the gap rather than inventing behavior.
+2. Read the declared boundary-value Context Asset and the required spec-review
+   Lens. Apply the optional test-design Lens only when test coverage is also in
+   scope for the requested review.
+3. Extract stated behavior, limits, assumptions, and sources from the supplied
+   specification. Keep facts separate from inferences and unresolved questions.
+4. Apply the required Lens's interpretation criteria to the reusable Context.
+   Cite the reusable guidance where relevant instead of reproducing it in this
+   Skill or output.
+5. Prioritize findings by implementation or release risk. Cite the relevant
+   specification section or repository evidence for every finding.
+6. Produce the expected output below and leave decisions with the accountable
+   human owner.
+
+## Expected Output
+
+- A short scope and evidence summary.
+- Prioritized unresolved questions and risk notes.
+- Clarification suggestions tied to cited source gaps.
+- The Context and Lens IDs applied, including why the optional Lens was or was
+  not used.
 
 ## When Not To Use
 
@@ -41,6 +68,8 @@ approval, or an editorial workflow for copy-only review.
 
 - The output distinguishes known facts from open questions.
 - The output cites the source-of-truth gaps it found.
+- Each finding has an impact or risk and an evidence-backed rationale.
+- Use of the optional Lens matches the requested review scope.
 - The skill does not copy reusable testing guidance into this file.
 
 ## Completion Criteria

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renma",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Manage human-curated context assets for LLMs and agents in Git.",
   "license": "MIT",
   "repository": {