renma 0.16.0 → 0.17.0

package/docs/authoring-guide.md

@@ -0,0 +1,324 @@
+# Renma Authoring Guide
+
+This is the canonical guide for authoring and improving Skills and Context
+Assets in a Renma repository.
+
+## Responsibility Boundary
+
+Use your platform's standard Skill authoring guidance for general Skill design,
+then use Renma for repository-specific governance and validation.
+
+Platform-native authoring guidance owns:
+
+- name and trigger description;
+- usage and exclusion boundaries;
+- instructions and workflow;
+- constraints and safety behavior;
+- examples; and
+- completion criteria.
+
+Renma complements that guidance with:
+
+- canonical metadata and Agent Skills compatibility;
+- dependency and graph validation;
+- ownership and lifecycle governance;
+- security policy validation;
+- workflow clarity diagnostics; and
+- repository-wide scan and readiness evidence.
+
+Renma does not replace platform-native authoring guidance, generate domain
+intent, or automatically improve a Skill body. Human judgment remains required
+for semantics, ownership, policy, dependencies, and source-of-truth claims.
+
+## New Skill Workflow
+
+Use this sequence for a new Skill:
+
+```text
+platform-native Skill authoring guidance
+  -> renma scaffold skill
+  -> review and complete the generated Skill
+  -> renma scan . --fail-on high
+  -> fix relevant diagnostics
+  -> rerun validation
+  -> human review
+```
+
+### 1. Design the Skill
+
+Before generating a file, use the standard guidance for your platform to define:
+
+- the recurring task or decision;
+- the trigger and nearby cases that should not use the Skill;
+- required inputs and evidence;
+- the ordered workflow and decision points;
+- safety and repository constraints; and
+- the output and completion criteria.
+
+Do not guess missing owners, policies, dependencies, product behavior, domain
+rules, or source-of-truth documents. Record gaps for a human to resolve.
+
+### 2. Generate one repository-compatible starting point
+
+Run the Renma generator once:
+
+```bash
+renma scaffold skill skills/testing/spec-review/SKILL.md \
+  --id skill.testing.spec-review \
+  --title "Spec Review" \
+  --owner qa-platform \
+  --tags testing,spec-review
+```
+
+The target must be a canonical `SKILL.md` under `skills/**` or
+`.agents/skills/**`. File mode refuses to overwrite an existing file and
+requires an explicit owner. The output is a deterministic starting point, not
+a finished Skill.
+
+Do not run two independent generators against the same target file. Some
+platform-native authoring tools create files themselves, so choose one of these
+safe approaches:
+
+1. Run `renma scaffold skill`, then ask the platform tool to review and refine
+   that existing file.
+2. Ask the platform tool to use `renma scaffold skill` as the starting point
+   instead of independently generating the same target.
+
+`--format prompt` prints the deterministic scaffold and constraints without
+writing the file. `--format json` prints the existing structured bundle. These
+modes do not reserve or create the target path.
+
+### 3. Review and complete the scaffold
+
+Use platform-native guidance to complete:
+
+- `description`, including positive and negative trigger boundaries;
+- required inputs and preflight evidence;
+- instructions, decisions, and workflow;
+- constraints and security behavior;
+- completion criteria and validation; and
+- intended Renma metadata and Context relationships.
+
+Preserve the repository's intended behavior. Keep reusable domain, testing,
+product, platform, or tool knowledge in independently owned Context Assets when
+it should outlive one Skill.
+
+### 4. Validate, fix, and rerun
+
+Start with the release gate:
+
+```bash
+renma scan . --fail-on high
+```
+
+Review every relevant diagnostic, correct the underlying wording, metadata, or
+relationship, and rerun the same scan. Do not weaken security policy or add a
+suppression merely to make validation pass.
+
+Use other deterministic views when they answer a specific review question:
+
+```bash
+renma inspect skills/testing/spec-review/SKILL.md
+renma catalog . --format markdown
+renma graph . --focus skill.testing.spec-review --format mermaid
+renma ownership . --format markdown
+renma readiness . --format markdown
+```
+
+The final step is human review of the Skill's intent, workflow, policy,
+relationships, and remaining uncertainty.
+
+## Existing Skill Workflow
+
+Use this sequence for an existing Skill:
+
+```text
+review with platform-native Skill authoring guidance
+  -> renma scan . --fail-on high
+  -> inspect relevant diagnostics and repository evidence
+  -> use suggest-metadata only for metadata or migration work
+  -> prepare and review intended changes
+  -> renma scan . --fail-on high
+  -> fix relevant diagnostics
+  -> rerun validation
+  -> human review
+```
+
+### 1. Review the whole Skill
+
+Use platform-native authoring guidance to review the trigger description,
+instructions, workflow, constraints, examples, and completion criteria. This is
+semantic authoring review; `suggest-metadata` does not perform it.
+
+### 2. Scan and inspect repository evidence
+
+```bash
+renma scan . --fail-on high
+renma inspect skills/testing/spec-review/SKILL.md
+```
+
+`scan` is the general deterministic starting point for an existing Skill. Use
+`inspect`, `catalog`, `graph`, `ownership`, or `readiness` when one of those
+commands answers a specific evidence question. Renma reports structural and
+governance evidence; it does not perform the whole-Skill semantic review.
+
+### 3. Generate a metadata or migration suggestion when needed
+
+```bash
+renma suggest-metadata skills/testing/spec-review/SKILL.md
+```
+
+Optionally provide an owner only when a human has explicitly confirmed it:
+
+```bash
+renma suggest-metadata skills/testing/spec-review/SKILL.md \
+  --owner qa-platform \
+  --format json
+```
+
+`suggest-metadata` reads one target and prints a deterministic prompt or JSON
+payload to stdout. It does not edit, rename, or move the file. Its supported
+responsibilities are:
+
+- compact canonical metadata suggestions;
+- explicit owner retrofit and one-way migration of recognized pre-0.16
+  governance and security metadata;
+- pre-0.16 to canonical Agent Skills migration candidates;
+- conflict and unsafe-evidence detection; and
+- validation of the rendered candidate.
+
+It does not rewrite the body, infer ownership, choose between conflicting
+semantic values, infer missing security policy, or propose reverse migration
+for a canonical Skill. An owner candidate requires explicit human-provided
+evidence. Security policy remains intentionally authored and deterministically
+validated.
+
+Do not route an already canonical Skill through `suggest-metadata` as ceremony.
+Use it only for a metadata retrofit, explicit owner retrofit, recognized
+pre-0.16 one-way migration, or blocked migration review.
+
+### 4. Review before applying
+
+Treat the output as a candidate. Compare it with the source and apply only the
+intended metadata, path migration, or migration changes. Preserve the Markdown
+body and unknown vendor metadata unless a separately reviewed semantic change
+requires otherwise.
+
+If migration is blocked:
+
+1. Review the reported conflicts or invalid evidence.
+2. Confirm the Skill's intent using platform-native authoring guidance.
+3. Do not apply a candidate while Renma cannot generate it safely.
+4. Correct the source evidence.
+5. Rerun `renma suggest-metadata <SKILL.md>`.
+6. After intended corrections, run `renma scan . --fail-on high` and repeat the
+   fix-and-rerun loop.
+
+Renma never chooses a semantic winner automatically. The detailed one-way
+migration and blocking contract is in
+[Agent Skills Compatibility and Migration](agent-skills-compatibility.md).
+
+## Canonical Skill Metadata
+
+Agent Skills owns the standard Skill identity and body. Renma fields are flat,
+string-valued `metadata.renma.*` entries. JSON-array strings encode lists:
+
+```yaml
+---
+name: spec-review
+description: Review specifications for ambiguity and missing boundaries. Use when requirements need evidence-backed review before implementation.
+metadata:
+  renma.id: skill.testing.spec-review
+  renma.title: Spec Review
+  renma.owner: qa-platform
+  renma.status: stable
+  renma.tags: '["testing","spec-review"]'
+  renma.requires-context: '["context.testing.boundary-value-analysis"]'
+  renma.optional-context: '[]'
+---
+```
+
+Do not use a nested `metadata.renma` mapping, native YAML booleans for canonical
+security fields, or comma-separated canonical lists. See the compatibility and
+security guides for the complete contracts.
+
+## Context Asset And Context Lens Authoring
+
+Create a Context Asset when knowledge should be reusable and independently
+owned:
+
+```bash
+renma scaffold context contexts/testing/boundary-value-analysis.md \
+  --owner qa-platform
+```
+
+A Context Asset should contain durable, source-backed domain knowledge,
+testing heuristics, tool constraints, platform facts, or reviewed policy. Keep
+task-specific prompt instructions and runtime selection rules out of shared
+Context.
+
+Create a Context Lens when one purpose needs a focused interpretation of one or
+more Context Assets:
+
+```bash
+renma scaffold context_lens \
+  lenses/testing/spec-review-boundary-values.md \
+  --owner qa-platform
+```
+
+The repository can represent both:
+
+```text
+Skill -> Context Lens -> Context Asset
+Skill -> Context Asset
+```
+
+These metadata relationships are static governance evidence. Renma does not
+select, load, or inject Context at runtime.
+
+Context and Context Lens scaffolds keep their top-level Renma metadata syntax;
+the Agent Skills `metadata.renma.*` serialization boundary applies to Skills.
+
+For current guidance on deriving several thin, bounded Skills from a broad
+existing Skill—including focused `inspect`, graph, Context reuse, and Appium
+examples—see [Advanced Skill Authoring](advanced-skill-authoring.md). That guide
+keeps current thin-Skill authoring separate from proposed 0.18.0 Skill-to-Skill
+discovery.
+
+## Optional Codex Example
+
+Codex `skill-creator` is one example of platform-native authoring guidance; it
+is not a Renma dependency and is not named in generic CLI output.
+
+After creating the Renma scaffold, a safe request is:
+
+```text
+Use skill-creator to review and refine the existing
+skills/testing/spec-review/SKILL.md scaffold. Preserve its intended Renma
+metadata and repository behavior. Do not independently generate a second target
+file. Do not invent owners, policy, dependencies, domain rules, or
+source-of-truth claims. After the reviewed edits, run
+`renma scan . --fail-on high`, fix relevant diagnostics, and rerun the scan.
+```
+
+Alternatively, ask `skill-creator` to use `renma scaffold skill` as its
+starting point. In both cases, only one generator creates the target file.
+
+## Review Checklist
+
+Before human approval, confirm that:
+
+- the description says when the Skill should and should not be selected;
+- instructions, constraints, and completion criteria are explicit;
+- owners, policies, dependencies, and domain claims are evidence-backed;
+- reusable knowledge has an appropriate Context boundary;
+- generated or suggested changes were reviewed rather than applied blindly;
+- blocked migration evidence was resolved instead of bypassed;
+- `renma scan . --fail-on high` was rerun after fixes; and
+- no policy weakening or new suppression was used merely to pass validation.
+
+The operating principle remains:
+
+```text
+LLM proposes. Renma verifies. Human approves.
+```

