reflect_audit

Category: reflection
Access: read
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Finds consolidation candidates without mutating anything. Call it to preview duplicates, stale work, orphans, and hygiene gaps before starting a run.

Arguments

Optional: abandoned_inbox_days, format, limit_per_category, project, stale_days.

abandoned_inbox_days: inbox items untouched this long are flagged (default 30) Note: Inbox items untouched this long are flagged; defaults 30.
format: "json" (default) or "markdown" (adds rendered report) Note: json or markdown; markdown adds a rendered report.
limit_per_category: cap candidates per category (default 20) Note: Cap per category; defaults 20.
project: filter to a single project (empty = all) Note: Single-project filter; empty means all but then requires star scope.
stale_days: due_date older than this many days counts as stale (default 60) Note: Overdue thresholds older than this many days count as stale; defaults 60.

Result

Object with version, summary (total_candidates, by_category, applied_filters), candidates per category, and markdown when requested.

Boundaries

An explicit project must be granted; an unfiltered global audit requires star scope. Scans additionally constrain to grants, so candidates only come from visible projects.

Lifecycle / side effects

Read-only dry run; persists nothing. Six deterministic categories: exact duplicate titles, stale overdue not_started tasks, empty-description notes, orphan parent links, abandoned inbox items, and entities without observations, each with a suggested action.

Errors

Out-of-scope project or non-star global request returns a normal error payload. Engine failures return a normal error payload, never a transport error.

Example

{
  "format": "json",
  "limit_per_category": 20
}

Result shape:

{
  "candidates": {
    "exact_duplicate_titles": []
  },
  "summary": {
    "by_category": {
      "exact_duplicate_titles": 0
    },
    "total_candidates": 0
  },
  "version": "reflect_audit_v0.5_dry_run"
}