affaan-m/ECC · error · Error

Missing provenance metadata for

Error message

Missing provenance metadata for ${skillDir}

What it means

readProvenance reads the provenance metadata file for a skill directory. If the file does not exist, it returns null when provenance is optional, but throws when provenance is required — either because the caller passed { required: true } or because requiresProvenance() determined the skill directory must carry provenance metadata.

Solutions

1. Generate/restore the provenance metadata file for the skill (use the library's provenance tooling or writeProvenance with a valid record).
2. If provenance is genuinely optional for this skill, call readProvenance(dir) without required: true and handle the null return.
3. Verify skillPath resolves to the intended skill directory; fix the path if it points elsewhere.
4. Ensure the provenance file is included in version control/packaging so installs do not drop it.

Example fix

// before
const record = readProvenance(skillDir, { required: true }); // throws if missing

// after
const record = readProvenance(skillDir) ?? writeProvenance(skillDir, buildProvenance(skillDir));

const provenancePath = getProvenancePath(normalizeSkillDir(dir));
if (required && !fs.existsSync(provenancePath)) {
  throw new Error(`Run provenance init for ${dir} first`);
}

try {
  const record = readProvenance(skillDir, { required: true });
} catch (err) {
  if (err.message.startsWith('Missing provenance metadata')) {
    const record = createProvenanceFor(skillDir);
    writeProvenance(skillDir, record);
  } else throw err;
}

When it happens

Trigger: readProvenance(dir, { required: true }) on a skill dir with no provenance file; calling plain readProvenance(dir) on a skill that requiresProvenance() flags (e.g. a third-party/unverified skill lacking metadata); pointing skillPath at a directory that is a different skill than intended, one without a provenance file.

Common situations: Onboarding old skills into a repo that now enforces provenance; vendored/community skills copied in without their metadata file; .gitignore or packaging rules stripping the provenance file during install; running the check from the wrong working directory so the resolved path points at an empty skill.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• a generated candidate cannot claim original-source identity
• Agents directory not found
• anchor evidence source duration is not bound to its receipt…
• artifact cites an unknown provenance source
• artifact has an unbound source duration

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/756099127382e3ef. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/skill-evolution/provenance.js:147

    errors,
  };
}

function assertValidProvenance(record) {
  const validation = validateProvenance(record);
  if (!validation.valid) {
    throw new Error(`Invalid provenance metadata: ${validation.errors.join('; ')}`);
  }
}

function readProvenance(skillPath, options = {}) {
  const skillDir = normalizeSkillDir(skillPath);
  const provenancePath = getProvenancePath(skillDir);
  const provenanceRequired = options.required === true || requiresProvenance(skillDir, options);

  if (!fs.existsSync(provenancePath)) {
    if (provenanceRequired) {
      throw new Error(`Missing provenance metadata for ${skillDir}`);
    }

    return null;
  }

  const record = JSON.parse(fs.readFileSync(provenancePath, 'utf8'));
  assertValidProvenance(record);
  return record;
}

function writeProvenance(skillPath, record, options = {}) {
  const skillDir = normalizeSkillDir(skillPath);

  if (!requiresProvenance(skillDir, options)) {
    throw new Error(`Provenance metadata is only required for learned or imported skills: ${skillDir}`);
  }

  assertValidProvenance(record);

View on GitHub (pinned to 8321021c54)