@workflow-cannon/workspace-kit 0.17.0 → 0.24.0

package/src/modules/documentation/schemas/documentation-schema.md

@@ -1,54 +1,37 @@
-meta|v=1|doc=<manifest|rules|runbook|workbook|map|workflows|commands|decisions|glossary|observed|planned|checks>|truth=<canonical|observed|planned>|st=<active|deprecated|draft>
-
-syntax|rec=one_per_line|sep=||kv==|list=,|seq=>|all=+|bool=true,false
-ids|rule=R[0-9]{3,}|wf=W[0-9]{3,}|cmd=C[0-9]{3,}|decision=D[0-9]{3,}|observed=O[0-9]{3,}|planned=P[0-9]{3,}|check=K[0-9]{3,}
-sem|lvl=must,must_not,should,may|risk=low,medium,high,critical|ap=none,prompt,required|act=auto,warn,prompt,stop
-author|meta_first_once=true|one_fact_per_record=true|exceptions_inline=true|no_vague_directives=true|observed_ne_rule=true|planned_ne_rule=true|stable_order=true
-
-project|name=<name>|type=<type>|scope=<scope>
-stack|<key=value>...
-prio|<p1>><p2>><p3>...
-truth|order=<t1>><t2>><t3>><t4>
-ref|name=<name>|path=<path>
-
-rule|<RID>|<lvl>|<scope>|<directive>|unless=<cond>|also=<list>|risk=<risk>|ap=<ap>|ov=<act>|st=<st>|refs=<list>
-path|<path>|role=<role>|has=<list>|xhas=<list>|deps=<list>|xdeps=<list>|check=<list>|st=<st>|refs=<list>
-module|<name>|role=<role>|owns=<list>|deps=<list>|xdeps=<list>|entry=<list>|tests=<list>|st=<st>|refs=<list>
-
-runbook|<name>|<scope>|<owner>
-workbook|<name>|<phase>|<status>
-intent|<fact_or_guidance>
-chain|<step>|<command>|expect_exit=<code>
-artifact|path=<path>|schema=<schema_path>
-state|name=<name>|dist_tag=<tag>|intent=<intent>
-transition|from=<from>|to=<to>|requires=<list>
-promotion|from=<from>|to=<to>|requires=<list>
-rollback|strategy=<strategy>|note=<note>
-command|name=<name>|purpose=<purpose>|sensitivity=<non_sensitive|policy_sensitive>
-config|key=<key>|default=<value>
-cadence|rule=<rule>
-guardrail|<GID>|<lvl>|<directive>|st=<st>
-
-wf|<WID>|name=<name>|when=<trigger>|do=<s1>><s2>><s3>|done=<d1>+<d2>|forbid=<list>|ask_if=<cond>|halt_if=<cond>|ap=<ap>|risk=<risk>|st=<st>|refs=<list>
-cmd|<CID>|name=<name>|use=<command>|scope=<scope>|expect=<result>|risk=<risk>|st=<st>
-decision|<DID>|topic=<topic>|choice=<choice>|why=<reason>|then=<consequence>|st=<st>|refs=<list>
-term|<name>|def=<definition>|st=<st>
-
-observed|<OID>|scope=<scope>|fact=<fact>|evidence=<evidence>|risk=<risk>|st=observed|refs=<list>
-planned|<PID>|scope=<scope>|target=<target>|why=<reason>|st=planned|refs=<list>
-check|<KID>|scope=<scope>|assert=<assertion>|when=<cond>|on_fail=<act>|st=<st>|refs=<list>
-
-order|manifest=meta,project,stack,prio,truth,ref
-order|rules=global,risky,scoped,workflow,style
-order|map=roots,major,special,legacy
-order|workflows=common,risky,edge,clarify
-
-defaults|omit_optional=true|omit_empty=true|lvl_explicit=true|scope_explicit=true|directive_explicit=true
-stop|critical_secret_risk=true|destructive_unapproved=true|policy_conflict_unresolved=true
-prompt|multi_valid_interpretations=true|required_approval_missing=true
-warn|should_violation=true|low_risk_uncertainty=true
-
-directive|good=add_migration,preserve_backward_compatibility,contain_business_logic,commit_secrets,manual_edit
-directive|bad=best_practices,clean_code,good_design,keep_it_simple,do_the_right_thing
-scope|good=repo,src/api,src/domain,public_api,schema_changes,behavior_change
-scope|bad=general,misc,various,important_stuff
+meta|schema=base.v2|doc=<manifest|rules|runbook|workbook|map|workflows|commands|decisions|glossary|observed|planned|checks>|truth=<canonical|observed|planned>|status=<active|deprecated|draft>|profile=<core|runbook|workbook>
+
+syntax|record=one_per_line|separator=||assignment==|list=,|sequence=>|conjunction=+|bool=true,false
+ids|rule=R[0-9]{3,}|workflow=W[0-9]{3,}|command=C[0-9]{3,}|decision=D[0-9]{3,}|observed=O[0-9]{3,}|planned=P[0-9]{3,}|check=K[0-9]{3,}|example=E[0-9]{3,}|guardrail=G[0-9]{3,}
+semantics|level=<must|must_not|should|may>|risk=<low|medium|high|critical>|approval=<none|prompt|required>|override=<auto|warn|prompt|stop>|refType=<adr|file|code|doc|issue|pr|test|external>
+authoring|metaFirstOnce=true|oneFactPerRecord=true|exceptionsInline=true|noVagueDirectives=true|stableOrder=true
+
+record|type=meta|required=schema,doc,truth,status|optional=profile,title,owner,tags,refs
+record|type=ref|required=id,type,target|optional=label,note,status
+record|type=rule|required=id,level,scope,directive,why|optional=unless,also,risk,approval,override,status,refs
+record|type=check|required=id,scope,assertion|optional=when,onFail,status,refs
+record|type=decision|required=id,topic,choice,why|optional=consequence,status,refs
+record|type=example|required=id,for,kind,text|optional=status,refs
+record|type=term|required=name,definition|optional=status,refs
+record|type=command|required=id,name,use,scope,expectation|optional=risk,sensitivity,status,refs
+record|type=workflow|required=id,name,when,steps,done|optional=forbid,askIf,haltIf,approval,risk,status,refs
+
+record|type=runbook|required=name,scope,owner|optional=status,refs
+record|type=workbook|required=name,phase,state|optional=status,refs
+record|type=chain|required=step,command,expectExit|optional=status,refs
+record|type=state|required=name,distTag,intent|optional=status,refs
+record|type=transition|required=from,to,requires|optional=status,refs
+record|type=promotion|required=from,to,requires|optional=status,refs
+record|type=rollback|required=strategy,note|optional=status,refs
+record|type=artifact|required=path,schema|optional=status,refs
+record|type=config|required=key,default|optional=status,refs
+record|type=cadence|required=rule|optional=status,refs
+record|type=guardrail|required=id,level,directive,why|optional=status,refs
+
+profile|name=core|requiredRecords=meta,ref,rule,check,decision,example,term,command,workflow
+profile|name=runbook|requiredRecords=meta,ref,rule,check,decision,example,term,command,workflow,runbook,chain,artifact,state,transition,promotion,rollback,config,cadence,guardrail
+profile|name=workbook|requiredRecords=meta,ref,rule,check,decision,example,term,command,workflow,workbook,state,transition,artifact,guardrail
+
+defaults|omitOptional=true|omitEmpty=true|requiredFieldsExplicit=true
+stop|criticalSecretRisk=true|destructiveUnapproved=true|policyConflictUnresolved=true
+prompt|multiValidInterpretations=true|requiredApprovalMissing=true
+warn|shouldViolation=true|lowRiskUncertainty=true

