explain.md

estado	Completed

Explain

rootline explain traces each effective field in a document: whether it came from frontmatter, a schema default/source extraction, derivation, or aggregation, and what expression produced computed values. Current output reports .stem defined_in provenance for schema-backed fields; derive and aggregate fields expose their expression but not the .stem path that declared it.

CLI Usage

rootline explain docs/query.md
rootline explain docs/epics/E04/README.md -o json

JSON Result

{
  "version": 1,
  "kind": "rootline/explain",
  "path": "docs/query.md",
  "stem_chain": ["docs/.stem"],
  "fields": [
    {
      "name": "estado",
      "value": "Completed",
      "origin": "frontmatter",
      "defined_in": "docs/.stem"
    },
    {
      "name": "notes",
      "value": "Release notes go here.",
      "origin": "derived",
      "source": "body.section[\"## Notes\"]",
      "defined_in": "docs/.stem"
    },
    {
      "name": "total",
      "value": 3,
      "origin": "aggregate",
      "expression": "len(descendants)",
      "defined_in": "docs/.stem"
    }
  ]
}

For documents with derived and aggregated fields, each field shows its expression and origin:

{
  "version": 1,
  "kind": "rootline/explain",
  "path": "docs/epics/E04/README.md",
  "stem_chain": ["docs/epics/.stem"],
  "fields": [
    {
      "name": "estado",
      "value": "In Progress",
      "origin": "frontmatter",
      "defined_in": "docs/epics/.stem"
    },
    {
      "name": "slug",
      "value": "dx-advanced",
      "origin": "derived",
      "expression": "slugify(titulo)"
    },
    {
      "name": "total",
      "value": 15,
      "origin": "aggregate",
      "expression": "len(descendants)"
    }
  ],
  "errors": [
    {
      "rule": "enum",
      "field": "tipo",
      "message": "invalid value \"unknown\"",
      "source": "docs/epics/.stem",
      "severity": "error",
      "suggestion": "task"
    }
  ]
}

The stem_chain is emitted in resolution order, root-to-target/leaf. A chain that reaches the filesystem root without a root: true marker has no declared boundary; the preflight stops governed commands there and asks for the marker. The origin field is one of: frontmatter, schema (default value), derived, or aggregate.

For a source-backed field, source is the logical directive and defined_in is the physical .stem declaration. Explain resolves the same effective value as validation and query; frontmatter remains an override, empty-present sections remain present, and duplicate matching headings are reported as errors.

For index files with aggregate expressions, explain scans the containing directory for aggregate input records before rendering. A filesystem failure during that scan returns a contextual error, exits non-zero, and emits no stdout in either JSON or table mode; it does not report a successful trace with a null aggregate value. Malformed sibling frontmatter retains the scanner's existing record-extraction behavior: it is represented as a record with extraction errors rather than failing the scan.

explain supports -o json and -o table only — see Output Formats.