{"record":{"id":"d6685a9e31156275","repo":"ruvnet/ruflo","slug":"root-guidance-file-not-found-this-config-rootgu","errorCode":null,"errorMessage":"Root guidance file not found: ${this.config.rootGuidancePath}","messagePattern":"Root guidance file not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"v3/@claude-flow/guidance/src/index.ts","lineNumber":502,"sourceCode":"  /**\n   * Initialize the control plane\n   *\n   * 1. Read and compile guidance files\n   * 2. Load shards into retriever\n   * 3. Configure gates\n   * 4. Set up headless runner if enabled\n   */\n  async initialize(): Promise<void> {\n    if (this.initialized) return;\n\n    // Step 1: Read guidance files\n    const rootContent = await this.readGuidanceFile(this.config.rootGuidancePath);\n    const localContent = this.config.localGuidancePath\n      ? await this.readGuidanceFile(this.config.localGuidancePath)\n      : undefined;\n\n    if (!rootContent) {\n      throw new Error(`Root guidance file not found: ${this.config.rootGuidancePath}`);\n    }\n\n    // Step 2: Compile\n    this.bundle = this.compiler.compile(rootContent, localContent ?? undefined);\n\n    // Step 3: Load into retriever\n    await this.retriever.loadBundle(this.bundle);\n\n    // Step 4: Set active rules on gates\n    const allRules = [\n      ...this.bundle.constitution.rules,\n      ...this.bundle.shards.map(s => s.rule),\n    ];\n    this.gates.setActiveRules(allRules);\n\n    // Step 5: Set up headless runner if enabled\n    if (this.config.headlessMode) {\n      this.headless = createHeadlessRunner(undefined, this.ledger, this.bundle.constitution.hash);","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/index.ts#L484-L520","documentation":"GuidanceControlPlane.initialize() step 1 reads the root guidance file (default './CLAUDE.md', overridable via config.rootGuidancePath) through readGuidanceFile, which returns null both when the file is missing and when reading it throws (the catch swallows read errors). A null root content makes initialize() throw this error; the local guidance file ('./CLAUDE.local.md') is optional, only the root file is mandatory. Initialization aborts before compiling any policy bundle.","triggerScenarios":"Running in a working directory without CLAUDE.md while keeping the default config; passing a rootGuidancePath that does not exist; a relative path resolved against an unexpected process.cwd() (daemon, container WORKDIR, systemd unit); a file that exists but is unreadable due to permissions.","commonSituations":"CLI invoked from a subdirectory of the repo; apps packaged without shipping their guidance markdown files; container or service units with a different cwd than local development; permission-restricted mounted volumes.","solutions":["Create the guidance file at the path being resolved (default ./CLAUDE.md relative to process.cwd())","Pass an absolute rootGuidancePath in createGuidanceControlPlane config so cwd cannot change resolution","Verify with fs.existsSync AND a readability check (fs.accessSync(path, fs.constants.R_OK)) beforehand, since read errors are swallowed and also surface as 'not found'","Log process.cwd() at startup to catch wrong-working-directory deploys"],"exampleFix":"// before\nconst plane = createGuidanceControlPlane(); // default './CLAUDE.md'\nawait plane.initialize();\n// after\nimport { existsSync, accessSync, constants } from 'node:fs';\nimport { resolve } from 'node:path';\nconst root = resolve(process.cwd(), 'CLAUDE.md'); // or an absolute config path\nif (!existsSync(root)) throw new Error(`Missing guidance file: ${root}`);\naccessSync(root, constants.R_OK);\nconst plane = createGuidanceControlPlane({ rootGuidancePath: root });\nawait plane.initialize();","handlingStrategy":"validation","validationCode":"import { existsSync, accessSync, constants } from 'node:fs';\nimport { resolve } from 'node:path';\n\nconst rootPath = resolve(process.cwd(), config.rootGuidancePath ?? './CLAUDE.md');\nif (!existsSync(rootPath)) {\n  throw new Error(`Guidance file missing at ${rootPath} (cwd: ${process.cwd()})`);\n}\naccessSync(rootPath, constants.R_OK); // readGuidanceFile swallows read errors as null\nawait plane.initialize();","typeGuard":null,"tryCatchPattern":"try {\n  await plane.initialize();\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Root guidance file not found')) {\n    // check cwd and ship the guidance file before retrying; do not create an empty file blindly\n    throw new Error(`Initialize failed: ${err.message}; running from ${process.cwd()}`);\n  }\n  throw err;\n}","preventionTips":["Pass an absolute rootGuidancePath so process.cwd() cannot change resolution","Ship guidance markdown files as part of the deployable artifact and verify in CI","Remember an unreadable (permissions) file fails identically to a missing one"],"tags":["guidance","control-plane","initialization","missing-file","configuration"],"backgroundTag":"missing-config-file","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}