Mellea Fy Inventory

Melleafy Steps 1a + 1b: File Inventory and Element Tagging

Version: 4.1.0 | Prereq: classification.json | Produces: inventory.json

Schema: Output intermediate/inventory.json MUST conform to schemas/inventory.schema.json.

Step 1a reads files from the source based on the detected runtime's dialect. Step 1b takes those files and produces inventory.json — every significant element tagged with one of 17 tags and assigned to one of 9 dependency categories.

Step 1a: File Inventory

Read source files per the runtime's dialect. The dialect doc at docs/dialects/<runtime>.md defines exactly which files to read and their roles.

Also check: whether the spec's parent directory contains scripts/, references/, or assets/ directories (Agent Skills companion directories). If present, inventory their contents — scripts the spec references are tool-dependent inputs (C6); reference docs the spec says to "consult" are external data dependencies (C3 or C8). These directories are mirror sources per Rule OUT-6 (see mellea-fy.md): they remain at the skill root as the source of truth, and Step 3a-pre copies them into <package_name>/ before any code body is generated. Downstream steps may assume the package-internal copy is the runtime location, and emitted code MUST resolve their paths via Path(__file__).parent / "<dir>/<file>".

Output of Step 1a: a list of {filepath, role, frontmatter, content} tuples consumed by Step 1b.

Step 1b: Element Tagging and Categorisation

The 17 tags

Every significant line of the source spec becomes an element with exactly one of:

Python vs LLM decision rule: Before tagging an element as CLASSIFY/EXTRACT/GENERATE, ask: does this require judgment, interpretation, or natural language understanding?

• Tag DETERMINISTIC: config parsing, URL template filling, parameter mapping, enum lookups, JSON payload construction, string formatting, validation logic, numerical computations, if/for/dict.get()/str.format() operations.
• Tag CLASSIFY/EXTRACT/GENERATE: intent classification from natural language, severity assessment, content generation, natural language formatting, out-of-scope detection.

VALIDATE_OUTPUT vs VALIDATE_DOMAIN — this distinction is critical:

• VALIDATE_OUTPUT: checks on what the agent itself produced. → Requirement.
• VALIDATE_DOMAIN: checks the agent performs on external data (code, papers, patches). → m.instruct(format=VerdictSchema). If an element tagged VALIDATE_OUTPUT describes checking something other than the agent's own output, flag it as a probable tagging error.

The nine dependency categories (C1–C9)

Every element gets a category (C1–C9) or — (no external dependency):

Tag + category orthogonality — forbidden combinations:

• SCHEMA with category ≠ — (schemas are structure, not external dependencies)
• CONFIG with category ∈ {C4, C5, C9} (these are always runtime-delegated, not bundled constants)
• TOOL_TEMPLATE with category ≠ C6 (tools are C6 by definition)
• NO_DECOMPOSE with category ≠ —

Two-pass processing

Pass 1 — Section discovery: Discover candidate element boundaries across all source files.

For single-file runtimes (agent_skills_std, openclaw): one lightweight LLM invocation producing candidate boundaries {start_line, end_line, rough_kind}.

For multi-file runtimes (CrewAI, LangGraph, AutoGen, OpenAI Agents SDK, smolagents): dispatch one lightweight LLM invocation per file in parallel (all files simultaneously in a single turn). Each invocation returns candidate boundaries for its file. Since inter-file dependencies do not exist at this stage (Pass 1 is pure section discovery per file), all invocations can be issued concurrently using tool-call parallelism.

Output per invocation: {start_line, end_line, rough_kind} tuples where rough_kind is one of {rule, check, constant, tool_ref, schema, prose, other} — not a tag yet. Output schema is one class (SectionBoundary) with primitive fields.

Pass 2 — Element refinement: After all Pass 1 results are collected, issue a single LLM invocation processing all candidate boundaries and returning List[InventoryElement]. Each element in the list is the full element record: tag, category, content_summary, metadata. The List[InventoryElement] schema uses one class — KB5 schema priming concerns do not apply to melleafy compilation calls (KB5 governs Mellea pipeline sessions inside compiled skills, not the compilation process itself).

Retry protocol (when refinement produces invalid output):

1. Retry 1: include the validation error and re-invoke.
2. Retry 2: widen context to include neighboring elements.
3. Retry 3: split the element into two and re-invoke each separately. After 3 retries: record as tag: NO_DECOMPOSE, category: "—", notes: "refinement failed after 3 retries: <reason>". Step 1b does not halt on single-element failure.

Cross-element pass (deterministic — no LLM): after all elements are refined, identify aggregation candidates:

• Two VALIDATE_OUTPUT elements with near-identical content → flag with aggregation_hint
• Two CONFIG elements targeting the same constant name → flag
• Three+ sequential ORCHESTRATE elements → flag as "orchestration chain" Aggregation hints are advisory; Step 2.5a commits.

Coverage measurement

Target: ≥95% of non-blank, non-heading source lines represented in inventory.json.

Denominator: all source lines excluding pure whitespace and Markdown heading lines (^\s*#+\s). Numerator: lines within some element's source_lines range.

Record in intermediate/coverage_report.json. If coverage < 0.95: retry section discovery with relaxed boundary heuristics on the lowest-coverage files. If still < 0.95 after retry: halt with a generation-halt error.

Decomposition rules

Compound elements: if an element contains multiple operations ("Identify and rule out failure modes" = EXTRACT + VALIDATE), split before mapping.

Conditional elements: model the condition as a DECIDE gate wrapping the relevant sub-elements.

Checklist elements: group into a single Mellea construct or split — use judgment based on whether independent pass/fail tracking is needed.

Cross-cutting requirements: if a quality standard applies globally to all outputs, define it once in requirements.py and attach to every m.instruct() call.

Remediation loops: if the spec describes an iterative fix-and-verify cycle, tag the modification step REMEDIATE and the evaluation step EXTRACT or VALIDATE_DOMAIN. Implement as a bounded while loop with MAX_REMEDIATION_ITERATIONS in config.py.

Output: inventory.json

Every element has this shape:

{
  "element_id": "elem_042",
  "source_file": "AGENTS.md",
  "source_lines": "15-22",
  "tag": "DECIDE",
  "category": "C2",
  "content_summary": "Escalate critical-priority tickets before auto-triaging",
  "content_full": "When a ticket arrives with priority:critical,\nalways escalate to L2 before\nrunning the auto-triage workflow.",
  "confidence": { "tag": 0.95, "category": 0.9 },
  "aggregation_hint": null,
  "notes": null,
  "dialect_attribution": "openclaw:AGENTS.md body rule"
}

Element IDs are elem_<NNN> (zero-padded, source order). IDs are stable within a run but not across re-runs when source changes.

Cross-checks before Step 1b declares done:

• Coverage ≥ 0.95
• Every element has tag in the 17-tag set
• Every element has category in {C1..C9, "—"}
• No element has a forbidden tag+category combination
• element_id values are sequential with no gaps
• Every source_file refers to a file from Step 1a's list