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:
| Input | Purpose | Main visibility |
|---|---|---|
--manifest file.json | Inspect caller-supplied coordination data | Tasks, repository paths and source snippets, leases, goals, and sessions |
--coordination directory | Discover direct child worker records | Task IDs, parsed state, heartbeat data, and status-file modification time |
--live | Add host data to either input form | OS 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
coverageandactivitymeanings 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, andnot-requestedstates.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A task references a repository or a session references a missing goal | The input is rejected instead of producing a misleading partial link | Validate manifest links before building the report |
| A coordination root or status file cannot be read | Discovery is marked unavailable or partial; it is not treated as an empty inventory | Check discovery.status and discovery.unreadable |
| A heartbeat is old or in the future | The task is labeled stale or clock-skewed; neither label proves a stuck process | Treat freshness as inspection guidance only |
| Two unexpired leases name the same resource | A lease conflict warning appears, but no owner is granted authority | Resolve ownership outside the read-only inventory |
| A caller expects goal activity from a running task or open session | Automation may act on a goal that was never declared | Use declared goal records and coverage fields |
| A source uses an alias or a non-supported relationship | Proximity warnings can miss a real dependency or report a comment as one | Read the coverage and limits before treating warnings as complete |
| Live process data is unsupported or unavailable | PID state remains unknown or not-observed | Branch on the explicit process status |
Key files
| File | Why to read it |
|---|---|
| scripts/coordination-inventory.js | Command flags, input selection, safe CLI behavior, and JSON output boundary |
| scripts/…/coordination-inventory.js | Shared normalization, report assembly, declaration activity, discovery, and live observation rules |
| scripts/…/graph.js | Source of the import relationships used by collision warnings |
| scripts/…/distance.js | Meaning of path, dependency, and tree risk channels |
| scripts/…/orchestration-session.js | Existing status format reused by coordination-directory discovery |
| examples/…/README.md | Operator guidance, scope limits, and interpretation of example output |
| examples/…/manifest.json | Basic task, path, heartbeat, and lease fixture |
| examples/…/goals.json | Goal and session declaration fixture |
| examples/…/fixtures.json | Synthetic warning and detector cases |
| examples/…/evaluate.js | Fixture classification report |
| examples/…/benchmark.js | Repeatable performance and declaration-limit measurement |
| tests/…/coordination-inventory.test.js | Guarantees for report safety, discovery, live metadata, warnings, and CLI behavior |
| tests/…/coordination-goals.test.js | Guarantees for goal/session coverage, freshness, independence, and validation |