test(cli): prove sync restores only what antigravity setup wrote

aidd_docs/tasks/2026_10/2026_10_14_antigravity-review-fixes/backlog-link.json

@@ -0,0 +1,5 @@
+{
+  "backlog": "ai-driven-dev/framework#511",
+  "written_at": "2026-10-14T12:00:00Z",
+  "written_by": "aidd-dev:01-plan"
+}

aidd_docs/tasks/2026_10/2026_10_14_antigravity-review-fixes/phase-1.md

@@ -0,0 +1,66 @@
+---
+status: pending
+---
+
+# Instruction: Host profile: user-facing skip message, conformance guard
+
+Owning commit: `feat(cli): add Antigravity CLI as a flat host for skills` on `feat/511-antigravity-host`.
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+cli/
+├── src/contexts/tools/domain/profiles/antigravity/profile.ts                 ✏️ skip reason without a ticket reference
+└── tests/contexts/tools/domain/
+    ├── profiles/antigravity/profile.unit.test.ts                             ✏️ assert the new reason
+    └── registry-conformance.unit.test.ts                                     ✏️ named opt-out replaces the silent early return
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[aidd setup --ai antigravity on a hooks plugin] --> B[skip reason printed]
+  B --> C[no ticket id in the message]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    Check out the host branch => profile and conformance tests present: 5: system
+  section Happy path
+    Read the antigravity hooks skip reason => it says hooks are not wired yet, with no ticket id: 5: system
+    Run the conformance suite => antigravity passes through its named opt-out: 5: system
+  section Edge case - new flat-only tool
+    A tool declaring plugins with no marketplace contract and no opt-out => conformance runs => the probe assertion fails: 1: system
+```
+
+## Tasks to do
+
+### `1)` Skip reason
+
+> The message a user reads carries no ticket reference.
+
+1. Set `hooksUnsupportedReason` to `Antigravity CLI hooks are not wired yet.`
+2. Assert that exact string in the profile test instead of `toContain("phase 3")`.
+
+### `2)` Explicit conformance opt-out
+
+> A future flat-only tool cannot skip the marketplace-probe check by accident.
+
+1. Replace the early `return` with a named set of tools exempt from the marketplace probe, holding `antigravity` with a one-line reason.
+2. Mutation check: drop `antigravity` from the set, the probe test goes red; restore.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | The antigravity hooks skip reason contains no `#` ticket id and the profile test pins it |
+| 2 | Removing antigravity from the opt-out set fails the conformance test for antigravity only |

aidd_docs/tasks/2026_10/2026_10_14_antigravity-review-fixes/phase-2.md