package/docs/context-conflict-diagnostics.md

@@ -0,0 +1,32 @@
+# Context Conflict Graph Diagnostics
+
+Renma checks declared `conflicts` metadata so incompatible context assets do not become required together without review.
+
+These diagnostics are deterministic catalog diagnostics. They do not choose runtime context, infer conflict intent, create scan finding IDs, or rewrite metadata.
+
+## Invalid conflicts metadata
+
+Renma warns when an asset's `conflicts` metadata points at itself or points at an asset that does not exist in the catalog.
+
+Example messages:
+
+```text
+Asset conflicts metadata references itself: "context.testing.boundary-analysis".
+Asset conflicts target "context.testing.missing" does not match a catalog entry.
+```
+
+Fix self references by removing the conflict entry. Fix missing targets by correcting the asset ID, adding the missing asset, or removing stale metadata.
+
+## Conflicting required context
+
+Renma warns when a skill requires two context assets that are declared as conflicting:
+
+```text
+Skill requires conflicting context assets "context.testing.boundary-analysis" and "context.testing.fuzz-testing".
+```
+
+A skill should not require conflicting context assets as always-loaded base knowledge. Split the skill, move one context to `optional_context`, remove stale `conflicts` metadata, or document a safer static relationship.
+
+## Relationship to context lens
+
+These checks are useful before adding purpose-oriented lens assets. A lens should not have to compensate for skills that require mutually conflicting base context.

