Public-ready repository skill

Secret-boundary inspection

Produces a canary-proven, scope-explicit secret-material observation for a repository, exact proposed index, locally available history, or named artifact. Applies before snapshot, publication, delivery, or receiving-repository handoffs where credential-shaped material could travel.

Source and version

Repository path
.agents/skills/secret-boundary-inspection/SKILL.md
Source revision
341bceb719a28be760775b6322021d78abaa919b
Source SHA-256
0fc2cc964ed65457fdea77ea1494756b0c1c618d30c0622094ae7c089374405d
Publication standing
Public ready

Included source files

Complete skill source

The Markdown below matches the exact source text. The format link above opens the file on its own.

---
name: secret-boundary-inspection
description: Produces a canary-proven, scope-explicit secret-material observation for a repository, exact proposed index, locally available history, or named artifact. Applies before snapshot, publication, delivery, or receiving-repository handoffs where credential-shaped material could travel.
---

# Secret-boundary inspection

## Contract

- **What:** A repository-grounded method for proving the selected detector path with a fresh synthetic canary, observing one named material scope, and returning a safe, bounded receipt or finding response.
- **When:** Source, an exact proposed index, locally available history, or a named generated artifact is preparing to cross a snapshot, publication, delivery, or repository-reception boundary.
- **Boundaries:** The repository-owned implementation defines the engine, version, configuration, commands, and supported scopes. This skill supplies neither universal secret absence nor authority to validate a credential, publish material, rotate access, rewrite history, change refs, or disclose a finding. Those actions keep their existing owners and authorization boundaries.
- **Result:** The detector path proves itself before interpretation; each requested scope returns zero unresolved matches or enters a private response route; and the receipt names what was observed, what it establishes, and where its evidence stops.

## Fit and attention

- **Useful when:** A commit, snapshot, successor population, publication input, ignored build output, or other named repository artifact may carry credential-shaped material.
- **Poor fit when:** The task is live credential administration, vulnerability intake, Notion ancestry or publication approval, signed-out route verification, or exhaustive Git-object forensics.
- **Smallest useful dose:** One verified local implementation, one fresh generated canary, one precisely named scope, and one safe receipt.
- **Foregrounds:** Detector liveness, scope identity, exact-index behavior, local-ref limits, sensitive report handling, reviewed exceptions, and receiving-repository re-observation.
- **May under-attend:** Semantic publication standing, service-side exposure, binary-object history, unfetched refs, forks, caches, and provider validity; those claims retain their fitting observations.
- **Interactions:** `repository-reentry` establishes current source and Git standing. `locator-boundary-stewardship` owns public locator placement. `source-authority-mapping` distinguishes source, projection, and receiving roles. `collaboration-accounting` receives real findings, receiver friction, and changed tool behavior.
- **Rest or release when:** No material boundary is active, a smaller existing repository check already supplies the same receipt, or the selected implementation no longer owns the requested scope.

## Rules

### Rule: Repository behavior authority leads

Read the nearest repository guidance, executable wrapper, reviewed configuration, pinned-version record, and focused tests before invoking or changing the mechanism. A portable contract routes the observation; it does not replace the receiving repository's implementation evidence.

### Rule: A fresh canary precedes interpretation

Generate a new non-issued provider-shaped value for each run and require the selected material rule, finding exit, parser, redaction, and safe-output path to detect it together. Keep the canary in transient process input rather than a reusable tracked fixture. A failed canary stops interpretation of later clean output.

### Rule: Every receipt names its scope

Distinguish the working tree and explicitly included ignored material, the exact proposed Git index, diff-visible history across locally available refs, and one contained artifact path. Do not let one clean scope stand in for another.

### Rule: History claims follow ref acquisition

Establish whether the clone is complete and which refs are locally available before a history observation. State unfetched remotes, forks, dangling objects, caches, GitHub-native prose, and binary content omitted from textual patches as evidence limits rather than implied coverage.

### Rule: Scanner output receives a narrow information diet

Treat raw reports, scanner diagnostics, matched values, filenames, commit messages, fingerprints, and free-text attributes as potentially sensitive. Keep them local and ephemeral. Durable output carries only the repository wrapper's allowlisted orientation and never the candidate value.

### Rule: Exceptions remain source-readable and singular

Use the repository's one reviewed configuration surface for non-credential fixtures or indirections. A new suppression names its exact scope, value or rule shape, rationale, and focused test. Hidden ignore files, accumulating baselines, and inline allowances enter only when the repository contract explicitly adopts them.

### Rule: A finding pauses the affected handoff

Keep the candidate inside private triage. When live access is plausible, route revocation or rotation to the credential owner before repository cleanup and coordinated history work. Resume only after the affected copies are addressed and the canary plus changed scopes pass again.

### Rule: A receiving repository observes its own assembly

A successor or delivery repository reruns its accepted implementation after population. The source repository's clean receipt is useful lineage, not a substitute for observing the receiving tree, index, locally available history, and named artifacts.

## Operating sequence

1. **Bind the handoff:** Name the source state, receiving event, requested scopes, repository implementation owner, and the person or Issue that can accept the receipt.
2. **Verify the mechanism:** Confirm the pinned executable and reviewed configuration; run focused implementation tests when the wrapper, engine, rules, or scope behavior changed.
3. **Prove the path:** Run the fresh synthetic canary and stop if detection, redaction, parsing, or safe output differs from the accepted contract.
4. **Observe each scope:** Run only the named tree, exact-index, local-history, or artifact routes. Complete clone and ref acquisition before making the corresponding history claim.
5. **Respond or receive:** Keep findings private and pause the affected handoff, or record a clean scope-bound receipt with engine version, configuration identity, canary result, and evidence limits.
6. **Return the result:** Place the safe receipt with the receiving Issue or pull request. A successor repeats the observation after assembly; material friction returns through collaboration accounting.

## Representative scenarios

### Scenario: A successor receives an accepted source snapshot

- Given the source repository has a canary-proven clean receipt
- And the successor has assembled its own tree and refs
- When the successor prepares to accept the snapshot
- Then it verifies its local implementation and runs a fresh canary
- And it observes its own tree, exact index, locally available history, and named delivery artifacts
- And its receipt names any coverage that remains outside those scopes

### Scenario: The detector reports a candidate

- Given the generated canary has proved the detector and safe-output path
- When a named material scope returns a finding
- Then the affected handoff pauses
- And the candidate remains outside Issues, pull requests, retained reports, and ordinary transcripts
- And the credential owner receives the private response route before cleanup or coordinated history work proceeds

## Conditional context

In Human-AI Systems Exemplars, load the [repository secret-material boundary](../../../threadkeeping/repository-secret-material-boundary.md) before invoking or changing the scanner. It owns the current Betterleaks version, exact commands, scope topology, reviewed exception surface, safe-output contract, evidence limits, and successor handoff.

## Completion

The inspection completes when the canary has proved the accepted detector path, every requested scope has a zero-finding receipt or a named private response owner, the evidence boundary is explicit, and the receiving handoff knows whether it can proceed. A changed engine, configuration, scope, receiver, or real finding can reopen the contract.