pjsip-artifact-validation: 02 guide agents through scoped artifact validation

[alemar11]

pjsip-artifact-validation: 02 guide agents through scoped artifact validation

Execution Contract

Field	Value
source_spec_ref	alemar11/dotagents#20
feature_slug	pjsip-artifact-validation
affected_repositories	alemar11/pjsip-builder
allowed_paths	.agents/skills/pjsip-builder-validation/**, AGENTS.md, README.md
target_branch_name	codex/pjsip-artifact-validation
delivery_type	github-pr
dependency_ids	01

Goal

A Codex agent working in PJSIP Builder can recognize artifact-validation work, choose the smallest sufficient quick, affected-destination, or full validation tier, invoke the authoritative repository validator, diagnose failures without replacing its judgment, and report reproducible evidence; humans can discover the same command and policy without reading the skill.

Non-Goals

• Reimplement plist, archive, Mach-O, header, or symbol validation inside the skill.
• Put the authoritative validator under the hidden skill directory.
• Add another build wrapper, MCP server, plugin, hook, or CI workflow.
• Automatically run a clean debug/release matrix for every edit or every implicit skill activation.
• Fix cache, provenance, preflight, or transitive linker-metadata issues tracked separately in alemar11/pjsip-builder.
• Use ipatool for XCFramework validation or make direct vtool archive inspection a required path.

Context

Issue 01 delivers the stable validate_artifacts.py interface, structured findings, post-build enforcement, trackable .agents/skills/**, and deterministic unit/real-artifact proof. This issue depends on that interface because a skill that invents its own pass/fail rules would recreate the drift the feature is intended to remove.

Current Codex repository-skill discovery uses .agents/skills/<skill-name>/SKILL.md. AGENTS.md is loaded as durable repository guidance, while a skill provides a focused reusable workflow with optional references. Keep those surfaces complementary: AGENTS.md states when validation is required and names the canonical command; the skill owns tier selection, diagnostics, and reporting procedure.

A build may delete or replace _build/{debug|release}/PJSIP.xcframework. The skill must not inspect that path concurrently with a process that is producing it, and it must not turn a validation-only request into permission for a long or destructive rebuild.

Requirements

• Create .agents/skills/pjsip-builder-validation/SKILL.md with valid name and a concise, front-loaded description that matches PJSIP Builder XCFramework/static-archive validation, packaging/architecture/deployment-target/header/module/symbol/codec changes, and explicit requests to choose or run the repository's artifact checks. It must not claim general PJSIP source-test, IPA, app-signing, or arbitrary Xcode expertise.
• Keep the skill focused on one recognizable goal. Put the detailed change-to-tier matrix and diagnostic routing in .agents/skills/pjsip-builder-validation/references/validation-matrix.md; load that reference only when selecting scope or diagnosing a validator failure.
• Resolve the repository root and read the current Feature Spec/issue contract when invoked during implementation. Inspect the user request, relevant diff, selected build configuration/options, artifact existence, and any active build.py process before selecting a tier. Do not infer optional-codec state from headers alone when the caller or build invocation supplies it.
• Define quick as validation of an already complete, stable artifact with explicit expectations and no rebuild. Use it for validation-only requests, existing-artifact checks, documentation/skill changes, or follow-up diagnosis that does not invalidate build outputs.
• Define affected-destination as rebuilding only the selected or provably affected destination/configuration/features and then running the validator. Use it for destination-specific compiler/target flags, deployment values, arch lists, per-slice packaging, module/header changes, or codec merge behavior when a focused build can prove the change. State whether the chosen output path will be reused or isolated before launching the build.
• Define full as one all-destination debug and release proof plus the feature-required targeted optional-codec build. Select it only for explicit release/readiness requests or shared matrix/archive/XCFramework assembly changes whose correctness cannot be established by an affected-destination build. Reuse issue 01 evidence when it is current for the same final HEAD and invocation facts; do not spend the constrained build budget twice merely because this issue runs later.
• Treat validation and rebuilding as separate decisions. An existing artifact can be checked without rebuild; a requested rebuild must honor build.py's destructive behavior and the user's output scope. When another process or task is mutating the same artifact path, wait, choose a distinct output, or stop with the collision evidence instead of reading a partial package.
• Invoke top-level validate_artifacts.py as the normal pass/fail authority. Consume its JSON mode when available for structured reporting. Raw plutil, lipo, otool, ar, or nm calls are allowed only after failure and must be bounded to the failing slice, architecture, member, header, or symbol. Never override a nonzero validator result with an ad hoc successful sample.
• On every run, report the selected tier and reason, whether any rebuild occurred, artifact path/configuration/destinations/codec expectations, validator status, retained build log or JSON evidence, and exact blocked or skipped checks. Do not claim full validation after a quick or affected-destination run.
• Update AGENTS.md with a compact artifact-validation section: name the standalone human/CI command; require it after build-plan, architecture, target-flag, archive assembly, module/header, TLS, or optional-codec packaging changes; define when real rebuild evidence is required; warn against concurrent reads during package replacement; and preserve the boundaries with pjsip-builder#11 through #14.
• Update the root README with a concise human-facing validation section covering an existing debug/release artifact, explicit subset/codec expectations, JSON output, automatic post-build validation, and the fact that the Codex skill orchestrates scope but is not required to run the validator. Do not copy the complete skill matrix into README or AGENTS.md.
• Keep the skill portable and repository-relative. Do not embed developer-machine paths, current task IDs, transient artifact locations, a plugin manifest, or assumptions that only the Codex desktop app is available.

Implementation Plan

Plan-hardening: final stable $plan-harder issue-hardening pass completed for this issue.

This is the planning-time recommended approach. The implementing Codex task may replace it with a simpler or safer design when the accepted goal, scope, constraints and acceptance criteria remain unchanged.

1. Invoke $skill-creator for the repository skill scaffold and activation-language check, then keep the generated skill limited to artifact-validation orchestration.
2. Write SKILL.md as a short decision workflow: establish scope and artifact stability, load the matrix reference, select a tier, announce rebuild consequences when applicable, run the authoritative validator, perform bounded failure diagnosis, and report evidence.
3. Put exact change categories, tier definitions, build-budget reuse rules, collision handling, and diagnostic tool routing in references/validation-matrix.md. Avoid copying validator invariants that already belong to validate_artifacts.py.
4. Add a compact AGENTS.md policy that requires the canonical validator and appropriate rebuild evidence after relevant changes. Add README examples for humans and CI, including JSON output and automatic post-build behavior.
5. Test structural discovery and four activation cases in fresh repository sessions: explicit invocation, implicit artifact-validation request, incomplete/mutating artifact handling, and an unrelated PJSIP/Xcode request that must not trigger the workflow. Record the selected tier and ensure the validator remains authoritative.
6. Reuse the final-head real-build evidence from issue 01 when the HEAD and invocation facts are unchanged; otherwise rerun only the invalidated proof within the Feature Spec budget.

Acceptance Criteria

• Codex discovers pjsip-builder-validation from .agents/skills, and its metadata activates for direct and relevant implicit artifact-validation requests without claiming unrelated PJSIP, IPA, signing, or general Xcode work.
• The skill deterministically distinguishes quick, affected-destination, and full validation, states why the selected tier is sufficient, and never equates one tier's evidence with another.
• Validation-only requests do not trigger a rebuild, and any affected/full rebuild identifies its destination, configuration, codec flags, output path, destructive consequences, and artifact-collision check before execution.
• The skill uses validate_artifacts.py and its structured result as the normal authority; raw Apple tools are restricted to the exact failing scope and cannot convert a validator failure into success.
• Concurrent or incomplete artifact production is handled by waiting, selecting a distinct authorized output, or stopping with evidence rather than validating a partially replaced XCFramework.
• Every skill result reports tier, reason, rebuild status, artifact expectations, validator outcome, evidence locations, and any blocked or skipped checks without overstating coverage.
• AGENTS.md requires the canonical validation policy after relevant builder changes, includes the concurrency and adjacent-issue boundaries, and leaves detailed procedure in the skill.
• The root README documents direct human/CI validation, JSON output, selected expectations, and automatic post-build validation without requiring Codex or duplicating the tier matrix.
• Direct, implicit, incomplete/mutating-artifact, and unrelated-request trials pass at the final HEAD, and issue 01's real artifact evidence is reused only when its HEAD and invocation identity remain valid.

Validation

• Preferred: validate the skill directory and metadata with $skill-creator guidance, inspect that .agents/skills/pjsip-builder-validation/SKILL.md is tracked, and start a fresh Codex session from the repository root to confirm discovery.
• Preferred: run one direct $pjsip-builder-validation request, one implicit existing-artifact validation request, one incomplete or actively mutating artifact scenario, and one unrelated PJSIP/Xcode request. Verify activation, non-activation, selected tier, rebuild decision, and final report against the matrix.
• Preferred: run the documented README human and JSON commands against issue 01's final-head debug and release artifacts and confirm AGENTS.md points to the same interface.
• Preferred: run git diff --check and inspect the final diff for duplicated validator logic, absolute paths, transient task IDs, plugin scaffolding, or long procedure copied into AGENTS.md/README.
• Fallback: structural inspection can prove Markdown/schema/reference correctness, but there is no fallback for fresh-session discovery or the four required activation-boundary trials.
• Failure policy: run each fresh-session activation scenario once. Retry a scenario at most once after a deterministic metadata or instruction correction, retaining both prompts, selected skills, tier decisions, and outputs. A skill that remains undiscoverable, triggers on the unrelated case, rebuilds during validation-only input, reads a mutating artifact, or overrides validator failure blocks completion. Do not compensate with extra model retries or broaden the description until it activates indiscriminately.

Executor Update Contract

Before starting this issue, after any recovery or handoff, and before final verification, re-read the current Feature Spec and complete current issue set. Block declaratively on any change to the goal or Non-Goals, repositories or allowed paths, source_spec_ref, target_branch_name, delivery_type, dependencies, acceptance criterion text/count/order, safety constraints, or material validation constraints including attempt budgets and required terminal outcomes. Do not ask the user from the worker task merely to resolve that semantic drift.

The implementing Codex task may update acceptance checkbox markers, implementation approach and internal design, safer or simpler rewrites, additional or equivalent tests, compatible clarifications, progress, status, evidence, and concrete refactors or fixes within accepted scope. It updates this issue's checkboxes only after current-head proof, then re-reads the GitHub artifact before writing. It updates parent Feature Spec checkboxes only when Spec-level behavior is proven, and restores an unchecked marker whenever later evidence invalidates the proof. Root coordination never edits or judges individual acceptance criteria. Inside an ## Acceptance Criteria section, only checkbox markers are execution progress; criterion text, count, and order remain stable. This does not restrict updates to the other mutable execution sections named above.

Completion

After current-head evidence proves the issue criteria, the selected executor updates the issue checkboxes and tracker lifecycle truthfully. Completion may be represented by a closing reference or explicit close operation according to that executor's authorized delivery workflow.