---
id: workspace-capture
version: 0.1.0
name: "Workspace Capture and Evaluation"
description: "Inspect the active workspace and capture observable compliance evidence with redaction and provenance, including docs, runbooks, scripts, configs, generated reports, or a concise workspace-evaluation summary."
use_when: "The auditor needs generic evidence from the active workspace, the evidence expectation is broad or hard to classify, or the artifact is broader than a source-code snippet. Use it for runbooks, policy drafts, exported reports, operational configuration, scripts, and workspace evaluation summaries."
produces: evidence
author: "Pretorin Core Team"
license: Apache-2.0
requires:
  sources:
    - kind: workspace_repo
      binding_role: primary
      probe: "git rev-parse --show-toplevel"
      source_version_kind: workspace_revision
params:
  source_path:
    type: string
    description: "Workspace-relative path, directory, glob, or summary label for the evaluated artifact"
    required: true
  source_locator:
    type: string
    description: "Optional section, selector, page, or line locator inside the artifact"
  source_version:
    type: string
    description: "Optional source version anchor such as a git commit, report id, or generated timestamp"
scripts:
  redact_secrets:
    path: scripts/redact_secrets.py
    description: "Run pretorin's secret redactor over the supplied workspace artifact text."
    params:
      text:
        type: string
        description: "Raw artifact text to scan and redact"
        required: true
  compose_artifact:
    path: scripts/compose_artifact.py
    description: "Compose an auditor-facing Markdown evidence body with provenance for any workspace artifact."
    params:
      content:
        type: string
        description: "Redacted artifact content to embed"
        required: true
      source_path:
        type: string
        description: "Workspace-relative path, directory, glob, or summary label for the captured artifact"
        required: true
      source_label:
        type: string
        description: "Human-readable artifact label"
      source_locator:
        type: string
        description: "Optional section, selector, page, or line locator"
      source_version:
        type: string
        description: "Optional source version anchor"
      user_prose:
        type: string
        description: "Short explanation of what the artifact demonstrates"
      secrets_redacted:
        type: integer
        description: "Number of secret-shaped values redacted before composition"
        default: 0
---

# Workspace Capture and Evaluation

Use this recipe when the evidence source is the active workspace and the work
does not fit a narrower recipe. It can capture one readable artifact, a small
set of related excerpts, or a concise summary of a workspace evaluation. Good
fits include Markdown runbooks, policy drafts, exported reports, shell scripts,
YAML configs, operational notes, or a searched-files summary for broad AI
guidance expectations.

## Procedure

1. Inspect the relevant workspace files. Prefer focused searches guided by
   the control's `ai_guidance.evidence_expectations`.
2. Assemble the artifact text: either the source file/excerpt itself or a
   concise evaluation summary that names the searched paths and observed facts.
3. Call `recipe_workspace_capture__redact_secrets(text=<artifact text>)`.
3. Call `recipe_workspace_capture__compose_artifact(...)` with the redacted
   content and provenance fields.
4. Push evidence with `create_evidence(..., recipe_context_id=<context_id>)`.

Use `source_uri` / `source_label` / `source_locator` / `source_excerpt` on the
write call to preserve the same structured provenance carried in the composed
body. For a workspace-evaluation summary, set `source_path` to the most useful
scope label such as `.` or `workspace search: audit logging files`, and list
the concrete inspected files in the content. Use the most meaningful
`source_version` available: git commit for repo files, report id for generated
exports, or capture timestamp when nothing stronger exists.
