frame-credit-ledger

name

frame-credit-ledger

description

Warn-only frame credit-ledger pre-PR hook orchestration. Use when Code-Conductor has just run `gh pr create` and needs to surface frame port-coverage gaps as a non-blocking ledger comment on the new PR, or when a maintainer wants to (re)run the ledger against an existing PR for observation. DO NOT USE FOR: plugin entry-point version-bump guardrails (use `plugin-release-hygiene`), post-merge cleanup or pre-merge strategic assessment (use `post-pr-review`), or any flow that should block PR creation — the ledger is warn-only and never gates the PR.

Frame credit-ledger

When to Use

• Code-Conductor has just run gh pr create (or an equivalent PR-creation step) and needs to post the warn-only port-coverage ledger before handing the PR back to the operator.
• A maintainer wants to (re)render the credit ledger comment on an existing PR for observation, without re-running the full conductor flow.
• The same Code-Conductor run is rebuilding context after a smart-resume and needs the ledger to reflect the current changeset's frame port coverage.
• The PR body already carries a <!-- pipeline-metrics ... --> block at metrics_version: 4 (the v4 frame additions sit on top of the inherited v3 base per frame/pipeline-metrics-v4-schema.md). Pre-v4 bodies trigger the literal pre-v4 short-circuit notice.

Purpose

Make frame port-coverage visible as observation, not enforcement. Three customer-framing principles from the issue #429 design intent shape every behavior in this skill:

1. Surface every gap, silently respect every N/A. Ports that the changeset triggers but does not credit show up as gaps in the ledger comment. Ports that legitimately do not apply stay silent — the operator is never asked to acknowledge a non-event.
2. Suggestions, not directives — warn means warn. The ledger renders a comment and exits. It never blocks gh pr create, never fails the conductor flow, and never asks the operator to "fix" anything before merging. Recommendations are recommendations.
3. Idempotent observation. Re-running the ledger on the same PR produces the same comment in place (find-or-upsert), so repeated invocations during a long-lived PR never spawn duplicate warnings.

This skill operationalizes the umbrella frame-architecture initiative tracked in #425 and the warn-only pre-PR hook tracked in #429.

Workflow

Code-Conductor invokes this skill as the final observation step after gh pr create succeeds in its post-creation flow. The skill's responsibilities are:

• Run the orchestrator script .github/scripts/frame-credit-ledger.ps1 once against the freshly-created PR number.
• Treat the orchestrator's output as advisory. A non-zero exit or stderr noise must not block the conductor's PR-handoff.
• Default to warn mode. Enforce mode is reserved for a later sub-issue and is not engaged here.
• Trust the orchestrator's idempotence. The script finds-or-upserts its own comment, so callers do not need to check for an existing ledger first.

The canonical invocation is:

pwsh ./.github/scripts/frame-credit-ledger.ps1 -Pr <N>

Per the #429 D-Ordering-1 judge disposition, this skill deliberately does not enumerate the orchestrator's parameter list, the fail-open trigger taxonomy, or any internal helper signatures. Those details live in the script and are the single source of truth. For parameter discovery and failure behavior, read the orchestrator's comment header or run it with -? for PowerShell's standard help surface; do not duplicate that surface here.

The conductor's only contract with this skill is:

• Invoke it after PR creation succeeds.
• Pass the new PR number.
• Do not branch on the result. The ledger either posts a comment, posts nothing (pre-v3 short-circuit), or fails open silently. None of those outcomes change the conductor flow.

Review Integrity Contract

Review and post-fix-review adapters declare their integrity contract in adapter frontmatter under integrity-contract:. The ledger consumes the current-tree declarations; historical PR-body back-derivation does not read legacy adapter frontmatter, so no pass-blocks compatibility shim is needed in the review credit builder.

The supported sibling keys are:

• pipeline-stages: — ordered stage names that the adapter runs, such as [prosecution, defense, judge].
• atomic: — true when the declared stages must run as one uninterrupted adversarial pipeline; n/a for single-stage or exempt adapters.
• prosecution-passes: — ordered prosecution pass IDs expected in the prosecution output, or an empty list for exempt adapters.
• exempt: — true when the adapter has no numbered prosecution pass output to verify.

Build-ReviewCreditRow emits the review credit integrity field as integrity-check.prosecution-passes. The standard adapter emits [1, 2, 3, 4, 5]; lite and post-fix emit [1]; exempt adapters emit an empty list with status: not-applicable.

Atomic Marker Hook