@@ -0,0 +1,108 @@
+---
+status: pending
+---
+
+# Instruction: Project hooks: `--force` reaches the edit guard
+
+Owning commit: `feat(cli): merge plugin hooks into antigravity's .agents/hooks.json` on `feat/511-antigravity-memory-hook`.
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+cli/
+├── src/contexts/framework/application/
+│   ├── shared/remove-project-hooks.ts                          ✏️ overwriteEdited option; refusal hints --force
+│   ├── framework/translator/project-hooks-materializer.ts      ✏️ honour overwriteEdited, obsolete-script removal too
+│   ├── framework/translator/plugin-translator.ts               ✏️ contract carries overwriteEdited
+│   ├── framework/translator/mode-b-flat-materialization-translator.ts   ✏️ forward it
+│   ├── framework/translator/built-tree-materialization-translator.ts    ✏️ forward it; drop flat hook scripts from plugin files
+│   ├── plugin/plugin-helpers.ts                                ✏️ materializeViaTranslator forwards it
+│   ├── shared/apply-plugin-files-use-case.ts                   ✏️ option force
+│   ├── restore/restore-all-plugins-use-case.ts                 ✏️ option force
+│   ├── restore/restore-use-case.ts                             ✏️ pass ctx.force to plugin restore
+│   └── clean-use-case.ts                                       ✏️ pass options.force to hook preflight and removal
+├── src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.ts   ✏️ comment without a pinned agy version
+├── src/contexts/translate/application/strategies/flat-build-strategy.ts   ✏️ unparsable hooks file named, left untouched
+└── tests/                                                      ✏️ reviewer reproductions, duplicate-record check, translate error
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[setup --ai antigravity] --> B[user edits AIDD hook script or its hooks.json entry]
+  B --> C{command}
+  C -- sync --force --> D[AIDD entry and script rewritten, user key kept, drifted skill restored]
+  C -- clean --force --> E[AIDD entry and scripts removed, user key kept, all plugin files removed]
+  C -- sync without --force --> F[refused, message suggests --force]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    Install aidd-context for antigravity in a temp project with a user lint hook => hooks.json holds lint and aidd-context, provenance recorded: 5: system
+  section Happy path
+    Edit the AIDD hook script then sync --force => script restored to installed content: 5: cli
+    Edit the AIDD hooks.json entry then sync --force => entry restored, lint untouched: 5: cli
+    Edit the AIDD hook then clean --force => AIDD entry and script gone, lint kept, plugin files gone: 5: cli
+  section Edge case - no force
+    Edited hook => sync without --force => refused with a hint to rerun with --force: 1: cli
+  section Edge case - ownership unproven
+    Hook script path outside the plugin hooks dir in provenance => sync --force => still refused: 1: cli
+  section Edge case - unparsable hooks file
+    Invalid .agents/hooks.json => translate --as flat => error names the file, file left untouched: 1: cli
+  section Teardown
+    Remove the temp project => baseline restored: 5: system
+```
+
+## Tasks to do
+
+### `1)` Reproduce first
+
+> The reviewer's three reproductions fail before any production change.
+
+1. Add use-case level tests for: edited script + `sync --force`, edited entry + `sync --force`, edited hook + `clean --force`; each also asserts the user `lint` key survives.
+2. Add the no-force refusal test expecting the `--force` hint, and the unproven-path test expecting a refusal under force.
+3. Run them; record the red failure messages.
+
+### `2)` Thread `force` to the guard
+
+> One explicit option flows from the command to the guard; no global state.
+
+1. `assertProjectHooksUnchanged` takes `{ overwriteEdited }`; when true it skips only the entry-digest and script-hash "edited after install" refusals.
+2. `removeObsoleteScripts` deletes an edited obsolete script when `overwriteEdited` is set.
+3. Forward it: `RestoreUseCase` → `RestoreAllPluginsUseCase` → `ApplyPluginFilesUseCase` → `materializeViaTranslator` → `PluginTranslator.addPlugin` → `ProjectHooksMaterializer`; and `CleanUseCase` → `assertProjectHooksRemovable` / `removeProjectHooks`.
+4. Without the option, the refusal text ends with a hint to rerun with `--force`.
+5. Mutation check: drop the forwarding at one layer, a reproduction goes red.
+
+### `3)` One owner per hook script
+
+> A project-delivered hook script is recorded in the hooks provenance only.
+
+1. Test: after a flat antigravity install, `plugins[].files` holds no `.agents/hooks/` path and `projectHooks.scripts` holds the script.
+2. In the built-tree flat route, drop the flat hook output paths from the plugin files when the tool delivers hooks to the project.
+3. Re-run the restore test of the top branch to confirm it still holds.
+
+### `4)` Minors
+
+> Small corrections the reviewer named.
+
+1. `translate --as flat` with an unparsable `.agents/hooks.json` reports the same "is not valid JSON (...); left untouched." message as setup; test first.
+2. Remove the pinned `agy` version from the `antigravity-hooks.ts` comment.
+3. Rebuild and record the bundle size; bump the budget only if exceeded, with its comment line.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | The three reproductions and the no-force test exist and failed before task 2 |
+| 2 | `sync --force` and `clean --force` succeed on an edited AIDD hook, the user `lint` key survives, an unproven path still refuses, no-force refuses with a `--force` hint |
+| 3 | A fresh antigravity manifest records the hook script once, under `projectHooks.scripts` |
+| 4 | The translate error names `.agents/hooks.json`; no agy version in the comment; bundle under budget |

aidd_docs/tasks/2026_10/2026_10_14_antigravity-review-fixes/phase-3.md

@@ -0,0 +1,69 @@
+---
+status: pending
+---
+
+# Instruction: Agents: bundle figures, bracketed frontmatter values
+
+Owning commit: `feat(cli): emit antigravity agents as portable .agents/agents/<name>/agent.md` on `feat/511-antigravity-agents`.
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+cli/
+├── scripts/check-bundle-size.mjs                                   ✏️ per-PR split of the measured growth
+├── package.json                                                    ✏️ budget only if phase 2 moved the size
+├── src/kernel/markdown.ts                                          ✏️ raw emission only for a real JSON array
+└── tests/
+    ├── contexts/tools/domain/formats/portable-agent.unit.test.ts   ✏️ bracketed description, non-string tools
+    └── kernel/markdown.unit.test.ts                                ✏️ the same value round-trips as a string
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[agent description '[WIP] foo [x]'] --> B[antigravity build]
+  B --> C[frontmatter parses, description is the same string]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    An agent source with description '[WIP] foo [x]' and tools [1, true] => fixture ready: 5: system
+  section Happy path
+    Build the portable frontmatter and parse it back => description equals the source string, tools are strings: 5: system
+  section Edge case - real JSON array string
+    A cursor globs value '["a/**","b"]' => serialize => still emitted as a YAML inline array: 1: system
+```
+
+## Tasks to do
+
+### `1)` Bundle figures
+
+> The comment and the commit tell the same per-PR story as the measurements.
+
+1. Rebuild each branch tip after phase 2 and record its size.
+2. Rewrite the budget comment lines: host profile, hooks merge, agents, each with its own measured delta.
+3. Reword the owning commit message's bundle sentence to the measured figures.
+
+### `2)` Bracketed values
+
+> A string that only looks like a list is quoted.
+
+1. Test first: `[WIP] foo [x]` and non-string `tools` items through `portableAgentFrontmatter` + `serializeFrontmatter`, parsed back with the project's YAML reader.
+2. If red, emit a value raw only when it parses as a JSON array; quote otherwise.
+3. Keep the cursor globs test green.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | The budget comment, the commit message and the measured sizes agree for each of the three branches |
+| 2 | A bracketed description parses back as the same string; a JSON-array string still serializes as an inline array |