package/docs/context-language-diagnostics.md

@@ -0,0 +1,99 @@
+# Context Language Diagnostics
+
+Renma checks canonical active shared context assets for small English-only wording patterns that can make reusable context harder for humans and agents to apply safely.
+
+These diagnostics are deterministic catalog diagnostics. They do not call an LLM, infer a replacement threshold, infer a date or version, create scan finding IDs, or rewrite context content.
+
+## Scope
+
+The checks apply only to shared context assets that are active and canonical:
+
+- the artifact kind is `context`
+- the asset has an `id` that starts with `context.`
+- the asset has an `owner`
+- the asset status is not `deprecated` or `archived`
+
+## Vague wording
+
+Renma warns when a shared context body contains broad English wording such as:
+
+- `usually`
+- `often`
+- `quickly`
+- `soon`
+- `as needed`
+- `where appropriate`
+- `major`
+
+These terms are not always wrong, but they often require a concrete condition, threshold, required evidence, or uncertainty-handling rule before the context is safe to reuse broadly.
+
+Example warning message:
+
+```text
+Shared context asset contains vague wording "often".
+```
+
+Prefer replacing vague wording with concrete boundaries, or keep the uncertainty explicit:
+
+```md
+WDA may be involved only when session startup logs show WDA build, launch, or connection errors.
+```
+
+Do not invent thresholds or domain facts just to satisfy the diagnostic. Ask the context owner when the boundary is unknown.
+
+## Currentness wording
+
+Renma warns when a shared context body contains relative English currentness wording without an explicit date or version on the same line, such as:
+
+- `recently`
+- `latest`
+- `currently`
+- `as of now`
+
+Example warning message:
+
+```text
+Shared context asset contains currentness wording "recently" without an explicit date or version.
+```
+
+Prefer a stable date, version, or review boundary:
+
+```md
+As of 2026-07-01, Appium driver installation guidance uses this path.
+```
+
+Versioned wording is also acceptable when it makes the claim stable:
+
+```md
+The latest Appium 2.8 behavior is covered here.
+```
+
+## Prompt or runtime-selection wording
+
+Renma warns when a shared context body looks like a prompt artifact or runtime context-selection rule instead of reusable base knowledge. Examples include:
+
+- role-prompt wording such as `You are an ... assistant`
+- runtime selection wording such as `always load this context`
+- priority wording such as `use this context first`
+- direct runtime wording such as `select this context at runtime`
+- prompt-artifact wording such as `system prompt`
+
+Example warning message:
+
+```text
+Shared context asset contains prompt or runtime-selection wording "role prompt".
+```
+
+Prefer keeping the context as reusable knowledge:
+
+```md
+This context describes Appium setup terminology and constraints for maintainers.
+```
+
+Put prompt assembly, runtime context selection, and assistant role instructions outside shared context assets. Renma does not choose runtime context, assemble prompts, inject context into agents, or execute agent workflows.
+
+## Relationship to metadata diagnostics
+
+These body-language diagnostics complement usage-boundary metadata diagnostics such as missing `when_to_use`, missing `when_not_to_use`, and placeholder usage-boundary metadata.
+
+Keep `when_to_use` and `when_not_to_use` compact. Put detailed explanations, examples, and caveats in the Markdown body or referenced context assets.

