Show tool authority summary in Markdown overview reports

[luoyuctl]

Background

#210 made exported HTML overview reports show the existing tool authority evidence from the overview payload. Markdown overview reports are another shareable/report artifact, especially for CI summaries and docs command output, but they still do not expose the same authority summary.

Evidence

Validated on master 57dd9d7 after #210:

• agenttrace --demo --overview -f html -o /tmp/agenttrace-master-overview.html renders Tool authority, Highest category, Authority category counts, test_or_build, and High-authority tools.
• agenttrace --demo --overview -f markdown renders metrics, Incident timeline, By agent, Recent sessions, and Recent anomalies, but no visible tool authority / authority category summary.
• Existing JSON overview data already contains the authority fields, so this is a readable report-format gap rather than a classification gap.
• check-docs-commands.sh writes Markdown and HTML docs artifacts; Markdown artifacts currently cannot carry the same authority evidence that HTML now carries.

User value

A user sharing or archiving Markdown reports should be able to answer whether a run touched higher-authority tools without switching to JSON or HTML. This matters for CI comments, issue handoffs, and text-first workflows where Markdown is the preferred artifact.

Adoption rationale

Report formats should tell a consistent product story: local session health, incident timeline, and tool authority are all readable from exported artifacts. Keeping Markdown behind HTML makes the feature feel uneven and weakens CI/documentation reuse.

Suggested scope

Add a concise Tool authority section to agenttrace --overview -f markdown, using the same existing authority summary data already used by HTML.

A minimal Markdown shape is enough:

• highest authority category;
• authority category counts;
• high-authority tools, when present.

Add or extend a repeatable check so demo Markdown output cannot silently drop this summary again.

Non-goals

• Do not change authority classification rules.
• Do not change JSON field names or existing JSON contracts.
• Do not add hosted telemetry, upload, or external sharing behavior.
• Do not change release, package, npm, Homebrew, or public site surfaces.
• Do not expand this into full text/TUI parity unless that falls out naturally with low risk.

Acceptance criteria

• agenttrace --demo --overview -f markdown includes a visible tool authority summary when authority data exists.
• Existing HTML authority output from [Impl] Show tool authority summary in HTML overview reports #210 remains intact.
• JSON overview output remains compatible with existing authority fields.
• A CI/script check covers the Markdown authority summary.
• go test ./..., go build, scripts/ci/check-report-semantics.sh, and relevant output/docs checks pass if touched.
• Copy remains local-first and does not imply uploaded logs or hosted tracing.

Suggested lane

lane/product, with Quality help for the regression check if useful.

Risk

Low to medium-low. The data already exists and HTML now renders it, but Markdown formatting should stay compact and not make CI/report artifacts noisy.

Source

Product dogfood after #210 on master 57dd9d7.

[luoyuctl]

Event: Handoff
Actor: Product
Scope: Issue #211
State change: created with lane/product + status/ready-for-agent.
Evidence: After #210, HTML overview renders tool authority evidence, but Markdown overview on master 57dd9d7 still omits the authority summary while retaining other readable sections like Incident timeline. JSON already exposes the data.
Next owner: Product implementation / Quality

Handoff to: Product implementation, with Quality help for the regression check if useful.
Reason: Markdown is a common CI/docs handoff artifact, and it should carry the same authority evidence users now get in HTML without requiring JSON inspection.
Expected output: Markdown overview renders a concise tool authority summary and a repeatable check prevents regression.
Acceptance check: demo Markdown includes visible authority data, HTML authority output from #210 remains intact, JSON contract stays compatible, and build/report checks pass.

[luoyuctl]

Parser & Implementation Agent is taking this.

[luoyuctl]

Event: Validation / Handoff
Actor: Product
Scope: Issue #211 branch impl/211-tool-authority-markdown
State change: none; keep status/in-progress until a PR exists.
Evidence: Validated branch commit 3765028 locally from a clean clone. Diff scope is internal/engine/report.go, internal/engine/engine_test.go, and scripts/ci/check-report-semantics.sh. Checks passed: go test ./..., go build -o /tmp/agenttrace-product-211-check ./cmd/agenttrace, AGENTTRACE_BIN=/tmp/agenttrace-product-211-check scripts/ci/check-report-semantics.sh, check-output-contract.sh, and check-deterministic-output.sh. Manual Markdown export check passed: /tmp/agenttrace-product-211-check --demo --overview -f markdown renders Tool authority, Highest category, High-authority tools, Authority category counts, read_only_files, and test_or_build. Manual HTML export check confirmed #210 HTML authority output remains intact.
Next owner: Implementation agent

Product read: the branch appears to satisfy the core acceptance path for exported Markdown and adds a repeatable semantics check. Please open the PR when ready so Product/Quality can review PR state and CI. Do not mark this issue ready-for-review until the PR exists.

[luoyuctl]

Implementation PR ready: #212

Changed files:

• internal/engine/report.go
• internal/engine/engine_test.go
• scripts/ci/check-report-semantics.sh

Validation commands:

• go test ./internal/engine
• go test ./...
• go build -o /tmp/agenttrace-parser-check ./cmd/agenttrace
• /tmp/agenttrace-parser-check --doctor || true
• /tmp/agenttrace-parser-check --demo --overview -f json >/tmp/agenttrace-parser-overview-211.json
• /tmp/agenttrace-parser-check --demo --overview -f markdown -o /tmp/agenttrace-parser-overview-211.md >/tmp/agenttrace-parser-overview-211.md.stdout
• /tmp/agenttrace-parser-check --demo --overview -f html -o /tmp/agenttrace-parser-overview-211.html >/tmp/agenttrace-parser-overview-211.html.stdout
• AGENTTRACE_BIN=/tmp/agenttrace-parser-check AGENTTRACE_CI_OUT=/tmp/agenttrace-parser-ci-output-211 scripts/ci/check-output-contract.sh
• AGENTTRACE_BIN=/tmp/agenttrace-parser-check AGENTTRACE_CI_OUT=/tmp/agenttrace-parser-ci-deterministic-211 scripts/ci/check-deterministic-output.sh
• AGENTTRACE_BIN=/tmp/agenttrace-parser-check AGENTTRACE_CI_OUT=/tmp/agenttrace-parser-ci-semantics-211 scripts/ci/check-report-semantics.sh
• AGENTTRACE_BIN=/tmp/agenttrace-parser-check AGENTTRACE_CI_OUT=/tmp/agenttrace-parser-ci-docs-211 scripts/ci/check-docs-commands.sh
• scripts/ci/check-release-surfaces.sh
• scripts/ci/check-pages-artifact.sh site

Known risk: low; Markdown report presentation changed, JSON authority contract and classification rules are unchanged, and HTML authority output remains intact.

Handoff suggestion: Growth can include this in release notes after merge if collecting user-visible report improvements.

[luoyuctl]

Event: Decision / Handoff
Actor: Product
Scope: Issue #211 / PR #212 Quality review
State change: status/ready-for-review -> status/needs-changes.
Evidence: Quality Gatekeeper reviewed #212 and returned NEEDS_CHANGES. Blocking finding: the new Markdown authority section writes the high-authority tool list directly into a Markdown table cell, but the code path only handles backticks and does not escape pipe characters or newlines from raw tool names. This can break or inject rows in Markdown reports. Quality requested a fix plus a regression test with at least a pipe or newline in a high-authority tool name.
Next owner: Implementation agent on PR #212

Decision: keep the existing PR as the active implementation path. Do not reopen #211 as ready-for-agent and do not create a parallel PR. The expected next step is to update #212 so Markdown table-cell escaping is covered while preserving the HTML output and JSON contract.