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

## 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.

2. 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.

3. 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`

4. 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.