package/src/modules/documentation/types.ts

@@ -49,3 +49,231 @@ export type DocumentationBatchResult = {
     timestamp: string;
   };
 };
+
+export type NormalizedRecordStatus = "active" | "deprecated" | "draft" | "observed" | "planned";
+
+export type NormalizedBaseRecord = {
+  id?: string;
+  status?: NormalizedRecordStatus;
+  refs?: string[];
+};
+
+export type NormalizedMeta = NormalizedBaseRecord & {
+  schema: "base.v2";
+  doc: string;
+  truth: "canonical" | "observed" | "planned";
+  profile?: "core" | "runbook" | "workbook";
+  title?: string;
+  owner?: string;
+  tags?: string[];
+};
+
+export type NormalizedRef = NormalizedBaseRecord & {
+  id: string;
+  type: "adr" | "file" | "code" | "doc" | "issue" | "pr" | "test" | "external";
+  target: string;
+  anchor?: string;
+  label?: string;
+  note?: string;
+};
+
+export type NormalizedRule = NormalizedBaseRecord & {
+  id: string;
+  level: "must" | "must_not" | "should" | "may";
+  scope: string;
+  scope_kind?: string;
+  kind?: string;
+  directive: string;
+  why: string;
+  unless?: string;
+  also?: string[];
+  risk?: "low" | "medium" | "high" | "critical";
+  approval?: "none" | "prompt" | "required";
+  override?: "auto" | "warn" | "prompt" | "stop";
+};
+
+export type NormalizedCheck = NormalizedBaseRecord & {
+  id: string;
+  scope: string;
+  assertion: string;
+  when?: string;
+  onFail?: "auto" | "warn" | "prompt" | "stop";
+};
+
+export type NormalizedDecision = NormalizedBaseRecord & {
+  id: string;
+  topic: string;
+  choice: string;
+  why: string;
+  consequence?: string;
+};
+
+export type NormalizedExample = NormalizedBaseRecord & {
+  id: string;
+  for: string;
+  kind: "good" | "bad" | "edge";
+  text: string;
+};
+
+export type NormalizedTerm = NormalizedBaseRecord & {
+  name: string;
+  definition: string;
+};
+
+export type NormalizedCommand = NormalizedBaseRecord & {
+  id: string;
+  name: string;
+  use: string;
+  scope: string;
+  expectation: string;
+  risk?: "low" | "medium" | "high" | "critical";
+  sensitivity?: "non_sensitive" | "policy_sensitive";
+};
+
+export type NormalizedWorkflow = NormalizedBaseRecord & {
+  id: string;
+  name: string;
+  when: string;
+  steps: string[];
+  done: string[];
+  forbid?: string[];
+  askIf?: string;
+  haltIf?: string;
+  approval?: "none" | "prompt" | "required";
+  risk?: "low" | "medium" | "high" | "critical";
+};
+
+export type NormalizedRunbook = NormalizedBaseRecord & {
+  name: string;
+  scope: string;
+  owner: string;
+};
+
+export type NormalizedWorkbook = NormalizedBaseRecord & {
+  name: string;
+  phase: string;
+  state: string;
+};
+
+export type NormalizedChain = NormalizedBaseRecord & {
+  step: string;
+  command: string;
+  expectExit: number;
+};
+
+export type NormalizedState = NormalizedBaseRecord & {
+  name: string;
+  distTag: string;
+  intent: string;
+};
+
+export type NormalizedTransition = NormalizedBaseRecord & {
+  from: string;
+  to: string;
+  requires: string[];
+};
+
+export type NormalizedPromotion = NormalizedBaseRecord & {
+  from: string;
+  to: string;
+  requires: string[];
+};
+
+export type NormalizedRollback = NormalizedBaseRecord & {
+  strategy: string;
+  note: string;
+};
+
+export type NormalizedArtifact = NormalizedBaseRecord & {
+  path: string;
+  schema: string;
+};
+
+export type NormalizedConfig = NormalizedBaseRecord & {
+  key: string;
+  default: string;
+};
+
+export type NormalizedCadence = NormalizedBaseRecord & {
+  rule: string;
+};
+
+export type NormalizedGuardrail = NormalizedBaseRecord & {
+  id: string;
+  level: "must" | "must_not" | "should" | "may";
+  directive: string;
+  why: string;
+};
+
+export type NormalizedDocument = {
+  meta: NormalizedMeta | null;
+  refs: NormalizedRef[];
+  rules: NormalizedRule[];
+  checks: NormalizedCheck[];
+  decisions: NormalizedDecision[];
+  examples: NormalizedExample[];
+  terms: NormalizedTerm[];
+  commands: NormalizedCommand[];
+  workflows: NormalizedWorkflow[];
+  runbooks: NormalizedRunbook[];
+  workbooks: NormalizedWorkbook[];
+  chains: NormalizedChain[];
+  states: NormalizedState[];
+  transitions: NormalizedTransition[];
+  promotions: NormalizedPromotion[];
+  rollbacks: NormalizedRollback[];
+  artifacts: NormalizedArtifact[];
+  configs: NormalizedConfig[];
+  cadences: NormalizedCadence[];
+  guardrails: NormalizedGuardrail[];
+  refsById: Map<string, NormalizedRef>;
+  examplesByParent: Map<string, NormalizedExample[]>;
+  profileRecords: Map<"core" | "runbook" | "workbook", Array<NormalizedBaseRecord>>;
+};
+
+export type ViewModelSection = {
+  id: string;
+  title?: string;
+  description?: string;
+  renderer: string;
+  source:
+    | "meta"
+    | "refs"
+    | "rules"
+    | "checks"
+    | "decisions"
+    | "examples"
+    | "terms"
+    | "commands"
+    | "workflows"
+    | "runbooks"
+    | "workbooks"
+    | "chains"
+    | "states"
+    | "transitions"
+    | "promotions"
+    | "rollbacks"
+    | "artifacts"
+    | "configs"
+    | "cadences"
+    | "guardrails";
+  where?: Record<string, string | number | boolean>;
+  sortBy?: string[];
+  template?: string;
+};
+
+export type ViewRenderPolicy = {
+  id: string;
+  mode: "append" | "replace" | "fallback";
+  when?: string;
+};
+
+export type ViewModelDefinition = {
+  id: string;
+  version: number;
+  docType: string;
+  target: string;
+  profile?: "core" | "runbook" | "workbook";
+  sections: ViewModelSection[];
+  renderPolicies?: ViewRenderPolicy[];
+};