package/docs/context-lens.md

@@ -0,0 +1,253 @@
+# Context Lens Assets
+
+`context_lens` is a Renma asset type for purpose-oriented interpretation over reusable context assets.
+
+It keeps the Renma core boundary intact:
+
+```text
+LLM proposes. Renma verifies. Human approves.
+```
+
+Renma catalogs and validates repository assets. Agents and tools decide what to do at runtime.
+
+Renma does not select lenses for a task, rank lenses, assemble prompts, inject context, or run an LLM to judge lens quality.
+
+## Model
+
+```text
+references -> contexts -> context_lenses -> skills
+```
+
+The design principle is:
+
+```text
+Knowledge should be reusable.
+Interpretation should be purpose-oriented.
+Execution should be skill-specific.
+```
+
+Use this split when the same base context should be read differently for different purposes.
+
+For example, a payment retry context can support:
+
+- a spec review lens that focuses on ambiguity and source-of-truth gaps
+- a test design lens that focuses on boundary values and expected results
+- a failure analysis lens that focuses on observed symptoms and logs
+
+The base context remains reusable. The lens explains how that context should be interpreted for a purpose.
+
+See [`examples/context-lens`](../examples/context-lens) for a runnable fixture with two valid lenses, readiness output, inspect output, and an invalid diagnostic example.
+
+## Minimal Valid Lens
+
+A minimal valid lens declares a stable ID, owner, purpose, and at least one `applies_to` target.
+
+```yaml
+---
+id: lens.testing.spec-review.boundary-values
+type: context_lens
+owner: qa-platform
+status: experimental
+purpose: spec_review
+applies_to:
+  - context.testing.boundary-value-analysis
+---
+# Spec Review Lens for Boundary Values
+
+Review the boundary value analysis context for ambiguity, missing limits, and unclear sources of truth.
+```
+
+`type: context_lens` is optional for files under `lenses/**`, but it is recommended because it makes the file's intent obvious in code review. It is required when a lens is stored under `context/**` or `contexts/**`.
+
+## Multiple Lenses
+
+Multiple lenses can interpret the same base context for different review purposes:
+
+```yaml
+---
+id: lens.testing.spec-review.boundary-values
+type: context_lens
+owner: qa-platform
+status: experimental
+purpose: spec_review
+applies_to:
+  - context.testing.boundary-value-analysis
+focus:
+  - ambiguity
+  - missing boundary
+expected_outputs:
+  - unresolved questions
+  - risk notes
+---
+```
+
+```yaml
+---
+id: lens.testing.test-design.boundary-values
+type: context_lens
+owner: qa-platform
+status: experimental
+purpose: test_design
+applies_to:
+  - context.testing.boundary-value-analysis
+focus:
+  - inclusive limits
+  - zero and empty values
+  - overflow behavior
+expected_outputs:
+  - test cases
+  - edge-case checklist
+---
+```
+
+A skill declares static lens relationships with `requires_lens` or `optional_lens`:
+
+```yaml
+---
+id: skill.testing.spec-review
+owner: qa-platform
+status: experimental
+requires_context:
+  - context.testing.boundary-value-analysis
+requires_lens:
+  - lens.testing.spec-review.boundary-values
+---
+```
+
+These fields create catalog and graph relationships. They do not make Renma choose runtime context or inject the lens into an agent.
+
+## Supported Fields
+
+Prefer compact, flat metadata. Detailed interpretation guidance belongs in the Markdown body, not in frontmatter.
+
+- `id`: required stable lens ID. Prefer the `lens.<domain>.<purpose>` prefix style.
+- `type`: recommended `context_lens` discriminator.
+- `owner`: required accountable owner.
+- `status`: optional lifecycle status: `experimental`, `stable`, `deprecated`, or `archived`.
+- `version`: optional lens schema version. The supported schema version is `1`.
+- `scope`: optional lens scope. The supported scope is `context`.
+- `purpose`: required short purpose label such as `spec_review`, `test_design`, or `failure_analysis`.
+- `applies_to`: required context asset IDs or repository-relative paths this lens interprets.
+- `focus`: optional compact review focus terms.
+- `expected_outputs`: optional compact output expectations.
+
+Deprecated field aliases such as `target`, `targets`, `output`, and `outputs` produce warnings. Use `applies_to` and `expected_outputs`.
+
+## Diagnostics
+
+Context Lens governance diagnostics use stable string codes in JSON output. The detailed diagnostics appear in `scan` and `readiness`; concise summaries appear in `readiness` and `inspect`.
+
+Invalid example:
+
+```yaml
+---
+id: lens.testing.spec-review.boundary-values
+owner: qa-platform
+applies_to:
+  - ./contexts/testing/missing.md
+---
+# Spec Review Lens
+```
+
+Expected diagnostics include:
+
+- `CONTEXT-LENS-MISSING-REQUIRED-FIELD` because `purpose` is missing.
+- `CONTEXT-LENS-PATH-NORMALIZATION-MISMATCH` because `./contexts/testing/missing.md` normalizes to `contexts/testing/missing.md`.
+- `CONTEXT-LENS-TARGET-NOT-FOUND` because the target path does not resolve to a cataloged asset.
+
+Blocking Context Lens diagnostics are `error` diagnostics. Warnings are reported by default but do not fail readiness unless another policy makes the repository not ready.
+
+## Readiness And Inspect
+
+`renma readiness --json` includes an additive `summary.contextLens` object:
+
+```json
+{
+  "summary": {
+    "contextLens": {
+      "enabled": true,
+      "detected": true,
+      "totalLensCount": 2,
+      "validLensCount": 2,
+      "invalidLensCount": 0,
+      "diagnosticCounts": {
+        "error": 0,
+        "warning": 0,
+        "info": 0
+      }
+    }
+  }
+}
+```
+
+Markdown readiness includes a `Context Lens` section with lens counts, diagnostic counts, a representative diagnostic code, definition paths, and target references.
+
+`renma inspect <file> --format text` includes a concise Context Lens summary:
+
+```text
+Context Lens:
+- Enabled: yes
+- Detected: yes
+- Lenses: 2/2 valid (0 invalid)
+- Diagnostics: error 0, warning 0, info 0
+- Representative diagnostic: (none)
+- Definition paths: lenses/testing/spec-review-boundary-values.md, lenses/testing/test-design-boundary-values.md
+- Target references: context.testing.boundary-value-analysis
+```
+
+`renma inspect <file> --format json` includes the same additive `contextLens` summary object.
+
+## CI Usage
+
+Use readiness in CI when Context Lens governance should block merges:
+
+```bash
+renma readiness . --json
+```
+
+The command exits `1` when readiness is not ready, including when blocking Context Lens diagnostics are present.
+
+For pull-request review artifacts, `renma ci-report` continues to report deterministic catalog, graph, readiness, finding, and security deltas. It does not call an LLM or make subjective lens-quality judgments.
+
+## Authoring Helpers
+
+Use `scaffold` to create a compact starter lens:
+
+```bash
+renma scaffold context_lens lenses/testing/spec-review-boundary-values.md \
+  --id lens.testing.spec-review.boundary-values \
+  --title "Spec Review Boundary Values Lens" \
+  --owner qa-platform \
+  --tags testing,spec-review
+```
+
+Use `inspect` on a lens to review its purpose metadata and declared graph neighborhood. Lens inspection shows inbound skill references, outbound `applies_to` context targets, and the static `skill -> lens -> context` chain.
+
+## Good Lens Boundaries
+
+A lens should answer:
+
+- What purpose is this context being read for?
+- Which context assets does it apply to?
+- What questions, risks, checks, or evidence should be emphasized?
+- What output shape should the agent or human reviewer produce?
+
+A lens should not become:
+
+- a copy of the base context
+- a long prompt template
+- a runtime routing rule
+- a QA-specific rule hardcoded into Renma core
+- a replacement for the skill entrypoint
+
+## Non-Goals For 0.12.0
+
+Renma 0.12.0 intentionally does not implement:
+
+- runtime selection
+- prompt assembly
+- context injection
+- automatic LLM judgment or subjective scoring
+- external signal imports from Codex, Claude, IDEs, or similar tools
+
+The release stabilizes deterministic Context Lens governance: summary output, diagnostics, readiness integration, inspect integration, docs, and examples.