Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / coordination-inventory-and-goals

Coordination inventory and goals

The coordination inventory is a read-only view of concurrent engineering work. It combines declared tasks, work paths, leases, status files, optional process data, and goal or session declarations into JSON that operators and automated workflows can inspect without starting workers or changing coordination state. It complements orchestration and autonomous workflows and provides analysis that can be used beside workflow execution and worktrees and work items, loops, and epics.

Coordination inventory

The coordination-inventory command is the operator entry point for a point-in-time coordination report. It accepts a JSON manifest or a coordination directory and prints a stable JSON result; the optional live mode adds bounded host observations without executing input or taking control of a worker. scripts/coordination-inventory.js is the full path for the command.

Inventory inputs

The command accepts three input forms that serve different observation needs:

InputPurposeMain visibility
--manifest file.jsonInspect caller-supplied coordination dataTasks, repository paths and source snippets, leases, goals, and sessions
--coordination directoryDiscover direct child worker recordsTask IDs, parsed state, heartbeat data, and status-file modification time
--liveAdd host data to either input formOS memory and metadata for explicitly declared PIDs on supported hosts

The command can also receive --now with a UTC time. This makes freshness and lease results repeatable for fixtures and automated checks. Invalid arguments or unreadable input fail with a safe error rather than producing a partial success report.

References: scripts/coordination-inventory.js• L3-31 examples/…/README.md• L8-38

Inventory report

The report joins several views of coordination state so a consumer can separate declared intent from observed evidence:

  • Tasks show IDs, parent links, repository scope, declared paths, status, heartbeat age, and process state.
  • Leases show owners and expiry state. Simultaneous unexpired owners are surfaced as conflicts.
  • Warnings identify likely work collisions from exact path overlap or supplied relative import relationships.
  • Resources show whether memory or process collection was requested and whether that observation succeeded.
  • Coverage and limits state what the report could see and what the report must not be taken to prove.

The report is always read-only. A lease is an observation of a declaration, not a lock or permission grant. A fresh heartbeat or observed PID is useful evidence, but it does not prove that a task is healthy or that its owner is authorized.

References: scripts/…/coordination-inventory.js• L168-197 tests/…/coordination-inventory.test.js• L27-46 examples/…/README.md• L57-67

Reusable analysis library

The library in scripts/…/coordination-inventory.js separates input normalization from report construction. This lets the command, tests, examples, and future automation use the same rules without making the command the only integration point.

Input normalization

Normalization turns a bounded manifest into a safe internal view. It validates IDs, repository-relative paths, timestamps, links, collection sizes, and supported declaration states. It rejects duplicate task, goal, or session IDs and rejects links to tasks or goals that are not present in the same input.

The normalized view keeps only the fields that the inventory understands. Source snippets support dependency analysis, while task and declaration metadata remains separate from source text. This boundary allows callers to provide small, non-sensitive observations instead of private transcripts, commands, or tool results.

References: scripts/…/coordination-inventory.js• L11-45 scripts/…/coordination-inventory.js• L49-119 tests/…/coordination-inventory.test.js• L48-58 tests/…/coordination-goals.test.js• L88-114

State analysis

Report construction compares declarations with a caller-supplied observation time. It classifies heartbeats as fresh, stale, clock-skew, or unknown, and leases as unexpired or expired. If live resources are present, a task PID becomes observed or not-observed; without a usable process snapshot it remains unknown.

The collision view uses the existing agent-proximity analysis. It compares tasks within the same logical repository and combines declared path overlap with relative import dependency. The result is a review warning, not a command to pause, message, steer, or stop work.

The following flow shows how an input becomes an operator or automation report.

flowchart TD
    A[Manifest or coordination directory] --> B[Normalize bounded declarations]
    B --> C[Optional live host observations]
    B --> D[Heartbeat and lease state]
    B --> E[Goal and session activity]
    B --> F[Path and import proximity]
    C --> G[Read-only JSON inventory]
    D --> G
    E --> G
    F --> G

References: scripts/…/coordination-inventory.js• L121-197 scripts/…/coordination-inventory.js• L201-259 scripts/…/graph.js• L109-133 scripts/…/distance.js• L243-260

Goal and session declarations

Goals and sessions add a small coordination vocabulary to the inventory. A goal is a caller-declared unit of intended or completed work. A session is a caller-declared period of work that may link to a task or goal. These records expose coordination state without making the inventory a goal tracker or a source of execution authority.

Goal state

Each goal can declare a task link, a kind, a status, and an update time. The supported goal kinds are native and unknown; supported statuses are active, complete, blocked, and unknown. The native kind means that the caller reports a native goal observation. It does not mean that the inventory verified a native goal tool.

The report counts goals by status and also counts native-kind declarations. It marks each record as declared-only and adds freshness without changing the declared status. A fresh active native declaration is therefore a recent caller observation, not proof of current execution.

References: scripts/…/coordination-inventory.js• L78-83 scripts/…/coordination-inventory.js• L126-140 examples/…/README.md• L69-80

Session state

Each session can declare task and goal links, an open or closed status, and an update time. Sessions and goals remain independent: an open session can point to a complete goal, and several sessions can point to one goal. The report counts records rather than treating those links as exclusive ownership.

The activity summary highlights open sessions without a goal declaration. It never infers a goal from a running task, heartbeat, PID, lease, terminal, or status-file change. Missing collections are distinct from explicit empty collections through coverage.goals and coverage.sessions; neither state proves that no goal or session exists elsewhere.

