Cfn Persona Verify

CFN Persona Verify

Purpose: Drive the running app as a named role doing that role's actual job, and report where the implementation stops making sense from inside that role's head. Findings route through /cfn-vote-implement. This skill never auto-fixes code and never rewrites a role doc.

Status is beta: the protocol is unproven against a live app. The role-doc schema is enforced mechanically (validate-role-skills.sh, 21 controls). The walk itself is not.

The gap this fills

Every gate above compares the implementation to the plan. None compare the implementation to the role's reality. The failure class here is a build that is correct, coherent, mechanically green, and still wrong for the actor: a manager with no way to approve their staff's work, an approver who can approve their own submission, a coordinator whose landing page is a dead end.

This is the verify-time counterpart to cfn-spec 1b (Interaction Intent Walk). 1b catches intent drift while planning. This catches it after it ships.

Protocol owns procedure, projects own content

This skill is global and symlinked. It holds zero role knowledge. Role knowledge is per-project ground truth and lives in the project at .claude/skills/role-<slug>/SKILL.md.

The seam between them is ROLE_SKILL_SCHEMA.md, a required-section contract. Same pattern as SPEC 1a: one side declares the contract, the other fills it, neither owns both.

GLOBAL (this skill, symlinked)        PROJECT (never symlinked)
  how to discover roles          -->    .claude/skills/role-manager/SKILL.md
  how to drive the app                  .claude/skills/role-staff/SKILL.md
  how to classify a mismatch            .claude/skills/role-cdrc/SKILL.md
  manifest + report format
  the role-doc schema contract

A ## How to verify section inside a role doc is this protocol, copy-pasted. That is the duplication this skill deletes; the validator rejects it.

Step 1: Discover

1. Enumerate .claude/skills/role-*/SKILL.md in the current project.
2. Validate them: ./.claude/skills/cfn-persona-verify/validate-role-skills.sh. Any violation exits 3. Do not verify against a doc that failed the schema.
3. Where the plan's spec (planning/<slug>/SPEC_<slug>.md, or legacy flat planning/SPEC_*.md; resolve with $HOME/.claude/skills/cfn-megaplan/lib/plan-paths.sh resolve <slug> SPEC_<slug>.md) has a 1a. Actors section, use it as the actor list and resolve each actor to the role doc whose frontmatter actor: matches verbatim. Report, do not guess:
   • Actor in 1a with no role skill: gap. That actor cannot be verified.
   • Role skill matching no 1a actor: dead doc. Flag for deletion or for a missing 1a row.
4. Where no SPEC exists, the role docs are the actor list. Scoping comes from --ref instead (Step 2).

Step 2: Scope

Run only roles the change touches. Not every role, every time.

• With a SPEC: an actor is in scope if its 1a Touches (FR ids) intersects the FR ids the change implements. Automatic.
• Without a SPEC: pass the refs in play (--ref PR4,C8). A role is in scope if any of its capability rows cite one.

Name every skipped role and why. A silently skipped role reads as a passing role.

Step 3: Check freshness before trusting the doc

Compare the role doc's most recent ISO date against the change under review. A role doc older than the subsystem it describes is a finding in its own right, not a silent assumption. Report it; do not let it quietly become the baseline.

Step 4: Drive

Log in per ## Access. Do that role's actual job. Not a feature-by-feature click-through: walk the job the ## Capabilities table describes, in the order a real person would.

Read ## Known-state exceptions first, before filing anything. It is the list of things that look like bugs and are not.

For each capability row:

## Allowed and ## Denied are prose and are the decision record, not the checklist. Read them for the why, especially when deciding whether a mismatch is a bug or a superseded decision (Step 6). The table is what you drive.

Step 5: Execution safety

observe is the default and attempts no writes. It covers the primary case: a manager who navigates to the expenses queue and finds no Approve control on a submitted expense is a finding, established without writing anything.

seeded attempts a write, under one invariant:

The pass may only act on rows it created itself.

Any row that could write must be seeded, including a denied row. This is the rule that is easy to get backwards, and getting it backwards is how a verification pass damages real data. Checking that a manager cannot approve their own expense, by really attempting it against a pre-existing expense, means that if the block is broken you just approved a real person's real expense. That is the exact moment the check existed to protect you. Seeded, a broken block approves the pass's own throwaway row and you get the finding with no damage.

Safety comes from the marker invariant, not from the environment. A seeded row is safe even against production, because the pass only ever touches rows it made. An observe row is safe anywhere by construction. This skill therefore places no restriction on the target host, and verifying against a real deployment (where the real roles and real data live) stays viable.

