@lifeaitools/rdc-skills 0.24.38 → 0.24.41

package/skills/fixit/SKILL.md

@@ -1,165 +1,165 @@
----
-name: rdc:fixit
-description: "Usage `rdc:fixit <description>` — Quick fix under 5 files / 30 min that does not warrant a full plan→build cycle. Creates a minimal work item, makes the change, commits, runs a mandatory code-review pass (pr-review-toolkit:code-reviewer), closes. The only sanctioned bypass of rdc:build."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`), then `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` (fallback: `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md`).
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
-
-
-# rdc:fixit — Sanctioned Quick Fix
-
-## When to Use
-- Typo or single-line text correction
-- Config value change (env vars, constants, feature flags)
-- Emergency hotfix that cannot wait for a full build cycle
-- Dependency version bump
-- CSS/styling tweak on a single component
-- Broken import or export fix
-- Single-file logic correction
-
-## When NOT to Use — escalate to rdc:build instead
-- New feature of any size
-- Refactor touching >5 files
-- Anything requiring architecture decisions
-- Work that will take longer than 30 minutes
-- Schema changes or migrations
-
-## Arguments
-- `rdc:fixit <description>` — fix the described issue
-
-## Procedure
-
-### 1. Scope check (mandatory — do this before touching any file)
-
-Will this fix touch more than **5 files** or take more than **30 minutes**?
-
-- **YES** → Stop. Use `/rdc:build` instead. Explain to the user why.
-- **NO** → Continue.
-
-### 2. Create a minimal work item (before touching any code)
-
-```sql
-SELECT insert_work_item(
-  p_title     := 'fixit: <description>',
-  p_item_type := 'bug',
-  p_priority  := 'urgent',
-  p_status    := 'in_progress',
-  p_source    := 'fixit'
-);
-```
-
-Note the returned `id`.
-
-### 3. Write the fixit session marker
-
-Write to `{USER_HOME}/.claude/fixit.marker`:
-```
-<work_item_id>
-<ISO timestamp>
-<description>
-```
-
-This signals the Stop hook that fixit is handling its own documentation.
-
-### 4. Make the fix
-
-Do the minimal work. Scope creep rule: if you discover the fix requires more than originally scoped, **stop immediately**:
-1. Close the work item: `update_work_item_status('<id>', 'blocked', '["Escalated — scope exceeded fixit threshold"]')`
-2. Delete the marker file
-3. Tell the user to use `/rdc:build` instead
-
-Apply `guides/engineering-behavior.md`: state material assumptions in the
-implementation report, avoid speculative abstractions, touch only required
-files, and verify behavior before moving the work item to `review`.
-
-### 5. Commit
-
-```bash
-git add <specific files only — never git add -A for a fixit>
-git commit -m "fix(<scope>): <description>"
-if [ "$RDC_TEST" != "1" ]; then
-  git push origin {development-branch}
-else
-  echo "[RDC_TEST] skipping git push origin {development-branch}"
-fi
-```
-
-### 5.5 Mandatory code-review gate (before submitting implementation report)
-
-⛔ **No fixit closes without a code-review pass.** Even single-file changes go through review.
-
-Dispatch ONE `pr-review-toolkit:code-reviewer` agent on the fixit commit:
-
-```
-Agent({
-  subagent_type: "pr-review-toolkit:code-reviewer",
-  description: "fixit code review",
-  prompt: "Review `git show HEAD` on the development branch. Focus on:
-           bugs, logic errors, security, project-convention adherence (.claude/rules/*).
-           Confidence-based filtering — high-confidence findings only.
-           Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
-           low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
-})
-```
-
-**Severity gate:**
-- `critical` or `high` findings → fix in this same fixit session (do not escalate to rdc:build for the fix itself; the original fixit owns the cleanup), re-commit, re-run review until clean
-- `medium` or `low` findings → record in `implementation_report.flags`; proceed to close
-- Zero findings → proceed to close
-
-Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.
-
-### 6. Close and clean up
-
-Submit implementation report first, move to review, then close as validator:
-
-```sql
-SELECT submit_implementation_report('<id>'::uuid,
-  '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[],"codeflow_post":{"agent_session_id":"<agent-session-id>","summary":"<what changed and why>","files_changed":["<path>"],"verification":["<command/evidence>"],"commit":"<hash optional>"}}'::jsonb
-);
-
-SELECT update_work_item_status('<id>'::uuid, 'review',
-  '["Fixed via rdc:fixit; ready for validation"]'::jsonb,
-  '<agent-session-id>',
-  'agent'
-);
-
-SELECT update_work_item_status('<id>'::uuid, 'done',
-  '["Validator verified rdc:fixit report, CodeFlow post, and checklist evidence"]'::jsonb,
-  '<validator-session-id>',
-  'validator'
-);
-```
-
-If the fix touched a transactional flow, API boundary, or package contract, set `"transactional": true` and populate `memory_records` (see `agent-bootstrap.md`), then run:
-```bash
-node scripts/work-item-memory.mjs <work-item-id>
-# Note: verify script exists first: ls {PROJECT_ROOT}/scripts/work-item-memory.mjs
-# If the script is absent, skip this step and note it in the implementation report.
-```
-
-```bash
-rm {USER_HOME}/.claude/fixit.marker
-```
-
-### 7. Confirm to user
-
-Report: what was fixed, file(s) changed, commit hash. One sentence.
-
-## Rules
-- Work item created BEFORE any code change — never after
-- `git add` specific files only — never `-A` or `.` for a fixit
-- Branch: development branch always
-- Never run `pnpm build` — not needed for a fixit
-- If scope expands mid-fix: stop, escalate to rdc:build, don't finish under fixit
-- Marker file must be cleaned up whether fix succeeds or escalates
-
-## Capture lessons (exit step)
-
-Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-fixit-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.
+---
+name: rdc:fixit
+description: "Usage `rdc:fixit <description>` — Quick fix under 5 files / 30 min that does not warrant a full plan→build cycle. Creates a minimal work item, makes the change, commits, runs a mandatory code-review pass (pr-review-toolkit:code-reviewer), closes. The only sanctioned bypass of rdc:build."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`), then `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` (fallback: `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md`).
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
+
+
+# rdc:fixit — Sanctioned Quick Fix
+
+## When to Use
+- Typo or single-line text correction
+- Config value change (env vars, constants, feature flags)
+- Emergency hotfix that cannot wait for a full build cycle
+- Dependency version bump
+- CSS/styling tweak on a single component
+- Broken import or export fix
+- Single-file logic correction
+
+## When NOT to Use — escalate to rdc:build instead
+- New feature of any size
+- Refactor touching >5 files
+- Anything requiring architecture decisions
+- Work that will take longer than 30 minutes
+- Schema changes or migrations
+
+## Arguments
+- `rdc:fixit <description>` — fix the described issue
+
+## Procedure
+
+### 1. Scope check (mandatory — do this before touching any file)
+
+Will this fix touch more than **5 files** or take more than **30 minutes**?
+
+- **YES** → Stop. Use `/rdc:build` instead. Explain to the user why.
+- **NO** → Continue.
+
+### 2. Create a minimal work item (before touching any code)
+
+```sql
+SELECT insert_work_item(
+  p_title     := 'fixit: <description>',
+  p_item_type := 'bug',
+  p_priority  := 'urgent',
+  p_status    := 'in_progress',
+  p_source    := 'fixit'
+);
+```
+
+Note the returned `id`.
+
+### 3. Write the fixit session marker
+
+Write to `{USER_HOME}/.claude/fixit.marker`:
+```
+<work_item_id>
+<ISO timestamp>
+<description>
+```
+
+This signals the Stop hook that fixit is handling its own documentation.
+
+### 4. Make the fix
+
+Do the minimal work. Scope creep rule: if you discover the fix requires more than originally scoped, **stop immediately**:
+1. Close the work item: `update_work_item_status('<id>', 'blocked', '["Escalated — scope exceeded fixit threshold"]')`
+2. Delete the marker file
+3. Tell the user to use `/rdc:build` instead
+
+Apply `guides/engineering-behavior.md`: state material assumptions in the
+implementation report, avoid speculative abstractions, touch only required
+files, and verify behavior before moving the work item to `review`.
+
+### 5. Commit
+
+```bash
+git add <specific files only — never git add -A for a fixit>
+git commit -m "fix(<scope>): <description>"
+if [ "$RDC_TEST" != "1" ]; then
+  git push origin {development-branch}
+else
+  echo "[RDC_TEST] skipping git push origin {development-branch}"
+fi
+```
+
+### 5.5 Mandatory code-review gate (before submitting implementation report)
+
+⛔ **No fixit closes without a code-review pass.** Even single-file changes go through review.
+
+Dispatch ONE `pr-review-toolkit:code-reviewer` agent on the fixit commit:
+
+```
+Agent({
+  subagent_type: "pr-review-toolkit:code-reviewer",
+  description: "fixit code review",
+  prompt: "Review `git show HEAD` on the development branch. Focus on:
+           bugs, logic errors, security, project-convention adherence (.claude/rules/*).
+           Confidence-based filtering — high-confidence findings only.
+           Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
+           low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
+})
+```
+
+**Severity gate:**
+- `critical` or `high` findings → fix in this same fixit session (do not escalate to rdc:build for the fix itself; the original fixit owns the cleanup), re-commit, re-run review until clean
+- `medium` or `low` findings → record in `implementation_report.flags`; proceed to close
+- Zero findings → proceed to close
+
+Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.
+
+### 6. Close and clean up
+
+Submit implementation report first, move to review, then close as validator:
+
+```sql
+SELECT submit_implementation_report('<id>'::uuid,
+  '{"tldr":"<one sentence>","assumptions":[],"deviations":[],"uncertainty":[],"detail":"<what was fixed>","flags":[],"transactional":false,"memory_records":[],"codeflow_post":{"agent_session_id":"<agent-session-id>","summary":"<what changed and why>","files_changed":["<path>"],"verification":["<command/evidence>"],"commit":"<hash optional>"}}'::jsonb
+);
+
+SELECT update_work_item_status('<id>'::uuid, 'review',
+  '["Fixed via rdc:fixit; ready for validation"]'::jsonb,
+  '<agent-session-id>',
+  'agent'
+);
+
+SELECT update_work_item_status('<id>'::uuid, 'done',
+  '["Validator verified rdc:fixit report, CodeFlow post, and checklist evidence"]'::jsonb,
+  '<validator-session-id>',
+  'validator'
+);
+```
+
+If the fix touched a transactional flow, API boundary, or package contract, set `"transactional": true` and populate `memory_records` (see `agent-bootstrap.md`), then run:
+```bash
+node scripts/work-item-memory.mjs <work-item-id>
+# Note: verify script exists first: ls {PROJECT_ROOT}/scripts/work-item-memory.mjs
+# If the script is absent, skip this step and note it in the implementation report.
+```
+
+```bash
+rm {USER_HOME}/.claude/fixit.marker
+```
+
+### 7. Confirm to user
+
+Report: what was fixed, file(s) changed, commit hash. One sentence.
+
+## Rules
+- Work item created BEFORE any code change — never after
+- `git add` specific files only — never `-A` or `.` for a fixit
+- Branch: development branch always
+- Never run `pnpm build` — not needed for a fixit
+- If scope expands mid-fix: stop, escalate to rdc:build, don't finish under fixit
+- Marker file must be cleaned up whether fix succeeds or escalates
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-fixit-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `lesson_status: open`; weekly triage alone records a final lesson outcome. Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/fs-mcp/SKILL.md

@@ -1,148 +1,148 @@
----
-name: rdc:fs-mcp
-description: "Usage `rdc:fs-mcp <task>` — Use the File System MCP bridge for live repo reads, safe writes, cloud-to-local ingest, and GitHub-branch imports into a dirty local monorepo. Use when Claude.ai, Cowork, or CLI agents need fs_read/fs_write/fs_import_git_files guidance."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-
-# rdc:fs-mcp — File System MCP Bridge
-
-## When to Use
-- Claude.ai, Cowork, or another remote surface needs live access to `{PROJECT_ROOT}` through the File System MCP.
-- You need to read, search, or list current local repo files without relying on GitHub freshness.
-- You need to write a small/scratch file through FS MCP.
-- You need to move a larger cloud file into the local repo.
-- Claude.ai created a durable new docs/corpus file on a GitHub branch and local dev needs to import it into a dirty monorepo.
-
-## Arguments
-- `rdc:fs-mcp read` — choose the right read/search/list tool.
-- `rdc:fs-mcp write` — choose direct write, chunked write, append, or URL ingest.
-- `rdc:fs-mcp import-git` — import named files from a GitHub branch/commit into local dev.
-- `rdc:fs-mcp status` — inspect mounts and repo state before deciding.
-
-## Procedure
-
-### 1. Identify the file intent
-
-Classify the file before writing:
-
-| Intent | Default path | Default action |
-|---|---|---|
-| Live repo read | Existing repo path | `fs_read`, `fs_grep`, `fs_glob`, `fs_list` |
-| Small scratch or relay file | `.rdc/relay/`, `.codex/tmp/`, agreed temp path | `fs_write` |
-| Large text file from the current chat | Target path | `fs_write_chunk` |
-| Cloud-hosted file | Target path | `fs_ingest_url` |
-| Durable new docs/corpus file from Claude.ai | Actual target path in `docs/**`, `.rdc/plans/**`, `.claude/context/**` | GitHub branch commit, then `fs_import_git_files` |
-| Existing file update | Existing repo path | Prefer patch/review workflow; do not overwrite unless explicitly requested |
-
-### 2. Read/search from live local FS
-
-Use FS MCP first for local state:
-
-```text
-fs_read CLAUDE.md
-fs_glob docs/**/*.md
-fs_grep "bridge mode" docs/
-fs_list .rdc/relay/from-claude-code/
-```
-
-Use GitHub for remote branch/file history, PRs, and durable publication. Use FS for the current local worktree.
-
-### 3. Choose the safest write surface
-
-Use direct FS writes only when the payload is small and the destination is clear:
-
-```text
-fs_write path=".rdc/relay/from-claude-ai/<timestamp>-topic.md"
-```
-
-Use chunked writes for larger text:
-
-```text
-fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=0 total_chunks=3 content="..."
-fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=1 total_chunks=3 content="..."
-fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=2 total_chunks=3 content="..."
-```
-
-Use URL ingest when the file already exists in cloud storage:
-
-```text
-fs_ingest_url url="https://..." path="docs/source/file.md" expected_sha256="<optional>"
-```
-
-### ⛔ Ingest discipline (lesson 2026-06-16-collab-claudeai-fs-ingest-race-and-preview-pollution)
-
-- **Prefer synchronous `fs_write` over `fs_ingest_url` for commit-bound bytes.**
-  `fs_ingest_url` can return before the bytes have landed on disk; a `git add`
-  immediately after races the download and silently stages nothing. If you MUST
-  use `fs_ingest_url` for content you will commit, `fs_stat`-poll the target path
-  until size/hash is stable BEFORE staging or committing.
-- **A silent `git add` skip is NOT gitignore.** If `git add <path>` adds nothing
-  and the file is not obviously ignored, do not assume `.gitignore` — confirm with
-  `git check-ignore -v <path>`. No output means it is NOT ignored, so the real
-  cause is a missing/empty/racing file, not an ignore rule.
-- **Never ingest claude.ai preview / Artifacts URLs.** URLs like
-  `*.claude.ai/.../preview` or Artifact render endpoints serve a wrapped,
-  data-omelette-injected document (host chrome, sanitizer rewrites, injected
-  markers) — not the clean source bytes. Ingesting them pollutes the repo. Get
-  the durable source via the GitHub-branch import path (§4) instead.
-
-Use guarded append when appending to a known file:
-
-```text
-fs_stat path="docs/plans/foo.md"
-fs_append path="docs/plans/foo.md" content="\n..." expected_sha256="<hash from fs_stat>"
-```
-
-### 4. Import durable new files from GitHub instead of large FS writes
-
-When Claude.ai creates a durable new docs/corpus file, publish it to a GitHub branch first, then ask FS MCP to import the exact file path.
-
-Required Claude.ai handoff shape:
-
-```json
-{
-  "repo": "<owner>/<repo>",
-  "remote": "origin",
-  "ref": "claude-ai/docs-upload-123",
-  "paths": ["docs/plans/foo.md"],
-  "mode": "new_only",
-  "commit": true,
-  "message": "docs(plans): add foo"
-}
-```
-
-Then call:
-
-```text
-fs_import_git_files remote="origin" ref="claude-ai/docs-upload-123" paths=["docs/plans/foo.md"] mode="new_only" commit=true message="docs(plans): add foo"
-```
-
-This tool must fetch only, restore only named paths, optionally commit only those paths, and never push.
-
-### 5. Safety rules
-
-- Never run or request `git pull` for the dirty monorepo.
-- Never checkout a whole branch into the local worktree.
-- For durable docs/corpus, save to the actual target path, not an upload folder, when the target is known.
-- Use upload/incoming folders only when the final destination is unknown.
-- Default to `new_only` for Git imports.
-- Refuse overwrites unless the user explicitly asks for overwrite/update behavior.
-- Stage only imported paths when committing.
-- Never push from FS import unless the user explicitly asks for a push-capable workflow.
-
-### 6. Completion report
-
-Report:
-
-```text
-FS MCP: <read/write/import> complete
-Paths: <paths>
-Source ref/commit: <if Git import>
-Local commit: <if committed>
-Verification: <fs_stat/hash or import result>
-Blocked/conflicts: <none or list>
-```
+---
+name: rdc:fs-mcp
+description: "Usage `rdc:fs-mcp <task>` — Use the File System MCP bridge for live repo reads, safe writes, cloud-to-local ingest, and GitHub-branch imports into a dirty local monorepo. Use when Claude.ai, Cowork, or CLI agents need fs_read/fs_write/fs_import_git_files guidance."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+
+# rdc:fs-mcp — File System MCP Bridge
+
+## When to Use
+- Claude.ai, Cowork, or another remote surface needs live access to `{PROJECT_ROOT}` through the File System MCP.
+- You need to read, search, or list current local repo files without relying on GitHub freshness.
+- You need to write a small/scratch file through FS MCP.
+- You need to move a larger cloud file into the local repo.
+- Claude.ai created a durable new docs/corpus file on a GitHub branch and local dev needs to import it into a dirty monorepo.
+
+## Arguments
+- `rdc:fs-mcp read` — choose the right read/search/list tool.
+- `rdc:fs-mcp write` — choose direct write, chunked write, append, or URL ingest.
+- `rdc:fs-mcp import-git` — import named files from a GitHub branch/commit into local dev.
+- `rdc:fs-mcp status` — inspect mounts and repo state before deciding.
+
+## Procedure
+
+### 1. Identify the file intent
+
+Classify the file before writing:
+
+| Intent | Default path | Default action |
+|---|---|---|
+| Live repo read | Existing repo path | `fs_read`, `fs_grep`, `fs_glob`, `fs_list` |
+| Small scratch or relay file | `.rdc/relay/`, `.codex/tmp/`, agreed temp path | `fs_write` |
+| Large text file from the current chat | Target path | `fs_write_chunk` |
+| Cloud-hosted file | Target path | `fs_ingest_url` |
+| Durable new docs/corpus file from Claude.ai | Actual target path in `docs/**`, `.rdc/plans/**`, `.claude/context/**` | GitHub branch commit, then `fs_import_git_files` |
+| Existing file update | Existing repo path | Prefer patch/review workflow; do not overwrite unless explicitly requested |
+
+### 2. Read/search from live local FS
+
+Use FS MCP first for local state:
+
+```text
+fs_read CLAUDE.md
+fs_glob docs/**/*.md
+fs_grep "bridge mode" docs/
+fs_list .rdc/relay/from-claude-code/
+```
+
+Use GitHub for remote branch/file history, PRs, and durable publication. Use FS for the current local worktree.
+
+### 3. Choose the safest write surface
+
+Use direct FS writes only when the payload is small and the destination is clear:
+
+```text
+fs_write path=".rdc/relay/from-claude-ai/<timestamp>-topic.md"
+```
+
+Use chunked writes for larger text:
+
+```text
+fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=0 total_chunks=3 content="..."
+fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=1 total_chunks=3 content="..."
+fs_write_chunk upload_id="<stable-id>" path="docs/plans/foo.md" chunk_index=2 total_chunks=3 content="..."
+```
+
+Use URL ingest when the file already exists in cloud storage:
+
+```text
+fs_ingest_url url="https://..." path="docs/source/file.md" expected_sha256="<optional>"
+```
+
+### ⛔ Ingest discipline (lesson 2026-06-16-collab-claudeai-fs-ingest-race-and-preview-pollution)
+
+- **Prefer synchronous `fs_write` over `fs_ingest_url` for commit-bound bytes.**
+  `fs_ingest_url` can return before the bytes have landed on disk; a `git add`
+  immediately after races the download and silently stages nothing. If you MUST
+  use `fs_ingest_url` for content you will commit, `fs_stat`-poll the target path
+  until size/hash is stable BEFORE staging or committing.
+- **A silent `git add` skip is NOT gitignore.** If `git add <path>` adds nothing
+  and the file is not obviously ignored, do not assume `.gitignore` — confirm with
+  `git check-ignore -v <path>`. No output means it is NOT ignored, so the real
+  cause is a missing/empty/racing file, not an ignore rule.
+- **Never ingest claude.ai preview / Artifacts URLs.** URLs like
+  `*.claude.ai/.../preview` or Artifact render endpoints serve a wrapped,
+  data-omelette-injected document (host chrome, sanitizer rewrites, injected
+  markers) — not the clean source bytes. Ingesting them pollutes the repo. Get
+  the durable source via the GitHub-branch import path (§4) instead.
+
+Use guarded append when appending to a known file:
+
+```text
+fs_stat path="docs/plans/foo.md"
+fs_append path="docs/plans/foo.md" content="\n..." expected_sha256="<hash from fs_stat>"
+```
+
+### 4. Import durable new files from GitHub instead of large FS writes
+
+When Claude.ai creates a durable new docs/corpus file, publish it to a GitHub branch first, then ask FS MCP to import the exact file path.
+
+Required Claude.ai handoff shape:
+
+```json
+{
+  "repo": "<owner>/<repo>",
+  "remote": "origin",
+  "ref": "claude-ai/docs-upload-123",
+  "paths": ["docs/plans/foo.md"],
+  "mode": "new_only",
+  "commit": true,
+  "message": "docs(plans): add foo"
+}
+```
+
+Then call:
+
+```text
+fs_import_git_files remote="origin" ref="claude-ai/docs-upload-123" paths=["docs/plans/foo.md"] mode="new_only" commit=true message="docs(plans): add foo"
+```
+
+This tool must fetch only, restore only named paths, optionally commit only those paths, and never push.
+
+### 5. Safety rules
+
+- Never run or request `git pull` for the dirty monorepo.
+- Never checkout a whole branch into the local worktree.
+- For durable docs/corpus, save to the actual target path, not an upload folder, when the target is known.
+- Use upload/incoming folders only when the final destination is unknown.
+- Default to `new_only` for Git imports.
+- Refuse overwrites unless the user explicitly asks for overwrite/update behavior.
+- Stage only imported paths when committing.
+- Never push from FS import unless the user explicitly asks for a push-capable workflow.
+
+### 6. Completion report
+
+Report:
+
+```text
+FS MCP: <read/write/import> complete
+Paths: <paths>
+Source ref/commit: <if Git import>
+Local commit: <if committed>
+Verification: <fs_stat/hash or import result>
+Blocked/conflicts: <none or list>
+```