package/src/modules/documentation/validator.ts

@@ -0,0 +1,247 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { DocumentationValidationIssue } from "./types.js";
+import { parseAiDocument } from "./parser.js";
+
+export type AiValidationContext = {
+  strict: boolean;
+  workspacePath: string;
+  expectedDoc?: "rules" | "runbook" | "workbook";
+};
+
+const REF_TYPES = new Set(["adr", "file", "code", "doc", "issue", "pr", "test", "external"]);
+
+const REQUIRED_BY_PROFILE: Record<string, string[]> = {
+  core: ["meta", "ref", "rule", "check", "decision", "example", "term", "command", "workflow"],
+  runbook: [
+    "meta",
+    "ref",
+    "rule",
+    "check",
+    "decision",
+    "example",
+    "term",
+    "command",
+    "workflow",
+    "runbook",
+    "chain",
+    "artifact",
+    "state",
+    "transition",
+    "promotion",
+    "rollback",
+    "config",
+    "cadence",
+    "guardrail"
+  ],
+  workbook: [
+    "meta",
+    "ref",
+    "rule",
+    "check",
+    "decision",
+    "example",
+    "term",
+    "command",
+    "workflow",
+    "workbook",
+    "state",
+    "transition",
+    "artifact",
+    "guardrail"
+  ]
+};
+
+function isAllowedMetaDoc(doc: string): boolean {
+  return (
+    doc === "rules" ||
+    doc === "runbook" ||
+    doc === "workbook" ||
+    doc === "generator" ||
+    doc === "map" ||
+    doc === "workflows" ||
+    doc === "commands" ||
+    doc === "decisions" ||
+    doc === "glossary" ||
+    doc === "observed" ||
+    doc === "planned" ||
+    doc === "checks" ||
+    doc === "manifest"
+  );
+}
+
+function profileForDoc(doc: string | undefined, explicitProfile: string | undefined): "core" | "runbook" | "workbook" {
+  if (explicitProfile === "core" || explicitProfile === "runbook" || explicitProfile === "workbook") {
+    return explicitProfile;
+  }
+  if (doc === "runbook") return "runbook";
+  if (doc === "workbook") return "workbook";
+  return "core";
+}
+
+export function validateAiSchema(aiOutput: string, ctx: AiValidationContext): DocumentationValidationIssue[] {
+  const issues: DocumentationValidationIssue[] = [];
+  const records = parseAiDocument(aiOutput);
+  if (records.length === 0) {
+    return [{ check: "schema", message: "AI output is empty", resolved: false }];
+  }
+
+  const meta = records[0];
+  if (!meta || meta.type !== "meta") {
+    return [{ check: "schema", message: "AI output must start with a meta record", resolved: false }];
+  }
+
+  const schema = meta.kv["schema"];
+  const doc = meta.kv["doc"];
+  const truth = meta.kv["truth"];
+  const status = meta.kv["status"] ?? meta.kv["st"];
+  const profile = profileForDoc(doc, meta.kv["profile"]);
+  const isLegacySchema = schema !== "base.v2";
+  if (schema !== "base.v2") {
+    issues.push({
+      check: "schema",
+      message: `AI meta.schema must be 'base.v2' (found '${schema ?? ""}')`,
+      resolved: true
+    });
+  }
+  if (!doc || !isAllowedMetaDoc(doc)) {
+    issues.push({ check: "schema", message: `Unsupported meta.doc '${doc ?? ""}'`, resolved: false });
+  }
+  if (!truth) issues.push({ check: "schema", message: "AI meta.truth is required", resolved: false });
+  if (!status) issues.push({ check: "schema", message: "AI meta.status is required", resolved: false });
+  if (ctx.expectedDoc && doc && ctx.expectedDoc !== doc) {
+    issues.push({
+      check: "schema",
+      message: `meta.doc '${doc}' does not match expected doc family for '${ctx.expectedDoc}'`,
+      resolved: !ctx.strict
+    });
+  }
+
+  const presentByType: Record<string, boolean> = { meta: true };
+  const knownIds = new Set<string>();
+  for (const rec of records.slice(1)) {
+    presentByType[rec.type] = true;
+    const id = rec.kv["id"];
+    if (id) knownIds.add(id);
+    if (rec.kv["name"]) knownIds.add(rec.kv["name"]);
+  }
+
+  for (const rec of records.slice(1)) {
+    if (rec.type === "rule" && !rec.kv["why"]) {
+      issues.push({
+        check: "schema",
+        message: "rule records require why",
+        resolved: isLegacySchema || !ctx.strict
+      });
+    }
+
+    if (rec.type === "ref") {
+      const type = rec.kv["type"];
+      const target = rec.kv["target"] ?? rec.kv["path"];
+      const legacyPath = rec.kv["path"];
+      if (!rec.kv["id"] || !type || !target) {
+        issues.push({
+          check: "schema",
+          message: "ref records require id, type, target",
+          resolved: isLegacySchema || !ctx.strict
+        });
+        if (legacyPath && !existsSync(resolve(ctx.workspacePath, legacyPath))) {
+          issues.push({
+            check: "schema",
+            message: `ref.path does not exist: '${legacyPath}'`,
+            resolved: !ctx.strict
+          });
+        }
+      } else if (!REF_TYPES.has(type)) {
+        issues.push({
+          check: "schema",
+          message: `ref.type '${type}' must be one of ${[...REF_TYPES].join(", ")}`,
+          resolved: isLegacySchema || !ctx.strict
+        });
+      } else if ((type === "file" || type === "code" || type === "doc") && !existsSync(resolve(ctx.workspacePath, target))) {
+        issues.push({
+          check: "schema",
+          message: `ref.target does not exist: '${target}'`,
+          resolved: !ctx.strict
+        });
+      }
+    }
+
+    if (rec.type === "example") {
+      const parent = rec.kv["for"];
+      const kind = rec.kv["kind"];
+      if (!parent || !knownIds.has(parent)) {
+        issues.push({
+          check: "schema",
+          message: `example.for must reference an existing record id/name (found '${parent ?? ""}')`,
+          resolved: isLegacySchema || !ctx.strict
+        });
+      }
+      if (!kind || !["good", "bad", "edge"].includes(kind)) {
+        issues.push({
+          check: "schema",
+          message: "example.kind must be one of good|bad|edge",
+          resolved: isLegacySchema || !ctx.strict
+        });
+      }
+    }
+  }
+
+  const isActive = status === "active";
+  if (isActive) {
+    // Preserve strict runbook/workbook/rules baseline behavior during v2 migration.
+    if (doc === "runbook" && !presentByType["rule"] && !presentByType["chain"]) {
+      issues.push({
+        check: "schema",
+        message: "Missing required AI records for doc family 'runbook': at least one rule| or chain| record",
+        resolved: !ctx.strict
+      });
+    }
+    if (doc === "workbook" && !presentByType["command"]) {
+      issues.push({
+        check: "schema",
+        message: "Missing required AI records for doc family 'workbook': at least one command| record",
+        resolved: !ctx.strict
+      });
+    }
+    if (doc === "workbook" && !presentByType["config"]) {
+      issues.push({
+        check: "schema",
+        message: "Missing required AI records for doc family 'workbook': at least one config| record",
+        resolved: !ctx.strict
+      });
+    }
+    if (doc === "rules" && !presentByType["rule"] && !presentByType["check"]) {
+      issues.push({
+        check: "schema",
+        message: "Missing required AI records for doc family 'rules': at least one rule| or check| record",
+        resolved: !ctx.strict
+      });
+    }
+
+    const missing = REQUIRED_BY_PROFILE[profile]
+      .filter((type) => {
+        if (type === "workflow") return !presentByType["workflow"] && !presentByType["wf"];
+        if (type === "command") return !presentByType["command"] && !presentByType["cmd"];
+        if (type === "example") return !presentByType["example"];
+        return !presentByType[type];
+      })
+      .map((t) => `${t}| record`);
+    if (missing.length > 0) {
+      issues.push({
+        check: "schema",
+        message: `Missing required AI records for profile '${profile}': ${missing.join(", ")}`,
+        resolved: isLegacySchema || !ctx.strict
+      });
+    }
+  }
+
+  return issues;
+}
+
+export function autoResolveAiSchema(aiOutput: string): string {
+  if (aiOutput.startsWith("meta|schema=") || aiOutput.startsWith("meta|v=")) {
+    return aiOutput;
+  }
+  return `meta|schema=base.v2|doc=rules|truth=canonical|status=draft|profile=core\n\n${aiOutput}`;
+}