{"record":{"id":"cb0bb4acb18d2bb5","repo":"coleam00/Archon","slug":"warning-workflowname-declares-keys-the-engin","errorCode":null,"errorMessage":"Warning: '${workflowName}' declares keys the engine ignores:","messagePattern":"Warning: '(.+?)' declares keys the engine ignores:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/cli/src/commands/workflow.ts","lineNumber":1060,"sourceCode":"    throw new Error(\n      `Error loading workflows: ${err.message}\\nHint: Check permissions on .archon/workflows/ directory.`\n    );\n  }\n}\n\n/**\n * Print a workflow's parse warnings (keys the engine silently drops) to stderr.\n *\n * stderr rather than stdout so `--json` callers keep a parseable payload while\n * still being told; `console.warn` rather than the logger because `--json` sets\n * the log level to silent, which is exactly the case this has to survive.\n */\nexport function emitParseWarnings(\n  parseWarnings: readonly string[] | undefined,\n  workflowName: string\n): void {\n  if (!parseWarnings || parseWarnings.length === 0) return;\n  console.warn(`Warning: '${workflowName}' declares keys the engine ignores:`);\n  for (const warning of parseWarnings) {\n    console.warn(`  - ${warning}`);\n  }\n}\n\n/**\n * Print a deprecated workflow's removal notice (#2781) to stderr.\n *\n * Same channel as emitParseWarnings: stderr keeps `--json` stdout parseable,\n * and `console.warn` survives `--json`'s log silencing. Not gated on --quiet —\n * a user driving runs programmatically still has to learn the default they\n * picked is scheduled for removal.\n */\nexport function emitDeprecationNotice(workflow: WorkflowDefinition): void {\n  const notice = formatDeprecationNotice(workflow);\n  if (notice) console.warn(notice);\n}\n","sourceCodeStart":1042,"sourceCodeEnd":1078,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/workflow.ts#L1042-L1078","documentation":"Header warning from `emitParseWarnings` in packages/cli/src/commands/workflow.ts. When a workflow YAML definition contains keys the engine does not recognize (per the workflow-language constitution: YAML exposes only governable surface), the parser collects the ignored keys and the CLI prints this header followed by one line per key. The run proceeds; the extra keys are silently dropped from the engine's perspective.","triggerScenarios":"Running any workflow command whose definition (bundled, project `.archon/workflows/`, or global `~/.archon/workflows/`) parsed with non-empty `parseWarnings` — i.e. the YAML has unknown top-level or node keys.","commonSituations":"Hand-edited workflow YAML with typo'd keys (e.g. `retries:` instead of `retry:`); copying keys from an older or newer Archon version; following outdated documentation or AI-generated YAML with invented fields.","solutions":["Read the indented lines under the header — each names an ignored key and its location.","Remove the unknown keys from the workflow YAML, or replace them with the engine-supported equivalents.","Check `.archon/workflow-language-constitution.md` and the authoring guide for the valid YAML surface.","Validate the workflow file against the current workflow schema before running."],"exampleFix":"// before (workflow.yaml)\nretries: 3\nsteps: []\n// after\nretry:\n  max: 3\nsteps: []","handlingStrategy":"validation","validationCode":"// Validate workflow YAML against the schema before running\nimport { parseWorkflowDefinition } from '@archon/workflows';\nconst { warnings } = parseWorkflowDefinition(yamlText);\nif (warnings.length) throw new Error(`ignored keys: ${warnings.join(', ')}`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Lint workflow YAML against the current workflow schema in CI.","Copy keys only from the current authoring guide, not older docs or AI output.","Treat any 'keys the engine ignores' warning as a bug in your workflow file."],"tags":["cli","workflow-yaml","schema","unknown-keys"],"backgroundTag":"unknown-config-key","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}