Overlaps and stacked intents

Many agents can work on one project at once, each in its own fork. Two of them editing the same file would otherwise find out at merge time. Wayglass checks for that as early as it can.

When overlaps are checked

The Worker compares an intent’s paths (declared and actually changed) with those of every other open or proposed intent:

• at intent declare, using the declared paths and globs,
• at every push, using the files the push changed.

Globs are compared with each other, so docs/** and docs/guide.md overlap, as do **/*.md and src/**, which could both name src/README.md.

Overlaps are reported, not enforced. Nothing is blocked because of an overlap. People see a warning on stderr; agents get an overlaps list in the JSON data of intent declare and push. wayglass overlaps lists every overlapping pair in the project, or only those involving one intent:

wayglass overlaps
wayglass overlaps i269d1c348e --json

Each overlap names the other intent, its goal, agent and status, and the path pairs that collide (mine and theirs).

Suggested re-plans

For each overlap the CLI suggests a re-plan, computed from both intents’ paths and statuses. It is a suggestion: "suggested": true in JSON, and nothing about either intent changes until an agent or person acts on it.

The rules, in order:

1. One side is already proposed: it lands first, the other lands after it (land_first).
2. Both pushed edits to a contested file: stack the newer intent on the older one (stack).
3. Only one side pushed edits to a contested file: it lands first (land_first).
4. Nothing pushed yet, and both declared the same literal file: the older intent lands first (land_first).
5. Nothing pushed yet, and only globs collide: split the glob, each side declares the narrower paths it needs (split).

In push --json, each overlap carries a replan object:

{
  "action": "stack",
  "first": "i1f0c9a2b31",
  "then": "i7d42e8a0c5",
  "paths": ["web/login.ts"],
  "summary": "stack i7d42e8a0c5 on i1f0c9a2b31; both edited web/login.ts",
  "suggested": true
}

“Lands after it” works because land merges onto a moved trunk instead of rebasing; see Landing.

Stacked intents

To build on work that has not landed yet, declare the new intent on top of it with --on:

wayglass intent declare --on i1f0c9a2b31 \
  --goal "Lock accounts after repeated failures" \
  --reason "Rate limiting alone still allows slow guessing" \
  --path "web/login.ts"

A stacked intent:

• forks from the parent intent’s pushed head, not from the trunk,
• is classified on its own change only (its diff base is the parent’s head), so the reviewer sees just the new work,
• still takes its policy from the trunk commit the stack started on,
• can land only after its parent has landed; land refuses before that,
• is not reported as overlapping its parent, since sharing the parent’s code is the point.

intent declare fetches the commit the new fork starts from (for a stacked intent, the parent’s head) and fast-forwards a clean checkout that is behind it, reported as fast_forwarded in JSON. A dirty or diverged checkout is left alone with a warning. If the Worker does not support stacking, declare --on fails with stack_unsupported rather than silently forking from the trunk.