Eve library

ISIS v2 WS16-003: Workflow Authoring Guide with Exhaustive Control/Consistency Examples

Guide

Revision 1

On this page

Scope#

WS16-003 publishes a deterministic workflow authoring guide that covers every workflow family in the taxonomy registry plus exhaustive control and consistency authoring examples.

Research and Existing Implementation Alignment#

Before implementation, existing canonical source registries and validators were reviewed to align guide generation with current ISIS source-of-truth contracts:

  • workflow taxonomy registry and validator:
    • libs/isis/workflows/src/metadata/workflow-taxonomy-registry.json
    • scripts/isis/validate-v2-workflow-taxonomy-registry.mjs
  • canonical control taxonomy and validator:
    • docs/domains/isis/remediation-v2/ISIS_V2_CONTROL_TAXONOMY.json
    • scripts/isis/validate-v2-control-taxonomy.mjs
  • canonical consistency taxonomy and validator:
    • docs/domains/isis/remediation-v2/ISIS_V2_CONSISTENCY_TAXONOMY.json
    • scripts/isis/validate-v2-consistency-taxonomy.mjs
  • deterministic generator/validator artifact pattern:
    • scripts/isis/generate-v2-api-docs-from-source-routes.mjs
    • scripts/isis/validate-v2-api-docs-from-source-routes.mjs

Deliverables#

  1. Added workflow authoring guide generator
  • scripts/isis/generate-v2-workflow-authoring-guide.mjs

Generator behavior:

  • derives workflow cards from canonical workflow taxonomy registry mappings;
  • derives exhaustive control catalog examples from control taxonomy entries;
  • derives exhaustive consistency catalog examples from consistency taxonomy entries;
  • resolves workflow input defaults directly from workflow JSON definitions;
  • emits canonical machine-readable and markdown guide artifacts.
  1. Added workflow authoring guide validator
  • scripts/isis/validate-v2-workflow-authoring-guide.mjs

Validator behavior:

  • recomputes guide payload from canonical registry/taxonomy/workflow sources;
  • verifies generated JSON and Markdown artifacts are current and deterministic;
  • fails on stale guide output or missing workflow JSON references.
  1. Published workflow authoring guide artifacts
  • docs/domains/isis/remediation-v2/ISIS_V2_WORKFLOW_AUTHORING_GUIDE.json
  • docs/domains/isis/remediation-v2/ISIS_V2_WORKFLOW_AUTHORING_GUIDE.md
  1. Added CI gate
  • .github/workflows/ci.yml

Added step:

  • node scripts/isis/validate-v2-workflow-authoring-guide.mjs

Verification Commands#

bash
node --check scripts/isis/generate-v2-workflow-authoring-guide.mjs
node --check scripts/isis/validate-v2-workflow-authoring-guide.mjs
node scripts/isis/generate-v2-workflow-authoring-guide.mjs
node scripts/isis/validate-v2-workflow-authoring-guide.mjs
node scripts/isis/reconcile-v2-doc-claims.mjs
node scripts/isis/validate-v2-doc-claims-reconciliation.mjs
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs

Verification Notes#

  • Current generated snapshot covers 48 workflow families, 27 control modes, and 8 consistency dimensions.
  • Control and consistency examples are source-derived, preventing manual drift between guide documentation and canonical taxonomy definitions.