Reporter Protocol

Reporter — Operational Protocol

Protocol

1. DISCOVER

1. Read inputs from the orchestrator execution context:
   • counts_path: path to frequency-counts.json written by the tokenizer step.
   • output_path: path where the final word frequency report must be written (always {ROOT}/output/parity-test-g-word-freq.txt).
   • state_path: path to pipeline-state.json for status updates.
   • run_id: current run identifier.
   • root: resolved scope root.
2. Verify counts_path exists and is a readable file. If not: update pipeline-state.json phases[1].status = "blocked"; emit BLOCKED with message: "Tokenizer frequency counts not found at {counts_path}. The tokenizer step may have failed."
3. Parse the counts JSON. If JSON is malformed: update pipeline-state.json phases[1].status = "blocked"; emit BLOCKED with message: "Frequency counts at {counts_path} are not valid JSON. Re-run the tokenizer step."

2. PROCESS

Step 2.1 — Select top-20:

Take the first 20 entries from counts.counts (already sorted descending by count by the tokenizer). If fewer than 20 entries exist, use all available entries. Record words_reported = number of entries selected.

Step 2.2 — Handle zero-entry edge case:

If counts.counts is empty, note words_reported = 0; proceed to deliver (the output will contain only the header and a sentinel line).

Step 2.3 — Render the report:

Format the plain-text report using the following template:

Word Frequency Report — parity-test-g
======================================
Source file : {counts.source_path}
Total tokens: {counts.total_tokens}
Unique words: {counts.unique_words}
Stopwords excluded: {counts.stopwords_excluded}
Generated   : {iso8601-timestamp}

Rank  Word                  Count
----  --------------------  -----
   1  {word}                {count}
   2  {word}                {count}
  ...
  20  {word}                {count}

Rules:

• Rank column: right-aligned integer, width 4.
• Word column: left-aligned, width 20.
• Count column: right-aligned integer, width 5.
• If words_reported < 20, the table ends after the last available word. Do NOT pad with empty rows.
• If words_reported = 0, replace the table with a single line: (no content words found after stopword removal)

3. DELIVER

1. Create the {root}/output/ directory if it does not exist.
2. Write the rendered report to output_path using the Write tool.
3. Update pipeline-state.json:
   • Set phases[1].status = "completed" (or "completed_with_concerns" if zero words reported).
   • Set phases[1].outputs = [output_path].
   • Set top-level status = "completed" (or "completed_with_concerns" as appropriate).
   • Set completed_at = current ISO-8601 timestamp.
4. Emit terminal status:
   • DONE — report written successfully with at least one word entry.
   • DONE_WITH_CONCERNS — report written but contained zero word entries (note reason).
   • BLOCKED — counts file missing or malformed; output not written.