renma 0.15.2 → 0.17.0

package/examples/context-lens/README.md

@@ -0,0 +1,101 @@
+# Context Lens Example
+
+This current example demonstrates how Context Lenses give different workflows
+purpose-specific interpretations of the same governed Context Asset.
+
+It includes:
+
+- one reusable Context Asset:
+  [`contexts/testing/boundary-value-analysis.md`](contexts/testing/boundary-value-analysis.md);
+- two valid Lenses over that Context:
+  [`spec-review-boundary-values.md`](lenses/testing/spec-review-boundary-values.md)
+  and
+  [`test-design-boundary-values.md`](lenses/testing/test-design-boundary-values.md);
+- one canonical nested Agent Skills-compatible
+  [`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.
+
+```text
+Skill -> Context Lens -> Context Asset
+```
+
+These are static repository relationships. Renma validates their definitions,
+metadata, resolution, and repository health. The consuming agent reads and
+applies the declared Context and Lens; Renma does not choose a runtime Lens,
+assemble prompts, inject Context, execute the workflow, or judge Lens quality
+with an LLM. A human reviews the result.
+
+```text
+LLM proposes. Renma verifies. Human approves.
+```
+
+## Inspect The Example
+
+From the Renma repository root after building the CLI:
+
+```bash
+node dist/index.js scan examples/context-lens --fail-on high
+node dist/index.js catalog examples/context-lens --format markdown
+node dist/index.js readiness examples/context-lens --format markdown
+node dist/index.js inspect examples/context-lens/lenses/testing/spec-review-boundary-values.md --format text
+node dist/index.js graph examples/context-lens --view layered --format mermaid
+```
+
+The expected result is one valid nested Skill, two valid Context Lenses, one
+governed Context Asset, resolved Skill-to-Lens-to-Context relationships, zero
+scan findings, and readiness level `ready` with score 100. Readiness includes a
+`Context Lens` summary; JSON output exposes the same evidence under
+`summary.contextLens`.
+
+## Minimal Valid Lens
+
+```yaml
+---
+id: lens.testing.spec-review.boundary-values
+type: context_lens
+owner: qa-platform
+status: experimental
+version: 1
+scope: context
+purpose: spec_review
+applies_to:
+  - context.testing.boundary-value-analysis
+---
+# Spec Review Lens for Boundary Values
+
+Review the boundary-value Context for ambiguity and missing limits.
+```
+
+The supported Lens schema version is `1`; the supported scope is `context`.
+
+## Diagnostic Illustration
+
+The following illustration is intentionally not stored as a scanned fixture:
+
+```yaml
+---
+id: lens.testing.invalid
+owner: qa-platform
+applies_to:
+  - ./contexts/testing/missing.md
+---
+# Invalid Lens
+```
+
+It would produce:
+
+- `CONTEXT-LENS-MISSING-REQUIRED-FIELD` for the missing `purpose`;
+- `CONTEXT-LENS-PATH-NORMALIZATION-MISMATCH` for the `./` path prefix; and
+- `CONTEXT-LENS-TARGET-NOT-FOUND` because the target does not resolve.
+
+Use readiness as the blocking CI view for Context Lens governance:
+
+```bash
+renma readiness examples/context-lens --json
+```
+
+Blocking Context Lens diagnostics make that command exit `1`.

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

@@ -0,0 +1,23 @@
+---
+id: context.testing.boundary-value-analysis
+owner: qa-platform
+status: stable
+tags:
+  - testing
+  - qa
+when_to_use:
+  - Designing or reviewing behavior around numeric, date, quantity, retry, or limit boundaries
+when_not_to_use:
+  - Reviewing copy, styling, or exploratory observations that do not depend on explicit boundaries
+allowed_data:
+  - repo-local-files
+network_allowed: false
+external_upload_allowed: false
+secrets_allowed: false
+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.
+
+Keep task-specific interpretation in context lens assets instead of copying this content into each skill.

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

@@ -0,0 +1,29 @@
+---
+id: lens.testing.spec-review.boundary-values
+type: context_lens
+owner: qa-platform
+status: experimental
+version: 1
+scope: context
+tags:
+  - testing
+  - spec-review
+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
+allowed_data:
+  - repo-local-files
+network_allowed: false
+external_upload_allowed: false
+secrets_allowed: false
+requires_human_approval: false
+---
+# Spec Review Lens for Boundary Values
+
+Use this lens when reading boundary value analysis context during spec review.
+
+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.
+
+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.

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

@@ -0,0 +1,29 @@
+---
+id: lens.testing.test-design.boundary-values
+type: context_lens
+owner: qa-platform
+status: experimental
+version: 1
+scope: context
+tags:
+  - testing
+  - test-design
+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
+allowed_data:
+  - repo-local-files
+network_allowed: false
+external_upload_allowed: false
+secrets_allowed: false
+requires_human_approval: false
+---
+# Test Design Lens for Boundary Values
+
+Use this lens when turning boundary value analysis context into concrete test coverage.
+
+Emphasize lower and upper bounds, inclusive and exclusive behavior, empty input, zero values, overflow, maximum retries, and expected failure modes.
+
+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.

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

@@ -0,0 +1,49 @@
+---
+name: spec-review
+description: Review a specification through declared Context Assets and Context Lenses. Use when implementation or test-design boundaries need focused analysis; do not use for implementation, final approval, or unrelated editorial review.
+metadata:
+  renma.id: skill.testing.spec-review
+  renma.owner: qa-platform
+  renma.status: experimental
+  renma.tags: '["testing","spec-review"]'
+  renma.requires-context: '["context.testing.boundary-value-analysis"]'
+  renma.requires-lens: '["lens.testing.spec-review.boundary-values"]'
+  renma.optional-lens: '["lens.testing.test-design.boundary-values"]'
+  renma.allowed-data: '["repo-local-files"]'
+  renma.network-allowed: "false"
+  renma.external-upload-allowed: "false"
+  renma.secrets-allowed: "false"
+  renma.requires-human-approval: "false"
+---
+# Spec Review
+
+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.
+
+## Required Inputs
+
+- The specification or product change to review.
+- Any linked source-of-truth documents or implementation references.
+
+## 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.
+
+## When Not To Use
+
+Use an implementation workflow for code changes, a decision owner for final
+approval, or an editorial workflow for copy-only review.
+
+## Validation
+
+- The output distinguishes known facts from open questions.
+- The output cites the source-of-truth gaps it found.
+- The skill does not copy reusable testing guidance into this file.
+
+## Completion Criteria
+
+Complete when the output separates facts from unresolved questions, cites each
+source-of-truth gap, records the applied Lens, and is ready for human review.

package/examples/context-repo/README.md

@@ -0,0 +1,149 @@
+---
+id: example.context-repo.overview
+title: Example Context Repository
+version: 0.1.0
+owner: qa-platform
+status: stable
+tags:
+  - example
+  - testing
+---
+
+# Example Context Repository
+
+This fixture is a focused workflow-authoring and repository-governance example.
+It is statically navigable for a consuming agent that has this repository
+checkout and can follow the relative Markdown links in the Skill. The agent can
+inspect an incomplete request, ask focused clarification questions, apply
+reusable Context, record evidence and assumptions, and produce findings for
+human review. Renma discovers and validates the repository assets; it does not
+open the links or execute the interaction.
+
+## Repository Assets
+
+- [`skills/testing/spec-review/SKILL.md`](skills/testing/spec-review/SKILL.md)
+  is the Agent Skills-compatible entrypoint and interactive usage guide.
+- [`lenses/testing/spec-review-boundary-values.md`](lenses/testing/spec-review-boundary-values.md)
+  interprets reusable boundary knowledge for specification review.
+- [`contexts/testing/boundary-value-analysis.md`](contexts/testing/boundary-value-analysis.md)
+  is the independently owned source of truth used through the Lens.
+- [`contexts/testing/negative-testing.md`](contexts/testing/negative-testing.md)
+  is used directly by the Skill; a Context Lens is not required for every
+  Context Asset.
+- [`contexts/domain/payment/idempotency.md`](contexts/domain/payment/idempotency.md)
+  is optional and applies only when a review covers retryable payment writes.
+
+The `metadata.renma.*` dependency values are governance relationships. Generic
+Agent Skills clients are not required to resolve them, so the Skill and Lens
+bodies provide a repository-relative path to every required asset. The Skill
+links the Lens and direct Context Asset, the Lens links Boundary Value Analysis,
+and the Skill links this asset index for its optional payment branch. Agent
+Skills-compatible syntax alone does not make those external assets portable,
+and copying the Skill without the rest of this fixture produces an incomplete
+workflow.
+
+The declared relationships demonstrate both supported shapes:
+
+```text
+Skill -> Context Lens -> Context Asset
+Skill -> Context Asset
+```
+
+These are static repository relationships. They do not make Renma select or
+load Context for a live request.
+
+## Responsibility Boundary
+
+Renma:
+
+- discovers and normalizes the example assets;
+- validates metadata and declared relationships;
+- reports deterministic diagnostics; and
+- exposes Catalog, graph, Trust Graph, Readiness, and Repository Context BOM
+  views.
+
+The consuming agent:
+
+- interprets the user's request and follows the Skill guidance;
+- asks focused clarification questions without inventing missing requirements;
+- opens the explicit repository-relative links in the Skill and Lens;
+- applies the Lens and direct Context relationships where relevant; and
+- records evidence, assumptions, unresolved questions, rationale, and findings.
+
+The human:
+
+- supplies missing domain knowledge and decision ownership;
+- reviews clarifications, assumptions, findings, and any resulting patch; and
+- accepts, rejects, or corrects the final result.
+
+Human review occurs before the findings become accepted requirements or before
+any implementation change is merged.
+
+## Inspect With Renma
+
+Run these commands from the renma repository root after building the CLI:
+
+```bash
+npm run build
+node dist/index.js scan examples/context-repo
+node dist/index.js catalog examples/context-repo --format markdown
+node dist/index.js ownership examples/context-repo --format markdown
+node dist/index.js graph examples/context-repo --view layered --format mermaid
+node dist/index.js trust-graph examples/context-repo --format markdown
+node dist/index.js readiness examples/context-repo --format markdown
+node dist/index.js bom examples/context-repo --format json --omit-generated-at
+node dist/index.js bom examples/context-repo --format markdown
+node dist/index.js inspect examples/context-repo/skills/testing/spec-review/SKILL.md
+```
+
+With an installed CLI, replace `node dist/index.js` with `renma`:
+
+```bash
+renma scan examples/context-repo
+renma catalog examples/context-repo --format markdown
+renma ownership examples/context-repo --format markdown
+renma graph examples/context-repo --view layered --format mermaid
+renma trust-graph examples/context-repo --format markdown
+renma readiness examples/context-repo --format markdown
+renma bom examples/context-repo --format json --omit-generated-at
+renma bom examples/context-repo --format markdown
+renma inspect examples/context-repo/skills/testing/spec-review/SKILL.md
+```
+
+`scan` checks the assets for findings. Catalog and ownership show inventory and
+responsibility. The layered graph makes Skill-to-Lens-to-Context and direct
+Skill-to-Context relationships visible. Trust Graph connects review evidence.
+Readiness summarizes repository health. BOM combines declared repository
+evidence into authoritative JSON or a Markdown review projection. `inspect`
+shows the structure of the workflow entrypoint.
+
+The example is structurally ready: its Skill and Lens validate, every declared
+relationship resolves, and every cataloged asset has an owner. `scan` also
+keeps advisory missing-security-policy findings visible for the fixture's
+Skill and Context Assets. The example does not invent security policy merely to
+produce an empty finding list; fixture owners would need to review and declare
+that policy.
+
+## Intentionally Not Demonstrated
+
+This fixture does not add or imply a Renma runtime state machine, automatic
+question generation, live Skill or Context selection, prompt assembly, agent
+execution, automatic file rewriting, telemetry collection, or automatic human
+approval. The interactive behavior belongs to the consuming agent and the
+final judgment belongs to the human. Renma metadata does not make the workflow
+self-contained or cause a generic Agent Skills client to load external assets.
+
+The declared relationship shape is:
+
+```mermaid
+flowchart TD
+  node_0["skill: skill.testing.spec-review"]
+  node_1["lens: lens.testing.spec-review.boundary-values"]
+  node_2["context: context.domain.payment.idempotency"]
+  node_3["context: context.testing.negative-testing"]
+  node_4["context: context.testing.boundary-value-analysis"]
+  node_0 -->|requires_lens| node_1
+  node_0 -->|optional| node_2
+  node_0 -->|requires| node_3
+  node_1 -->|applies_to| node_4
+```

package/examples/context-repo/contexts/domain/payment/idempotency.md

@@ -0,0 +1,20 @@
+---
+id: context.domain.payment.idempotency
+title: Payment Idempotency
+version: 0.1.0
+owner: payments-platform
+status: stable
+tags:
+  - payment
+  - reliability
+when_to_use:
+  - Reviewing payment write retry behavior or duplicate request handling
+when_not_to_use:
+  - Reviewing non-payment retries or read-only request behavior
+---
+
+# Payment Idempotency
+
+Payment writes should be safe to retry. A request with the same idempotency key should produce one durable outcome, even if the client times out and sends the request again.
+
+Review payment specs for key scope, duplicate handling, timeout behavior, and whether the response explains the original result.

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

@@ -0,0 +1,19 @@
+---
+id: context.testing.boundary-value-analysis
+title: Boundary Value Analysis
+version: 0.1.0
+owner: qa-platform
+status: stable
+tags:
+  - testing
+when_to_use:
+  - Designing test cases around numeric, date, count, length, or pagination limits
+when_not_to_use:
+  - Testing invalid inputs that are not tied to explicit boundary values
+---
+
+# Boundary Value Analysis
+
+Boundary value analysis checks the values just below, at, and just above important limits. Use it for limits such as quantity, length, date range, retry count, price, and pagination size.
+
+Prefer examples that name the limit and the expected behavior. A good case says what happens at the minimum, the maximum, and the first invalid value outside each edge.

package/examples/context-repo/contexts/testing/negative-testing.md

@@ -0,0 +1,19 @@
+---
+id: context.testing.negative-testing
+title: Negative Testing
+version: 0.1.0
+owner: qa-platform
+status: stable
+tags:
+  - testing
+when_to_use:
+  - Designing validation, unsupported-state, or error-handling test cases
+when_not_to_use:
+  - Designing accepted boundary-value cases for valid limits
+---
+
+# Negative Testing
+
+Negative testing verifies that invalid inputs and unsupported states fail clearly. It should confirm the user sees a useful error, the system avoids partial work, and any retry or recovery path is explicit.
+
+Useful negative cases include missing required fields, malformed values, expired sessions, duplicate submissions, permission failures, and upstream service errors.

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

@@ -0,0 +1,35 @@
+---
+id: lens.testing.spec-review.boundary-values
+type: context_lens
+title: Spec Review Boundary Values Lens
+version: 1
+owner: qa-platform
+status: stable
+tags:
+  - testing
+  - spec-review
+purpose: spec_review
+applies_to:
+  - context.testing.boundary-value-analysis
+focus:
+  - missing limits
+  - inclusive and exclusive boundaries
+  - empty and zero values
+  - overflow and retry limits
+expected_outputs:
+  - focused clarification questions
+  - boundary-related review findings
+  - unresolved source-of-truth gaps
+---
+
+# Spec Review Boundary Values Lens
+
+Interpret [Boundary Value Analysis](../../contexts/testing/boundary-value-analysis.md)
+for specification review. Identify missing limits, whether endpoints are
+inclusive or exclusive, behavior for empty and zero values, overflow behavior,
+and retry limits.
+
+Ask focused questions when the specification does not define those decisions.
+Record unresolved source-of-truth gaps instead of inventing a boundary. This
+Lens guides the consuming agent's interpretation; Renma validates its metadata
+and relationship to the Context Asset but does not apply the Lens at runtime.

package/examples/context-repo/renma.config.json

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

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

@@ -0,0 +1,66 @@
+---
+name: spec-review
+description: Review an incomplete product or test specification through focused clarification. Use when requirements need evidence-backed review notes; do not use for implementation or final approval.
+metadata:
+  renma.id: skill.testing.spec-review
+  renma.title: Spec Review
+  renma.version: "0.1.0"
+  renma.owner: qa-platform
+  renma.status: experimental
+  renma.tags: '["testing","spec-review"]'
+  renma.requires-context: '["contexts/testing/negative-testing.md"]'
+  renma.optional-context: '["context.domain.payment.idempotency"]'
+  renma.requires-lens: '["lens.testing.spec-review.boundary-values"]'
+---
+
+# Spec Review
+
+## Routing
+
+Use for incomplete specification clarification and evidence-backed review. The
+agent follows this Skill; Renma validates it and its declared relationships.
+
+## Required Inputs
+
+- The incomplete request, available criteria, examples, and references.
+- Known constraints, integrations, user states, and owners.
+
+## Repository Context
+
+This Skill is statically navigable inside this repository checkout. The
+consuming agent must open these relative links; Renma validates the matching
+asset IDs and relationships but does not load or inject their contents:
+
+- [Spec Review Boundary Values Lens](../../../lenses/testing/spec-review-boundary-values.md)
+- [Negative Testing](../../../contexts/testing/negative-testing.md)
+- [Example asset index](../../../README.md#repository-assets), which locates the
+  optional Payment Idempotency Context Asset for retryable payment writes
+
+Copying this `SKILL.md` without its linked assets is not a complete workflow.
+
+## Hard Constraints
+
+- Do not invent requirements, sources, or ownership. Ask a focused question;
+  when an answer is unavailable, record the gap and decision owner for human
+  review.
+
+## Clarification Workflow
+
+1. Inspect the request and available references.
+2. Separate facts from missing information, ambiguity, and conflicts.
+3. Ask about the most consequential gap. Record each answer and its source.
+4. Repeat until intended behavior, acceptance criteria, boundaries, error or
+   retry behavior, and remaining decision owners are clear enough for review.
+   Keep unavailable answers as unresolved questions.
+5. Open the linked Lens and Context Assets. Apply the Lens to boundary-value
+   analysis, use Negative Testing directly, and use Payment Idempotency only
+   for retryable payment writes.
+6. Record facts and sources, clarifications, assumptions, open questions,
+   applied Context and rationale, and findings with evidence and impact.
+7. Present the record to a human, who accepts, rejects, or corrects it.
+
+## Validation
+
+The review is ready for human judgment when each acceptance criterion has a
+positive path, a negative or unsupported-state path where relevant, and each
+material boundary or retry case. Unresolved issues remain explicit.

package/examples/context-repo/tools/appium/README.md

@@ -0,0 +1,14 @@
+---
+id: tool.appium.mobile-testing
+title: Appium Mobile Testing
+version: 0.1.0
+owner: qa-platform
+status: stable
+tags:
+  - testing
+  - mobile
+---
+
+# Appium Mobile Testing
+
+Use Appium for end-to-end mobile checks when the behavior depends on native platform UI, device permissions, or app lifecycle events. Keep scenarios narrow and pair them with faster lower-level tests when possible.

package/examples/github-actions/renma-ci-report.yml

@@ -0,0 +1,36 @@
+name: Renma CI Report
+
+on:
+  pull_request:
+
+jobs:
+  renma-ci-report:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - name: Generate Renma CI report
+        run: |
+          node dist/index.js ci-report . \
+            --from origin/${{ github.base_ref }} \
+            --to HEAD \
+            --format markdown > renma-ci-report.md
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: renma-ci-report
+          path: renma-ci-report.md