References: scripts/…/coordination-inventory.js• L84-92 scripts/…/coordination-inventory.js• L134-140 tests/…/coordination-goals.test.js• L12-36 examples/…/README.md• L95-109

Goal observations

Goal and session data is intended for an authorized caller to summarize. The caller keeps the original receipt and its provenance outside the inventory. The inventory omits unknown fields, does not read private thread stores, and does not import GOAL-STATE files automatically.

This boundary matters for automated workflows. A workflow may use counts and freshness to decide what to inspect next, but it must use its own authority and source of truth before it changes work or claims that a goal is running.

References: examples/…/README.md• L88-93 tests/…/coordination-goals.test.js• L88-94

Fixtures and benchmarks

The examples provide repeatable inputs for learning and controlled analysis. They show how the same library exposes task proximity, lease conflicts, goal activity, and known limits without presenting synthetic results as production measurements.

Example manifests

examples/…/manifest.json demonstrates a parent and child task, a stale heartbeat, a direct import relationship, and two owners for one browser resource. examples/…/goals.json adds active and complete goals plus open sessions with different links. These files are fixtures for report shape and interpretation; they do not grant access to a browser or any other resource.

The example README is the guide for running the command, discovery adapter, evaluation script, and tests from a source checkout. The coordination directory adapter reads direct child directories with STATUS.md or status.md. Freeform status stays unknown, while an unreadable root or child is reported as unavailable or partial rather than as an empty healthy inventory.

References: examples/…/manifest.json• L1-41 examples/…/goals.json• L1-18 examples/…/README.md• L20-29

Evaluation fixtures

examples/…/fixtures.json contains eight authored task pairs. The pairs compare exact path matching with the broader path-and-import warning view. They include direct imports, independent paths, separate repositories, comments that look like imports, aliases, and cross-artifact relationships.

evaluate.js reports a classification matrix for those synthetic pairs. The result characterizes fixture behavior only. It does not establish a calibrated risk probability, semantic proximity, or a reduction in real coordination conflicts.

References: examples/…/fixtures.json• L1-255 examples/…/evaluate.js• L9-19 examples/…/README.md• L117-132

Performance benchmark

benchmark.js measures repeated in-process inventory builds for the legacy manifest, the goal-and-session manifest, and a declaration-limit workload. It reports input hashes, sample counts, median and p95 build times, activity output, and the same eight-pair control matrix.

The benchmark excludes process startup and command-line I/O. Its timing is machine-dependent, and the declaration-limit case is not a worst-case graph workload. Compare runs only when the inputs, runtime, and parameters match; the benchmark does not claim a production speedup or conflict reduction.

References: examples/…/benchmark.js• L5-16 examples/…/benchmark.js• L18-34 examples/…/benchmark.js• L47-56 examples/…/README.md• L142-150

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to manifest links or declaration states must stay aligned with the coverage and activity meanings consumed by automation.
  • Changes to report fields must account for consumers that reject unknown JSON fields; the goal and session fields are additive to the v1 report.
  • Changes to status-file parsing must preserve the distinction between structured observations, freeform content, partial discovery, and unavailable roots.
  • Changes to source-map or proximity rules must update the fixture classification limits so warning results remain honest.
  • Changes to live resource collection must preserve the metadata-only boundary and the explicit unsupported, unavailable, and not-requested states.

Important failure modes

TriggerConsequenceGuard
A task references a repository or a session references a missing goalThe input is rejected instead of producing a misleading partial linkValidate manifest links before building the report
A coordination root or status file cannot be readDiscovery is marked unavailable or partial; it is not treated as an empty inventoryCheck discovery.status and discovery.unreadable
A heartbeat is old or in the futureThe task is labeled stale or clock-skewed; neither label proves a stuck processTreat freshness as inspection guidance only
Two unexpired leases name the same resourceA lease conflict warning appears, but no owner is granted authorityResolve ownership outside the read-only inventory
A caller expects goal activity from a running task or open sessionAutomation may act on a goal that was never declaredUse declared goal records and coverage fields
A source uses an alias or a non-supported relationshipProximity warnings can miss a real dependency or report a comment as oneRead the coverage and limits before treating warnings as complete
Live process data is unsupported or unavailablePID state remains unknown or not-observedBranch on the explicit process status

Key files

FileWhy to read it
scripts/coordination-inventory.jsCommand flags, input selection, safe CLI behavior, and JSON output boundary
scripts/…/coordination-inventory.jsShared normalization, report assembly, declaration activity, discovery, and live observation rules
scripts/…/graph.jsSource of the import relationships used by collision warnings
scripts/…/distance.jsMeaning of path, dependency, and tree risk channels
scripts/…/orchestration-session.jsExisting status format reused by coordination-directory discovery
examples/…/README.mdOperator guidance, scope limits, and interpretation of example output
examples/…/manifest.jsonBasic task, path, heartbeat, and lease fixture
examples/…/goals.jsonGoal and session declaration fixture
examples/…/fixtures.jsonSynthetic warning and detector cases
examples/…/evaluate.jsFixture classification report
examples/…/benchmark.jsRepeatable performance and declaration-limit measurement
tests/…/coordination-inventory.test.jsGuarantees for report safety, discovery, live metadata, warnings, and CLI behavior
tests/…/coordination-goals.test.jsGuarantees for goal/session coverage, freshness, independence, and validation