Skip to content

Rename ValidateShapes step IRI to VerifyShapes (with Flexo + audit migration) #6

@mzargham

Description

@mzargham

Context

WP1 of the pipeline-cleanup roadmap
established a strict semantic split between verification
(automated, fully specified — SHACL, ROBOT/ELK, hash matching) and
validation (human judgement — engineer attestation, adequacy,
sufficiency). WP1's f09c2af
renamed the closure-rule path: traceability/validation.py
verification.py, validate()verify(), validate_*_completeness
verify_*_completeness, banner strings updated.

Intentionally NOT renamed in WP1: the p-plan step IRI fragment
<http://example.org/ontology/rtm#plan/step/ValidateShapes> in
pipeline/plan.ttl. The rdfs:label says
"Verify Closure-Rule Suite", but the IRI fragment still says
ValidateShapes. Same applies to
<http://example.org/ontology/rtm#plan/var/ValidationReport> (label
updated to "Verification Report"; IRI fragment preserved).

The runner function — run_stage_6_5_verify_closure — also emits
emit_stage_activity(state.ds, "ValidateShapes") using the
preserved fragment, so already-persisted <adcs:plan-execution> and
<adcs:audit> graphs continue to validate against the SHACL
PlanInstantiation shape that requires correspondsToStep to land on
a known step in plan.ttl.

This issue tracks the deferred IRI rename so the discipline mismatch
on the step fragment is visible.

Why deferred (recap)

  1. Renaming the IRI fragment invalidates every persisted
    <adcs:plan-execution> graph that references it, and every
    downstream <adcs:audit> graph that traces through it.
  2. WP4 (three-remote architecture) will land state on the Flexo
    remote that uses this IRI. Renaming locally without coordinating
    with the Flexo migration would create cross-remote drift.
  3. The rdfs:label is what humans see; the IRI is what tools dereference.
    Updating the label only is a strict improvement in human-facing
    discipline; the IRI rename is a coordination event, not a
    correctness fix.

When to do this

Sequence it inside or immediately after WP4 (three-remote
architecture). The Flexo migration scripts WP4 introduces should
include a one-shot rewrite of <...plan/step/ValidateShapes>
<...plan/step/VerifyShapes> and <...plan/var/ValidationReport>
<...plan/var/VerificationReport> applied uniformly across all
named graphs on the Flexo remote.

Acceptance criteria

  • Rename <plan/step/ValidateShapes><plan/step/VerifyShapes>
    in pipeline/plan.ttl.
  • Rename <plan/var/ValidationReport>
    <plan/var/VerificationReport> in the same file.
  • Update STEP_NAMES in
    traceability/plan_execution.py
    to drop "ValidateShapes" and add "VerifyShapes".
  • Update PipelineState.activity_to_stage in
    pipeline/state.py and
    ACTIVITY_TO_STAGE in
    interrogate/rerun.py — both currently
    key on "ValidateShapes".
  • Update run_stage_6_5_verify_closure in
    pipeline/runner.py to emit
    "VerifyShapes".
  • Update traceability/audit.py if it references the old fragment
    string.
  • Update all <adcs:plan-execution> test fixtures and TriG
    snapshots; SHACL PlanInstantiation shape must still pass.
  • Provide a one-shot Flexo migration script (or document the
    manual steps) that rewrites the IRI uniformly across persisted
    branches; coordinate the cutover with the next pipeline run.
  • Bump roadmap discipline checklist to confirm zero remaining
    Validate* hits on the closure-rule path
    (grep -rn "Validate" pipeline/plan.ttl pipeline/runner.py pipeline/state.py interrogate/rerun.py traceability/ returns empty).
  • Confirm interrogate.rerun and the Stage 6.5 banner still work
    against a freshly migrated dataset.

References

  • WP1 subplan §10 "Known follow-ups" entry that promised this issue:
    /Users/z/.claude/plans/wp1-pipeline-cleanup-and-rerun.md
  • WP1 §4.4 rename pass commit: f09c2af
  • Related: WP4 three-remote architecture work package (pre-deferred Typer
    aggregator #5
    is a comparable WP4-dependent follow-up).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions