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.jsonscripts/isis/validate-v2-workflow-taxonomy-registry.mjs
- canonical control taxonomy and validator:
docs/domains/isis/remediation-v2/ISIS_V2_CONTROL_TAXONOMY.jsonscripts/isis/validate-v2-control-taxonomy.mjs
- canonical consistency taxonomy and validator:
docs/domains/isis/remediation-v2/ISIS_V2_CONSISTENCY_TAXONOMY.jsonscripts/isis/validate-v2-consistency-taxonomy.mjs
- deterministic generator/validator artifact pattern:
scripts/isis/generate-v2-api-docs-from-source-routes.mjsscripts/isis/validate-v2-api-docs-from-source-routes.mjs
Deliverables#
- 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.
- 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.
- Published workflow authoring guide artifacts
docs/domains/isis/remediation-v2/ISIS_V2_WORKFLOW_AUTHORING_GUIDE.jsondocs/domains/isis/remediation-v2/ISIS_V2_WORKFLOW_AUTHORING_GUIDE.md
- 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
48workflow families,27control modes, and8consistency dimensions. - Control and consistency examples are source-derived, preventing manual drift between guide documentation and canonical taxonomy definitions.