For applicable adapters declaring atomic: true, the ledger performs a warn-only marker check for the exact completion marker <!-- adversarial-pipeline-atomic-{ISSUE_ID} -->. The hook searches available PR body/comment text and, when the linked issue can be resolved, issue comments. It never blocks PR creation.

The hook records adversarial_pipeline_atomic_marker_present with one of these values:

• true — an applicable atomic adapter was detected and its completion marker was present.
• false-warn-only — an applicable atomic adapter was detected but the marker was absent; the ledger emits a warning and continues.
• not-applicable — no applicable atomic adapter was detected.

Related Guidance

• customer-experience/SKILL.md — CE Gate is a sibling concern. The ledger reports the credit status of any triggered ce-gate-* port; it never runs CE Gate. Execution stays with the customer-experience skill and the Experience-Owner agent.
• plugin-release-hygiene/SKILL.md — separate concern. Release-hygiene fires on plugin entry-point edits and proposes version bumps; the credit-ledger fires on PR creation regardless of whether entry-point files were touched. The two skills are co-resident, not overlapping.
• post-pr-review/SKILL.md — separate concern. Post-PR-review runs after merge for archival, documentation, and tagging; the credit-ledger runs before merge as a pre-PR observation pass.
• Documents/Design/frame-architecture.md — the Pre-PR Hook Contract section is the design reference for the ledger's behavior shape. The Adapter Model section governs why this skill is methodology and not a port-filling adapter.
• Issue #425 — frame-architecture umbrella that tracks the audit → declarations → enforcement arc.
• Issue #429 — the warn-only pre-PR hook that this skill describes.

Frame Ports Filled By This Skill

None — this skill is methodology, not a port-filling adapter. The credit-ledger orchestrator is the enforcement layer for the frame; no port is "filled" by enforcement itself. Per Documents/Design/frame-architecture.md Adapter Model, ports are filled by skills and agents whose terminal output becomes the credit for that port. The ledger reads those credits, it does not produce one.

Gotchas

• Cost telemetry is best-effort and always fail-open. If the cost libs fail to load (parse error, missing file) or if any step in the cost composition block throws, the orchestrator degrades gracefully: the ledger comment is posted without a Cost Pattern section. The cost pattern never gates or delays PR creation.

• Cost Pattern CI verification fires on more than the cost-reduction label. The presence-check workflow's if: condition (.github/workflows/cost-pattern-presence-check.yml) is the source of truth for exactly which PRs get a CI verification pass — read it directly rather than re-deriving the trigger set here, since it has drifted from a single-arm description before. As of this writing it has three arms: PRs carrying the cost-reduction label, any PR whose head branch starts with feature/issue-, and issue_comment events on PRs that carry the cost-reduction label. PRs matching none of these arms have no CI gate and may have no Cost Pattern section at all (the orchestrator still attempts composition, but there is no CI verification pass).

• Model key matching in the rate table is exact. The cost-rate-table.json keys must match the model string that appears in message.model in the JSONL transcript. If Claude introduces a new model variant (e.g., claude-sonnet-4-7) that is not yet in the rate table, cost for that model is set to null and null_cost_events increments. Update cost-rate-table.json and commit a new version entry when a new model is deployed.

• Transcript slug derivation preserves case and maps every non-alphanumeric character to a dash — but only after path-shape- and platform-specific normalization and a degenerate-input guard run first. The substitution phase (cwd.replace(/[^a-zA-Z0-9]/g, '-'), capped at 200 characters with a base-36 hash suffix appended beyond that) never collapses, trims, or lowercases — so C:\Users\Micah\Code 2\copilot-orchestra yields C--Users-Micah-Code-2-copilot-orchestra and a .claude\worktrees\ checkout yields ...-Orchestra--claude-worktrees-... (the dotted segment contributes its own dash on top of the separator's). But Get-CostTranscriptSlug is not that substitution alone: it first rejects a path with no ASCII alphanumeric character (returns ''), then normalizes MSYS/separator/trailing-separator path shapes to match what Claude Code's own would report — normalization that trim, on the reasoning that a normalized string is what should feed the (still trim-free) substitution. And the 200-character cap bounds the substituted prefix specifically; the appended suffix sits beyond it, not inside it. Issue #908 corrected the substitution rule itself from an earlier per-segment join that lowercased the drive and only substituted spaces, which derived a directory name that never existed for worktree checkouts. If the Claude projects directory uses a different slug format in practice, adjust the derivation in rather than trying to rename directories.

Platform-specific invocation

This skill's methodology is tool-agnostic. Platform-specific routing lives alongside:

• Copilot: platforms/copilot.md
• Claude Code: platforms/claude.md