renma 0.18.0 → 0.18.1

package/docs/quality-profile.md

@@ -5,7 +5,7 @@ the active profile as `renma-quality@<Renma package version>`, derived from
 `package.json` at build time. The source is `src/quality-profile.ts`. The current
 implementation does not expose quality overrides in `renma.config.json`; fixed
 defaults preserve comparable repository reports. The internal shape is
-versioned so later releases can add reviewed overrides without scattering
+versioned so later releases can add declared overrides without scattering
 constants across rules.
 
 `estimated_tokens` means Renma's deterministic, model-neutral estimate. Latin
@@ -14,6 +14,18 @@ grouped in two-code-point units; other punctuation is grouped in units of up to
 three code points. It is not an exact token count for any model. Skill budgets
 measure Markdown after frontmatter. Content-asset budgets measure the full file.
 
+Contexts, references, profiles, and examples may record a declared human
+decision and effective limit with top-level `token_budget_override` and
+`token_budget_rationale` metadata. The override must be a positive safe integer
+greater than the asset kind's unchanged default. Optional
+`token_budget_reviewed_at` must be a real `YYYY-MM-DD` date. Renma does not add
+these fields automatically. When an asset exceeds its default, an agent should
+first ask whether it can be split along meaningful boundaries without harming
+coherence or execution order, and split only after the user agrees. An override
+is appropriate only when the user confirms the long-form asset is intentionally
+coherent or ordered; it is not a general ignore mechanism. Renma validates the
+declaration but cannot prove that human review occurred.
+
 ## Agent Skills requirements and recommendations
 
 | Field | Value | Unit and trigger | Severity | Source | Rationale and false-positive risk | Diagnostic | Reviewed | Configurable later |
@@ -39,10 +51,10 @@ and `assets/` directories are valid. See the official
 | `descriptionMinChars` | 0 | characters; disabled | none | Renma | Length does not establish selection clarity | `QUAL-SHORT-DESCRIPTION` removed from default behavior | 0.18.0 | possibly |
 | `skillTokenWarn` | 2,000 | `estimated_tokens`; body above | low | Renma | Early progressive-disclosure review; focused workflows may exceed it | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | possibly |
 | `skillTokenStrongWarn` | 5,000 | `estimated_tokens`; body above | medium | Agent Skills recommendation with Renma severity | Stronger review, not a required split | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | possibly |
-| `contentTokenWarn.context` | 4,000 | `estimated_tokens`; full file above | low | Renma | Review coherent scope; size alone is insufficient | `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` | 0.18.0 | possibly |
-| `contentTokenWarn.reference` | 5,000 | same | low | Renma | Detailed local references may legitimately be long | same | 0.18.0 | possibly |
-| `contentTokenWarn.profile` | 2,000 | same | low | Renma | Profiles should remain reviewable overlays | same | 0.18.0 | possibly |
-| `contentTokenWarn.example` | 2,500 | same | low | Renma | Complete examples may legitimately be long | same | 0.18.0 | possibly |
+| `contentTokenWarn.context` | 4,000 | `estimated_tokens`; full file above effective limit | low | Renma | Prefer an agreed semantic split when coherence survives; intentionally coherent or ordered assets may record a declared decision | `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` | 0.18.1 | metadata only after human decision |
+| `contentTokenWarn.reference` | 5,000 | same | low | Renma | Detailed local references may legitimately be long | same | 0.18.1 | same |
+| `contentTokenWarn.profile` | 2,000 | same | low | Renma | Profiles should remain reviewable overlays | same | 0.18.1 | same |
+| `contentTokenWarn.example` | 2,500 | same | low | Renma | Complete examples may legitimately be long | same | 0.18.1 | same |
 | `lowHeadingDensityMinTokens` | 400 | body `estimated_tokens`, with fewer than 2 headings | low | Renma | Long prose can still be intentionally linear | `QUAL-LOW-HEADING-DENSITY` | 0.18.0 | possibly |
 | `lowHeadingDensityMinHeadings` | 2 | headings | low | Renma | Navigation heuristic only | same | 0.18.0 | possibly |
 

package/docs/user-manual.md

@@ -711,7 +711,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 +722,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

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.1",
   "description": "Manage human-curated context assets for LLMs and agents in Git.",
   "license": "MIT",
   "repository": {