Seed recipes declare Marker, Create, and Cleanup; the validator enforces that cleanup is scoped to the marker and rejects unscoped DELETE, any TRUNCATE, and FK-check disabling. Always clean up what you created, including on failure.

cfn: seeded execution trusts the project's marker convention. Upgrade trigger: a dedicated test tenant per project, if marker collisions with real data ever appear.

Step 6: Classify every mismatch

An unclassified mismatch is what teaches people to ignore the gate. Every finding is exactly one of three:

The not-yet-built bucket is load-bearing. Without it, the first run on any mature project reports every unbuilt feature as a regression and the gate is unusable on day one. The Ref column is what separates the buckets, which is why ROLE_SKILL_SCHEMA.md forbids an empty one.

Distinguishing implementation-wrong from doc-stale is what ## Allowed prose is for. If the app grants something the doc denies, but the doc's entry predates the PR that granted it, the doc is stale and the finding inverts.

Step 7: Outcomes per capability

blocked is a first-class outcome and is never reported as pass. A pass that had nothing to click proves nothing. Report every blocked with the reason.

Outputs

Two artifacts, deliberately separate.

1. Manifest (implementation-wrong findings only), at <project-root>/.cfn-cache/manifests/cfn-persona-verify-<ns>.json, in the shared cfn-vote-implement schema:

{
  "review_id": "persona-verify-<ns>",
  "source": "cfn-persona-verify",
  "generated_at": "ISO-8601",
  "status": "pending_review",
  "actors_checked": ["manager", "staff"],
  "actors_skipped": [{"actor": "board", "reason": "no ref overlap with this change"}],
  "suggestions": [
    {
      "id": "S001",
      "category": "missing-capability",
      "tag": "fix",
      "one_liner": "manager: no Approve affordance on a submitted expense (E1)",
      "title": "Manager cannot approve a staff expense",
      "description": "role-manager declares 'Approve a staff expense' at the Expenses queue, reaching status submitted -> approved. Drove as manager: submitted rows render, no Approve control present or reachable by any path.",
      "files": ["role-manager :: Capabilities :: Approve a staff expense", "E1"],
      "impact": "high",
      "effort": "medium",
      "suggested_approach": "Entry point resolves and lists submitted rows, so this is a missing affordance rather than a routing fault. See role-manager ## Allowed for the decision record.",
      "status": "pending",
      "related_suggestions": []
    }
  ]
}

Mapping: fail on a reachable row -> category: missing-capability, tag: fix. fail on a denied row -> category: privilege-leak, tag: block. Friction or coherence gaps with no correctness impact -> tag: harden. Stale-doc and not-yet-built findings never enter the manifest.

2. Doc-update proposals (doc-stale findings), surfaced via AskUserQuestion, batched 4 per call. Each proposes a dated entry for the role doc's ## Allowed or ## Denied prose. The user accepts or rejects. This skill never writes to a role doc.

The propose-never-write rule is the point. Auto-writing observed behavior into ground truth is how a bug becomes "working as designed" permanently. Those entries are human calls with dates and PR refs, and they stay that way.

Exit codes

Rules

• Local only. Not CI, not a GitHub Action.
• Never auto-fix. Findings route through /cfn-vote-implement.
• Never write to a role doc. Propose, and let the owner decide.
• Never act on a row the pass did not create.
• Never report blocked as pass.
• Read ## Known-state exceptions before filing any finding.
• Never invent an actor or a capability. If no role doc declares it, it is not checked.
• block-tagged findings are merge blockers regardless of vote outcome.

Usage

# validate the project's role docs against the schema first
$HOME/.claude/skills/cfn-persona-verify/validate-role-skills.sh

# spec-backed project: scoping is automatic from SPEC 1a
/cfn-persona-verify --fr FR-12,FR-13

# no spec: name the refs in play
/cfn-persona-verify --ref PR4,C8

# route findings through voting
/cfn-vote-implement latest

The walk is invoked as a skill, not a script: it needs judgment. Only the schema check is a script.

Related

• ROLE_SKILL_SCHEMA.md: the contract each project's role-<slug> skill must satisfy, and the migration steps for an existing doc.
• cfn-spec 1a Actors: the actor inventory this skill resolves against where a spec exists.
• cfn-spec 1b Interaction Intent Walk: the plan-time counterpart to this check.
• /cfn-vote-implement: votes on and routes the findings. Never implement them manually.
• cfn-a11y-gate, cfn-security-review: same emit-manifest, never-auto-fix flow.