---
name: sirno-witness
description: >-
  Create, refine, or review Sirno repository witnesses. Use for inserting or splitting
  `sirno:witness:<entry-id>:begin` blocks, linking code/tests/config to Sirno Lake entries,
  deciding whether a witness needs a new or more specific Sirno Lake entry, interpreting
  `sirno_entry_witness` output, or checking whether a Sirno entry has precise repository evidence.
---

# Sirno Witness

## Purpose

Use this skill when linking Sirno Lake entries to repository evidence.
A witness is a repository region that makes an entry claim inspectable.
The entry id is the query key.
This full skill text is served as the MCP resource `sirno://skills/sirno-witness`.
It follows the `witness-linking-discipline` lake entry.

## MCP Project Resolution

When using Sirno through MCP, call `sirno_cwd` with the repository root before project tools
if the server started without `--config`.
Project tools resolve `Sirno.toml` on every project tool call from the current server cwd.
Call `sirno_cwd` again before switching projects in the same server process.

## Core Principles

Keep the lake entry and repository artifact separate.
The entry states the claim in project language.
The witness block identifies where that claim can be inspected in code, tests, config, assets,
or generated artifacts.

Use repository witness blocks only when repository evidence exists.
Do not describe future evidence as present.
Do not invent witness ids or query strings separate from the entry id.

Prefer precise witness regions.
A block should cover the smallest durable region that supports the entry claim.
Multiple small blocks for one entry are better than one broad block that forces a reviewer to hunt.

Create a new entry when the evidence supports a related but different claim.
Do not reuse a near-enough entry id just to avoid lake editing.
Create a more specific entry when the evidence supports a narrower claim.
Use the configured structural fields for navigation.
This repository recommends `refines` for broader-entry targets and `belongs` for review locality.
Keep the same `belongs` target when the evidence belongs to the same module-like review unit.
Add another `belongs` target when the entry sits at a real intersection that should be reviewed from both sides.
Create a new `belongs` target only when the evidence belongs to a new design/program boundary.
Avoid ad hoc suffixes such as `entry#parser`; use real entry ids.

Do not duplicate `mosaika` behavior in Sirno.
Let Sirno call `mosaika` for delimiter matching, region extraction, and spans.
Sirno-side code should consume structured scan output and format it for review.

## Linking Workflow

Read the target entry before editing code.
Understand the claim, its structural fields, and any body guidance about what evidence should mean.

If no existing entry matches the witness need precisely,
create or propose a compact Sirno Lake entry before adding markers.
Keep the witness id tied to that exact entry claim.

Inspect current witnesses before adding new ones:

```json
{"id": "ENTRY_ID"}
```

Choose the evidence region deliberately.
Prefer a single item, test case, config stanza, generated boundary, or small cohesive block.
If the current region is too broad, split it into smaller blocks with the same entry id.

Add the repository block inside configured `[repo].members` paths.
If no repo members are configured, configure the intended repository artifact surface first:

```rust
// sirno:witness:entry-id:begin
// witnessed repository region
// sirno:witness:entry-id:end
```

For Markdown artifacts, use hidden HTML comment sentinels instead of visible line comments.
Always check `[[witness.delimiters]]` before adding markers.
Use the configured delimiter syntax.

For Rust, place witness comments around stable items or focused implementation spans.
Avoid wrapping unrelated helpers just because they are nearby.

Update the entry prose when needed so it briefly says what the witness region demonstrates.
Leave generated footer regions untouched.

If no repository evidence exists,
do not add a placeholder witness.
Report the claim as unwitnessed and create or revise an entry only when that gives review
a more precise handle.

If the intended file sits outside configured repository members,
update the config only when that file is truly part of the witness surface.
Otherwise choose evidence already inside the configured surface or report the mismatch.
Use `sirno-config-writer` for the `Sirno.toml` edit itself.

## Validation

After adding or changing witnesses, run the direct witness query:

```json
{"id": "ENTRY_ID"}
```

Then run structural validation:

```text
sirno_lake_check mode=review
```

If Sirno Lake metadata or links changed, run:

```text
sirno_lake_render
```

Review the full witness output as a human would.
The output should show concise ranges, literal matched regions, and no broad unrelated code.