aidd_docs/tasks/2026_10/2026_10_14_antigravity-review-fixes/phase-4.md

@@ -0,0 +1,82 @@
+---
+status: pending
+---
+
+# Instruction: Docs and runtime smoke
+
+Owning commits on `feat/511-antigravity-docs`: the smoke (`test(cli): add a local runtime smoke for antigravity`), the `aidd-context` surfaces (`feat(aidd-context): refresh AGENTS.md for antigravity ...`), the docs (`docs: list antigravity cli as a supported flat host`).
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+├── README.md                                                        ✏️ Docs link points at the Antigravity overview
+├── cli/scripts/smoke-antigravity.sh                                 ✏️ project hook proof, short header, portable script(1)
+├── cli/src/contexts/tools/domain/registry.ts                        ✏️ JSDoc keeps only the null case
+└── plugins/aidd-context/skills/
+    ├── 04-skill-generate/references/tool-detect.md                  ✏️ .agents/skills/ wording agrees with ai-mapping
+    ├── 05-rule-generate/references/tool-paths.md                    ✏️ glob with paths, always_on without; measured truncation
+    └── 11-explore/references/ai-mapping.md                          ✏️ plugins/ paths marked unmeasured; .agents/skills/ wording
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[pnpm smoke:antigravity] --> B[setup writes .agents/hooks.json]
+  B --> C[agy session]
+  C --> D{aidd-context hook loaded?}
+  D -- yes --> E[PASS]
+  D -- no, even with a global user hook --> F[FAIL]
+```
+
+## Test Scope
+
+```mermaid
+---
+title: Test scope
+---
+journey
+  section Setup
+    Logged-in agy, a temp workspace set up with aidd setup --ai antigravity => workspace ready: 5: system
+  section Happy path
+    Run the smoke => hooks loaded passes on the aidd-context project hook: 5: cli
+  section Edge case - project hooks removed
+    Delete .agents/hooks.json with a global user hook present => run the smoke => hooks loaded fails: 1: cli
+```
+
+## Tasks to do
+
+### `1)` Smoke proves the project hook
+
+> A global user hook can no longer make the check pass.
+
+1. Read what an `agy` log prints for loaded hooks; match `aidd-context` if it is named.
+2. Otherwise compare the loaded count with and without `.agents/hooks.json` and require it to be higher with it.
+3. Negative control: delete `.agents/hooks.json`, the check fails.
+4. Check whether a `-p` run fires the SessionStart hook; if it does, drop the interactive session part.
+5. Shorten the header; no pinned version; pick BSD or util-linux `script` syntax at runtime when the interactive part stays.
+
+### `2)` Docs precision
+
+> Each claim states what was measured and what was not.
+
+1. `tool-paths.md` (rules): a rule with paths is `trigger: glob` with `globs`, one without is `always_on`; the per-file limit is measured, `agy` truncates near 23 to 25 KB and `write-rule.cjs` refuses above 24,000 bytes.
+2. `ai-mapping.md`: `~/.gemini/config/plugins/<plugin>/` and `.agents/plugins/` marked unmeasured; `.agents/skills/` wording aligned with `tool-detect.md`.
+3. README Docs link to the Antigravity overview; `registry.ts` JSDoc reduced to the `null` case.
+
+### `3)` Pull request description
+
+> The description lists every code change it ships.
+
+1. Add the `write-rule.cjs` antigravity target (path, frontmatter, size refusal) to the description draft.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | The smoke passes with project hooks and fails without them, whatever the user-global hooks |
+| 2 | `ai-mapping.md` and `tool-detect.md` agree on `.agents/skills/`; rules docs name glob vs always_on and the measured truncation |
+| 3 | The description draft names the `write-rule.cjs` change |