---
name: lifecycle-status-guard-scan
description: Use when Codex needs to scan Markdown, JSON, YAML, or text files for lifecycle/status overclaims such as stable, accepted, owner-approved, CCRA-approved, released, production-ready, final, or equivalent Chinese phrasing before review, release, handoff, or governance work.
---

# Lifecycle Status Guard Scan

## Purpose

Run a deterministic, configurable scan for lifecycle/status claim candidates. Use the bundled script to produce Markdown and JSON reports that a human, Owner, CCRA reviewer, or upper-layer agent can judge.

The scanner is evidence-producing only. It must not edit status fields, promote or downgrade lifecycle state, or decide whether an approval claim is true.

## Command

```powershell
conda run -n skills-vault python .\scripts\lifecycle_status_guard_scan.py `
  --scan-root C:\path\project `
  --config C:\path\lifecycle-guard-config.yaml `
  --output-dir C:\path\helper-outputs
```

When installed under `C:\Users\wangq\.agents\skills\lifecycle-status-guard-scan`, run from that Skill directory or use the installed script path.

## Config

```yaml
watched_paths:
  - "**/*.md"
  - "**/*.json"
  - "**/*.yaml"
status_fields:
  - status
  - lifecycle
forbidden_status_values:
  - stable
  - accepted
warning_status_values:
  - candidate
required_evidence_markers:
  - owner_decision
  - ccra_review
approved_phrases:
  - owner-approved
  - ccra-approved
  - 所有者批准
forbidden_phrases:
  - production-ready
allowed_contexts:
  - do not say
  - example:
```

Config files may be JSON, YAML, or YML.

## Rules

- Treat `approved_phrases` as approval-claim phrases requiring evidence. They are not a whitelist and do not mean the claim is accepted.
- If an approval claim phrase lacks a nearby `required_evidence_markers` match, report a blocking phrase finding.
- If an approval claim phrase has nearby evidence, report only an evidence-present observation. Do not judge whether the approval is real.
- For structured fields, associate evidence only within the same front matter block or JSON/YAML object that contains the matched field.
- For phrase claims, associate evidence only within the configured nearby text window, default 240 characters.
- Apply `allowed_contexts` only to phrase-level claims, such as negations, examples, or policy text. Never use allowed contexts to exempt structured fields like `status: stable`.

## Outputs

The script writes:

```text
lifecycle-status-guard-scan.md
lifecycle-status-guard-scan.json
```

Reports include:

- files scanned
- possible overclaims
- field-level findings
- phrase-level findings
- missing evidence markers
- warnings
- blocking errors
- evidence-present observations
- machine-readable summary

Exit code is `1` when blocking findings exist and `0` when the scan has only warnings or observations.

## Safety

- Read only configured files under `scan_root`.
- Write only the two report files under `output_dir`.
- Do not modify scanned files.
- Do not treat evidence markers as proof of approval; they only prevent a missing-evidence blocking result.

## Validation

After changing scanner behavior, run:

```powershell
conda run -n skills-vault python -B -m unittest discover -s skills/lifecycle-status-guard-scan/tests -v
conda run -n skills-vault python -B C:\Users\wangq\.codex\skills\.system\skill-creator\scripts\quick_validate.py skills/lifecycle-status-guard-scan
```