renma 0.17.0 → 0.18.1

package/docs/schemas/trust-graph-v2.schema.json

@@ -0,0 +1,301 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/KazuCocoa/renma/blob/main/docs/schemas/trust-graph-v2.schema.json",
+  "title": "Renma Trust Graph v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "summary", "nodes", "edges", "findings"],
+  "properties": {
+    "schemaVersion": { "const": "renma.trustGraph.v2" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "nodes": { "type": "array", "items": { "$ref": "#/$defs/node" } },
+    "edges": { "type": "array", "items": { "$ref": "#/$defs/edge" } },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } }
+  },
+  "$defs": {
+    "nodeTypes": {
+      "enum": [
+        "asset",
+        "owner",
+        "lifecycle_status",
+        "security_profile",
+        "effective_policy",
+        "diagnostic"
+      ]
+    },
+    "edgeTypes": {
+      "enum": [
+        "owned_by",
+        "has_lifecycle_status",
+        "declares_dependency",
+        "references",
+        "owns_local_resource",
+        "statically_references",
+        "inherits_owner",
+        "selects_security_profile",
+        "inherits_policy",
+        "has_effective_policy",
+        "has_diagnostic"
+      ]
+    },
+    "severity": {
+      "enum": ["critical", "high", "medium", "low", "error", "warning", "info"]
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "assetCount",
+        "nodeCount",
+        "edgeCount",
+        "findingCount",
+        "nodeTypeCounts",
+        "edgeTypeCounts",
+        "findingSeverityCounts",
+        "riskClassCounts"
+      ],
+      "properties": {
+        "assetCount": { "type": "integer", "minimum": 0 },
+        "nodeCount": { "type": "integer", "minimum": 0 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "findingCount": { "type": "integer", "minimum": 0 },
+        "nodeTypeCounts": { "$ref": "#/$defs/nodeCounts" },
+        "edgeTypeCounts": { "$ref": "#/$defs/edgeCounts" },
+        "findingSeverityCounts": { "$ref": "#/$defs/severityCounts" },
+        "riskClassCounts": { "$ref": "#/$defs/riskCounts" }
+      }
+    },
+    "nodeCounts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "asset",
+        "owner",
+        "lifecycle_status",
+        "security_profile",
+        "effective_policy",
+        "diagnostic"
+      ],
+      "properties": {
+        "asset": { "type": "integer", "minimum": 0 },
+        "owner": { "type": "integer", "minimum": 0 },
+        "lifecycle_status": { "type": "integer", "minimum": 0 },
+        "security_profile": { "type": "integer", "minimum": 0 },
+        "effective_policy": { "type": "integer", "minimum": 0 },
+        "diagnostic": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "edgeCounts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "owned_by",
+        "has_lifecycle_status",
+        "declares_dependency",
+        "references",
+        "owns_local_resource",
+        "statically_references",
+        "inherits_owner",
+        "selects_security_profile",
+        "inherits_policy",
+        "has_effective_policy",
+        "has_diagnostic"
+      ],
+      "properties": {
+        "owned_by": { "type": "integer", "minimum": 0 },
+        "has_lifecycle_status": { "type": "integer", "minimum": 0 },
+        "declares_dependency": { "type": "integer", "minimum": 0 },
+        "references": { "type": "integer", "minimum": 0 },
+        "owns_local_resource": { "type": "integer", "minimum": 0 },
+        "statically_references": { "type": "integer", "minimum": 0 },
+        "inherits_owner": { "type": "integer", "minimum": 0 },
+        "selects_security_profile": { "type": "integer", "minimum": 0 },
+        "inherits_policy": { "type": "integer", "minimum": 0 },
+        "has_effective_policy": { "type": "integer", "minimum": 0 },
+        "has_diagnostic": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "severityCounts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "critical",
+        "high",
+        "medium",
+        "low",
+        "error",
+        "warning",
+        "info"
+      ],
+      "properties": {
+        "critical": { "type": "integer", "minimum": 0 },
+        "high": { "type": "integer", "minimum": 0 },
+        "medium": { "type": "integer", "minimum": 0 },
+        "low": { "type": "integer", "minimum": 0 },
+        "error": { "type": "integer", "minimum": 0 },
+        "warning": { "type": "integer", "minimum": 0 },
+        "info": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "riskCounts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["violation", "suspicious", "advisory", "unclassified"],
+      "properties": {
+        "violation": { "type": "integer", "minimum": 0 },
+        "suspicious": { "type": "integer", "minimum": 0 },
+        "advisory": { "type": "integer", "minimum": 0 },
+        "unclassified": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["path", "startLine", "endLine", "snippet"],
+      "properties": {
+        "path": { "type": "string" },
+        "startLine": { "type": "integer" },
+        "endLine": { "type": "integer" },
+        "snippet": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "inheritedFrom": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "sourcePath"],
+      "properties": {
+        "id": { "type": "string" },
+        "sourcePath": { "type": "string" }
+      }
+    },
+    "edgeProperties": {
+      "type": "object",
+      "properties": {
+        "policySources": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "local",
+              "security_profile",
+              "repository_config",
+              "owning_skill"
+            ]
+          }
+        },
+        "ownershipSource": { "enum": ["declared", "inherited"] },
+        "inheritedFrom": { "$ref": "#/$defs/inheritedFrom" }
+      },
+      "additionalProperties": true
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "label"],
+      "properties": {
+        "id": { "type": "string" },
+        "type": { "$ref": "#/$defs/nodeTypes" },
+        "label": { "type": "string" },
+        "properties": { "type": "object" },
+        "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence" } }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "from", "to", "type"],
+      "properties": {
+        "id": { "type": "string" },
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "type": { "$ref": "#/$defs/edgeTypes" },
+        "properties": { "$ref": "#/$defs/edgeProperties" },
+        "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence" } }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "owned_by" } },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["properties"],
+            "properties": {
+              "properties": {
+                "type": "object",
+                "required": ["ownershipSource"],
+                "allOf": [
+                  {
+                    "if": {
+                      "type": "object",
+                      "properties": {
+                        "ownershipSource": { "const": "inherited" }
+                      },
+                      "required": ["ownershipSource"]
+                    },
+                    "then": {
+                      "type": "object",
+                      "required": ["inheritedFrom"]
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": { "const": "has_effective_policy" }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["properties"],
+            "properties": {
+              "properties": {
+                "type": "object",
+                "required": ["policySources"],
+                "allOf": [
+                  {
+                    "if": {
+                      "type": "object",
+                      "properties": {
+                        "policySources": {
+                          "type": "array",
+                          "contains": { "const": "owning_skill" }
+                        }
+                      },
+                      "required": ["policySources"]
+                    },
+                    "then": {
+                      "type": "object",
+                      "required": ["inheritedFrom"]
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      ]
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "severity", "message"],
+      "properties": {
+        "source": { "enum": ["finding", "diagnostic"] },
+        "severity": { "$ref": "#/$defs/severity" },
+        "message": { "type": "string" },
+        "path": { "type": "string" },
+        "code": { "type": "string" },
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "riskClass": { "enum": ["violation", "suspicious", "advisory"] },
+        "evidence": { "$ref": "#/$defs/evidence" }
+      }
+    }
+  }
+}

package/docs/security-policy.md

@@ -294,7 +294,7 @@ Security findings may include `riskClass` so reviewers can distinguish clear vio
 
 Renma can summarize security posture from existing static security findings. The summary groups findings by `riskClass` (`violation`, `suspicious`, `advisory`, and `unclassified`) and by severity, and reports high/critical security finding counts.
 
-This is reporting-only in v1:
+This is reporting-only in the v2 contract:
 
 - it does not add new detectors
 - it does not change scan `fail_on`
@@ -306,17 +306,33 @@ Runtime enforcement remains outside Renma.
 
 ### Effective policy inventory
 
-Renma can also summarize the effective static policy surface across discovered assets. The inventory is derived from asset-local policy metadata, selected security-profile chains, and repository-level `security` config.
+Renma can also summarize the effective static policy surface across discovered assets. The inventory distinguishes assets with local metadata, inherited policy, effective policy, and no effective policy.
 
-The inventory reports policy coverage, network/upload/secrets booleans, human approval requirements, approved destinations, forbidden inputs, disallowed commands, and profile resolution counts. It is reporting-only in v1 and does not enforce runtime behavior.
+Script and asset bytes never declare local policy. Skill-local scripts and
+assets inherit policy only from one unambiguous owning Skill. Text scripts may
+be scanned under that inherited policy from line 1; ordinary output assets and
+binary files never contribute instruction text. Orphan scripts do not receive
+policy-dependent evaluation from repository configuration without an owning
+Skill and traceable inheritance evidence.
 
-`renma trust-graph` also includes effective policy evidence. Each effective policy node uses a deterministic fingerprint over normalized allowed data, forbidden inputs, network/upload/secrets booleans, human approval requirement, approved destinations, and disallowed commands. The graph links assets to selected security-profile values and to their effective policy fingerprint; it does not enforce the policy at runtime.
+The inventory reports local, inherited, effective, and missing-effective coverage; network/upload/secrets booleans; human approval requirements; approved destinations; forbidden inputs; disallowed commands; and profile resolution counts. It is reporting-only in v2 and does not enforce runtime behavior.
+
+`renma trust-graph` also includes effective policy evidence. Each effective policy node uses a deterministic fingerprint over normalized allowed data, forbidden inputs, network/upload/secrets booleans, human approval requirement, approved destinations, and disallowed commands. Every `has_effective_policy` edge carries a deterministic `policySources` array containing each source that contributed to the fingerprint: `local`, `security_profile`, `repository_config`, and/or `owning_skill`. Owning-Skill inheritance retains `inheritedFrom`, and selected-profile evidence retains the selected profile and profile chain. The graph does not enforce policy at runtime.
+
+Contribution is recorded during effective-policy resolution with the same
+precedence, fail-closed, replacement, accumulation, and deduplication rules. A
+profile scalar overridden by local metadata is not a contribution. For
+accumulating lists, every source that supplies a value is retained even when
+another source supplies the same value and the effective list deduplicates it.
+Source order is always `local`, `security_profile`, `repository_config`,
+`owning_skill`. For inherited support, `local` refers to local metadata on the
+owning Skill, while `owning_skill` identifies the inheritance channel.
 
 ### Security-aware semantic diff
 
 `renma diff` and `renma ci-report` can summarize how security posture and effective security policy inventory changed between two revisions.
 
-The diff uses existing static findings and existing policy metadata/config summaries. It does not add new detectors, change runtime behavior, change scan `fail_on`, change readiness scoring, or change CI pass/warn/fail status in v1.
+The diff uses existing static findings and existing policy metadata/config summaries. It does not add new detectors, change runtime behavior, change scan `fail_on`, change readiness scoring, or change CI pass/warn/fail status.
 
 ## Common Security Diagnostics
 

package/docs/trust-graph.md

@@ -0,0 +1,47 @@
+# Trust Graph v2 Contract
+
+Renma 0.18.0 emits only `renma.trustGraph.v2`, the first supported long-term
+Trust Graph contract. The authoritative machine-readable definition is the
+[Trust Graph v2 JSON Schema](schemas/trust-graph-v2.schema.json).
+
+The required top-level fields are `schemaVersion`, `summary`, `nodes`, `edges`,
+and `findings`. Node `properties` and node and edge `evidence` are optional.
+Edge `properties` are optional except where an edge-specific provenance rule
+requires them. Finding identity fields (`code`, `id`, `title`, `riskClass`,
+`path`, and `evidence`) appear only when supplied. Missing optional fields are
+omitted, not serialized as `null`.
+
+Nodes are ordered by type and stable ID; edges by source, type, target, and ID;
+findings by deterministic review order. Summary maps contain all enum members
+with non-negative integer counts. Asset nodes include normalized ownership and
+first-class support evidence.
+Static support uses `owns_local_resource`, `statically_references`,
+`inherits_owner`, and `inherits_policy`. Every `owned_by` edge declares
+`ownershipSource`; when its value is `inherited`, the edge also retains an
+`inheritedFrom` object with the owning asset ID and source path. Every
+`has_effective_policy` edge has a non-empty, duplicate-free `policySources`
+array. Its values are limited to `local`, `security_profile`,
+`repository_config`, and `owning_skill`, in that generated order. Effective
+policy inherited from an owning Skill retains `inheritedFrom`.
+
+Representative complete top-level document:
+
+```json
+{
+  "schemaVersion": "renma.trustGraph.v2",
+  "summary": {
+    "assetCount": 0, "nodeCount": 0, "edgeCount": 0, "findingCount": 0,
+    "nodeTypeCounts": { "asset": 0, "owner": 0, "lifecycle_status": 0, "security_profile": 0, "effective_policy": 0, "diagnostic": 0 },
+    "edgeTypeCounts": { "owned_by": 0, "has_lifecycle_status": 0, "declares_dependency": 0, "references": 0, "owns_local_resource": 0, "statically_references": 0, "inherits_owner": 0, "selects_security_profile": 0, "inherits_policy": 0, "has_effective_policy": 0, "has_diagnostic": 0 },
+    "findingSeverityCounts": { "critical": 0, "high": 0, "medium": 0, "low": 0, "error": 0, "warning": 0, "info": 0 },
+    "riskClassCounts": { "violation": 0, "suspicious": 0, "advisory": 0, "unclassified": 0 }
+  },
+  "nodes": [],
+  "edges": [],
+  "findings": []
+}
+```
+
+Within v2, evolution is additive and backward-compatible. Removing or changing
+an existing field requires a new schema version. Enum additions are
+consumer-visible and must be documented.

package/docs/user-manual.md

@@ -79,6 +79,17 @@ 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.
+
+Only files marked Markdown-parser eligible contribute frontmatter metadata,
+headings, links, code fences, and repeated-context evidence. Text scripts and
+data assets remain raw text for dedicated static path or security analysis;
+binary assets remain opaque.
+
 Avoid using reserved support directory names as skill names. Paths such as
 `skills/assets/SKILL.md`, `skills/examples/SKILL.md`,
 `skills/references/SKILL.md`, `skills/scripts/SKILL.md`, and
@@ -233,7 +244,7 @@ renma bom . --format markdown
 renma bom . --format json
 ```
 
-The BOM is a declared repository manifest. It combines catalog, graph, diagnostics, readiness, lifecycle, hash, and security posture evidence. It is not a record of actual LLM runtime usage. See the [Repository Context BOM contract](repository-context-bom.md) for the v1 boundaries.
+The BOM is a declared repository manifest. It combines catalog, graph, diagnostics, readiness, lifecycle, hash, and security posture evidence. It is not a record of actual LLM runtime usage. See the [Repository Context BOM contract](repository-context-bom.md) for v2 boundaries.
 
 ## User Story: Improve Existing Skills With Diagnostics
 
@@ -366,7 +377,9 @@ The JSON configuration supports the same names used by the implementation, inclu
 - `globs`: glob patterns to scan.
 - `exclude`: paths or path prefixes to skip.
 - `suppressions`: rule suppressions that remove matching findings from normal reports and failure thresholds.
-- `max_file_size_bytes`: largest file renma will read.
+- `max_file_size_bytes`: largest file renma will read for content analysis. A
+  larger discovered file remains repository existence evidence, so a valid
+  reference is not also reported as missing.
 - `max_depth`: maximum discovery depth.
 - `concurrency`: scan concurrency.
 - `fail_on`: scan exit threshold: `low`, `medium`, `high`, or `critical`.
@@ -388,6 +401,13 @@ against the collected repository snapshot. It validates the declared path but
 does not execute the command. Non-Skill documents do not receive an inferred
 Skill-relative base.
 
+Static support reachability accepts explicit Skill-relative paths, explicit
+basenames, Markdown link targets, quoted/code-form paths, and one additional
+hop through a directly referenced index/reference. Free-prose matches against
+generic filename stems such as `run`, `check`, or `logo` are not evidence.
+Extensionless executables and quoted or linked asset paths with spaces are
+valid; `..` traversal outside the Skill root remains invalid.
+
 Use `exclude` for files Renma should not scan. Use `suppressions` for audited exceptions where Renma should scan the file, detect matching findings internally, then omit those findings from normal reports and failure decisions. A suppression applies only when both `id` and `paths` match. Each suppression includes `id`, `paths`, required `reason`, and optional `expires`; the reason lives in config for auditability.
 
 Use a date in `YYYY-MM-DD` for temporary workarounds, or `"never"` when the exception is intentionally permanent. Permanent suppressions should still use narrow path patterns and a clear reason. Suppression path patterns are repository-relative and support exact paths, directory-prefix matches for non-glob patterns, `*` within one path segment, and `**` across directories.
@@ -418,6 +438,12 @@ Other default scan glob families are:
 - `skills/**/references/**/*.md`
 - `skills/**/examples/**/*.md`
 - `skills/**/scripts/**/*`
+- `skills/**/assets/**/*`
+- `.agents/skills/**/profiles/**/*.md`
+- `.agents/skills/**/references/**/*`
+- `.agents/skills/**/examples/**/*.md`
+- `.agents/skills/**/scripts/**/*`
+- `.agents/skills/**/assets/**/*`
 - `tools/**/*`
 
 ## Where To Go Next
@@ -425,6 +451,7 @@ Other default scan glob families are:
 - New to Renma? Start with [Authoring Guide](authoring-guide.md).
 - Writing security-sensitive skills or context assets? Read [Security Policy Guide](security-policy.md).
 - Fixing scan findings? See [Diagnostics Reference](diagnostics.md).
+- Reviewing thresholds? See [Renma Quality Profile](quality-profile.md).
 - Trying a minimal clarify-before-act Skill interaction? Use
   [`examples/interactive-placeholder`](../examples/interactive-placeholder).
 - Trying richer repository-aware Skill, Context Lens, and Context Asset
@@ -525,7 +552,7 @@ renma bom . --format markdown
 renma bom . --format json --omit-generated-at
 ```
 
-Use the BOM when reviewers or CI consumers need one repository evidence manifest that combines existing Renma evidence: catalog asset inventory, repository-relative source paths, content hashes, owners, lifecycle metadata, tags, declared dependencies, graph resolution, diagnostics, readiness score and checks, workflow readiness, context lens summary, security posture, and security policy inventory. See the [Repository Context BOM contract](repository-context-bom.md) for the authoritative v1 schema, snapshot, reproducibility, provenance, and future consumed-context evidence boundaries.
+Use the BOM when reviewers or CI consumers need one repository evidence manifest that combines existing Renma evidence. Renma 0.18.0 supports only v2, the first supported long-term BOM contract. It does not provide a v1 compatibility mode. V2 includes normalized declared/effective ownership plus static support relationships. See the [Repository Context BOM contract](repository-context-bom.md).
 
 The BOM is not a record of actual LLM runtime usage. Renma does not collect telemetry, assemble prompts, choose task-specific context, inject context into agents, import consumed-context evidence, or claim what an LLM actually consumed.
 
@@ -597,7 +624,9 @@ Use this when a reviewer or downstream tool needs one stable evidence layer that
 
 Trust Graph is repository evidence. It does not compute a trust score, select or inject runtime context, assemble prompts, call an LLM, collect telemetry, or enforce policy at runtime.
 
-Output includes stable node IDs, stable edge IDs, source evidence where parser support exists, normalized effective policy fingerprints, diagnostic links, and compact summary counts. JSON is the source of truth for downstream tools; Markdown is for human review. `scan --format json` includes the same Trust Graph under `trustGraph` so CI consumers can read one scan report when they do not need a separate command.
+Renma 0.18.0 supports only Trust Graph v2, the first supported long-term contract. It includes normalized ownership and static `owns_local_resource`, `statically_references`, `inherits_owner`, and `inherits_policy` evidence. JSON is the source of truth; Markdown is for human review. `scan --format json` includes the same v2 contract under `trustGraph`.
+
+Consumers must branch on `schemaVersion`, not on the Renma package version. A future incompatible contract may intentionally introduce v3.
 
 Reviewers can use Trust Graph to find assets without owners, find assets without lifecycle status, inspect assets sharing the same effective policy fingerprint, and connect diagnostics back to asset evidence. `trust-graph` exits `0` when the report is generated successfully; use `scan --fail-on` when CI should fail on findings.
 
@@ -655,7 +684,7 @@ The report summarizes readiness deltas, graph-resolution changes, added and remo
 
 Output includes a CI status (`PASS`, `WARN`, or `FAIL`), a summary, readiness changes, graph changes, and review-focused finding changes.
 
-Repository Context BOM artifacts describe declared repository state, not prompt assembly, context injection, agent execution, actual LLM runtime usage, or telemetry. Use `renma bom . --format json` when CI needs a machine-readable manifest and `renma bom . --format markdown` for review comments or artifacts. For v1 compatibility and reproducibility details, see the [Repository Context BOM contract](repository-context-bom.md).
+Repository Context BOM artifacts describe declared repository state, not prompt assembly, context injection, agent execution, actual LLM runtime usage, or telemetry. Use `renma bom . --format json` when CI needs a machine-readable manifest and `renma bom . --format markdown` for review comments or artifacts. For v2 compatibility and reproducibility details, see the [Repository Context BOM contract](repository-context-bom.md).
 
 ### `ownership`
 
@@ -682,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
@@ -691,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.