/drive-filing — filing, archival, and the docs.local lifecycle

One skill for everything that moves durable artifacts out of docs.local/ (formerly drive-usage, google-drive-archive, and the archive skill). Named drive-filing, not brain-drive, so it is not one hyphen away from /braindrive (the Gemini Drive query command).

Etan's pain: agents (except researchers) don't use Drive right and leave artifacts scattered in docs.local/. This skill makes filing automatic. Rule of thumb: if an artifact should outlive this session, file it by § Machine hygiene: code and harnesses in a repo, personal or client documents in iCloud, other durable artifacts in the RIGHT Brain Drive folder — docs.local/ is a cache, not a home.

Not this skill: /braindrive queries Drive via Gemini; /gemini-research does web research with Drive sources.

Brain Drive folder model

Folder IDs are private deployment values. Resolve them from the environment or private operator configuration; never copy live Drive IDs into this skill.

Folder semantics (what each numbered folder means) are confirmed with brainlayer-LEAD (s:57, owns Drive/backup). Legacy non-numbered folders (Research ×2 duplicates, Sessions, Collabs, _inbox-*, BrainBar Design Audit) are pre-taxonomy scatter — do not add to them; file into the numbered model. (Consolidation of the legacy dupes is an s:57 cleanup task.)

Legacy Brain Drive/Research/<project>/ folders are being moved under 03_RESEARCH/Active; if a prompt isn't found in Active, check the legacy path read-only and report it, never write there.

Decision tree (where does THIS artifact go?)

1. A research prompt or its results? → 03_RESEARCH/Active/<topic>/ (e.g. skills-eval/). Drive-ground prompts by uploading the real artifacts beside them.
2. A finished heavy artifact (>100KB / media / raw transcript / big audit)? → § Archive a heavy artifact → lands in 06_ARCHIVE/<area>/<topic>/<YYYY-MM-DD>/, leaves a _DRIVE-LEDGER.md pointer in docs.local/.
3. A canonical standard / spec / locked schema? → 01_STANDARDS/.
4. Grounding corpus / reference data? → 02_GROUNDING/.
5. Raw, not-yet-digested inbound? → 04_INGEST/.
6. Lightweight, session-scoped scratch? → fine to leave in docs.local/ — but if anyone else (or future-you) needs it, FILE it per 1–5.

Naming convention

New standalone artifacts: YYYY-MM-DD-<project>-<topic>-<kind>[-by-<producer>].<ext>, lowercase kebab-case. Example: 2026-11-04-voicebar-focus-audit-by-author.md. Topic must describe the work; Theo.md, Model.md and 2026-11-04-golems-theo-report.md fail. Put a person/model attribution in by-<producer> (exactly one lowercase token), never in the project, topic or kind slots. Kinds: report, prompt, result, transcript, recording, audit, plan, review, frame, image, notes, receipt, manifest, data, archive, index, dashboard, summary, eval, log.

Before uploading a new standalone artifact, set GOLEMS_ROOT to the absolute golems checkout (normally $HOME/Gits/golems) and run node "$GOLEMS_ROOT/scripts/drive/lint-name.mjs" <basename> from any repo; nonzero blocks filing until renamed. Existing files and preserved archive members (including MANIFEST.json and frame names) are grandfathered: --existing reports issues without blocking or renaming. Research-lifecycle's sequential context/R-number names keep their own contract. Folders retain <topic>-<domain>/; keep local mirror and Drive names identical for 1:1 ledger mapping.

Verify the ledger after uploads

Use one bullet per file: - <local path> → Brain Drive/<exact path>/<name> | bytes=<integer> | SHA256=<64 hex> | account=<expected-email> | cloud=pending. SHA256 is mandatory: missing or invalid hashes are malformed rows. Bare Brain Drive/ paths require account=<expected-email>; mount paths derive it from GoogleDrive-<account> (an explicit account, if provided, must agree). Record hashes from the source manifest; metadata such as Drive ID/URL and manifest pointer may follow as extra pipe fields. Absolute Drive-for-Desktop paths containing /My Drive/Brain Drive/ are also accepted. Old Markdown tables remain readable history; add a machine-readable pending row for verification.

GOLEMS_ROOT="${GOLEMS_ROOT:-$HOME/Gits/golems}"
node "$GOLEMS_ROOT/scripts/drive/verify-ledger.mjs" <ledger.md>            # dry-run; no ledger write
node "$GOLEMS_ROOT/scripts/drive/verify-ledger.mjs" <ledger.md> --apply    # only verified rows change

Run after each upload batch from any repo using the absolute GOLEMS_ROOT. The token has full Drive scope; the verifier only reads, using GET requests through the existing outside-repo OAuth guard. It checks the recorded account for every path, resolves every exact path (duplicates fail), compares bytes and the mandatory recorded SHA-256 (downloads remote bytes if Drive omits the checksum), and alone writes cloud=verified <ISO timestamp>. A local mount/cache is not sync proof. Missing, malformed, mismatched or unauthenticated rows remain pending with a reason on stdout; exit 1 means some rows remain, exit 2 is usage/ledger failure. Names in old rows are report-only. --apply is idempotent and never uploads or deletes. Deletion still requires the full preservation and authorization gates below.

Machine hygiene: no ad-hoc home folders

Applies to both Macs. Each kind of artifact has one home:

Naming and manifests. Local scratch/lane folder names use YYYY-MM-DD-<topic> in lowercase kebab-case, without machine prefixes (m1-*) or retired names (Ralph). Drive placement follows the existing layout above and the rollup targets below, including their <YYYY-MM> units; this local folder rule does not rename Drive archive units.

Every archive unit carries MANIFEST.json with:

• Source path and host.
• Byte count and SHA-256 for each file.
• Producer (lead thread or plan).
• Restore command.

Schema and measurement commands: references/archiving-convention.md.

Five rules:

1. Agents create no ad-hoc folders in ~/ or ~/Desktop. Use sanctioned T3 scratch or repo docs.local/ scratch under the workspace lifecycle contract.
2. Delete a local archive copy only after the Drive or iCloud copy exists, manifest hashes match verified remote bytes, and a one-file restore drill succeeds. A matching name or folder listing is insufficient. Keep the ledger and preservation proof outside any retiring scope; follow the archive procedure and lifecycle contract for their additional verification gates.
3. Measure disk recovery with diskutil container free space and APFS allocation. Finder free space includes purgeable space; logical du sums do not prove physical recovery. Record the host and before/after measurements.
4. Leads reap their own lane leftovers at settle, after harvesting and releasing consumers under the lifecycle contract. Unowned leftovers go to the local-files lead's per-Mac ledger; never silently delete them.
5. Deleting data remains a one-way door. Reviewed empty directories may be removed with rmdir. Nonempty data needs an identified owner, verified preservation and Etan's explicit instruction for that deletion, or a door he already opened for that work (quote his authorization). A lead's own call is insufficient; archive proof alone grants no deletion authority.

Enforcement follow-up (not implemented by this section): add a report-only inventory check for new agent-created top-level ~/ and ~/Desktop directories (uid 501, recent birthtime, patterns such as m1-*, vlv* / .vl*, vl-harness* copies and BrainLayer-*). These are investigation signals, not ownership or deletion proof. The local-files lead must register and link the M4 Max and M1 Pro ledgers here once their canonical locations are confirmed; until then, report unowned leftovers to that lead. Never infer a ledger path or add a destructive home-wide reaper.

The discipline (the one rule)

Before you finish a task that produced a durable artifact: did you FILE it in its home, or leave it scattered in docs.local/? Use the § Machine hygiene table: code and harnesses go to a repo, personal or client documents to iCloud, other durable artifacts to the right Brain Drive folder. If durable and still only local → file it now (the decision tree above, or § Archive a heavy artifact) and drop a one-line _DRIVE-LEDGER.md pointer. "It's in docs.local" is not "it's saved."

Quick reference (MCP)

• Upload: mcp__google-drive__uploadFile(localPath, parentFolderId=<resolved private ID>). For text, pass mimeType from the extension (.md → text/markdown, .txt → text/plain, .json → application/json); a .md starting with <!-- otherwise lands as text/html.
• New topic folder: mcp__google-drive__createFolder(name, parent=<resolved private ID>).
• Find: mcp__google-drive__search(query="'<RESOLVED_PRIVATE_PARENT_ID>' in parents", rawQuery=true).
• Heavy/forever: § Archive a heavy artifact.

Archive a heavy artifact

Full procedure: references/archive-procedure.md (was /google-drive-archive). Fire it on "save this to Drive", "archive this", "put this in the archive", a >100KB write to docs.local/{research,audits,plans}/, a post-brain_digest raw file, or a /tmp cleanup that may hold forever-knowledge. The eight steps, in short:

1. Ephemeral or forever? Only originals go up; list regeneratable derivatives and how to rebuild them. Not archiving a file grants no deletion authority; apply § Machine hygiene rule 5.
2. Resolve Brain Drive/06_ARCHIVE/<area>/<topic>/<YYYY-MM-DD>[-<tag>]/ (research, audits, plans, repos, voice); mcp__google-drive__search for precedent first.
3. createFolder per level, keeping every ID. 4. uploadFile; keep id, link, size.
4. brain_digest every text file (a background agent for >150KB).
5. Write docs.local/<area>/<topic>/_DRIVE-LEDGER.md (never committed) with pending rows, then run § Verify the ledger after uploads. Never mark rows verified by hand.
6. Write the ledger, then apply § Machine hygiene rules 2 and 5 as the single deletion gate: manifest hashes must match verified archive bytes, a one-file restore test must pass, and Etan must authorize deletion (or have already opened that door for this work, quoted). A listFolder result and ledger alone never authorize deletion.
7. brain_store unusual archive decisions only.

Never: commit a 1.5GB transcript, rm -rf /tmp/… before the forever check, digest without uploading, upload without a ledger row, re-upload what Drive already has.

docs.local lifecycle

Monthly qa-video archive

Job monthly-qa-video-drive-archive: first day of each month, Asia/Jerusalem, ONLY on the skill-creator lead's scheduling child (seat/role resolution: /agent-routing). The lead creates it after merge. Exact scheduled command: node "$HOME/Gits/golems/scripts/drive/archive-qa-video.mjs" --apply. Never add pruning to the scheduled command.

Configure ~/.config/golems/qa-video-archive.json outside repos: {"account":"<expected-email>","repos":[{"path":"<absolute-repo-root>","owner":"<producer>","harvestedRuns":["<completed-run-name>"]}]}. The scheduled job reports a missing config path and these required fields on stderr (exit 2). Before activation, create the config and run a configured --dry-run with eligible runs. Owners register only harvested runs; unknown ownership/harvest state stays held. Default command (or --dry-run) reports counts/bytes without writes or Drive calls. For unconfigured read-only inventory, repeat --repo <absolute-repo-root> with --dry-run; those units remain held until owners register them. --apply uploads preserved members plus MANIFEST.json to Brain Drive/06_ARCHIVE/docs-local/<repo>/qa-video/<YYYY-MM>/<run>/, writes pending member rows, restores one image (or a member if no image), checks its bytes/hash, then runs the verifier. Existing members and MANIFEST.json keep their names. No derivative is omitted.

Old means newest member mtime before the first day of the preceding calendar month (Asia/Jerusalem month); current/previous months stay local. Producer holds (active, pinned, hold, latest, partial, unharvested), credentials/content scans, symlinks, unknown ownership and regenerable directories hold the whole run. Manifests and the ledger stay outside the run. Re-runs reuse matching remote files/rows; conflicts stop. The existing outside-repo OAuth guard provides authentication; never call op. The token has full scope; image fetch uses only GETs.

Local pruning is optional, never implied by archive success: only --apply --prune-verified, with ownership and explicit deletion authority under Machine hygiene rule 5, may remove unchanged members after every row is verified, every remote hash matches and a restore drill passes. It preserves the ledger/manifests; logical bytes are not physical disk recovery. An existing .archive-lock holds only that repo; other repos continue. The job names the lock on stderr and exits nonzero. Confirm no archive process is active, then clear only the empty lock directory with rmdir and rerun; never automatically delete it. Pending counts include each remaining ledger row once across runs. Pruning removes empty nested directories; any newly nonempty directories remain intact without a cleanup error.

For a missing cited image, use node "$HOME/Gits/golems/scripts/drive/fetch-qa-image.mjs" <ledger.md> <original-image-path>; it restores exact verified ledger bytes into ~/.cache/qa-video/, reports the Drive path/ID/URL/hash, and never changes Drive or the ledger. Open that returned image before making a visual claim; ambiguity, missing bytes or hash/auth failure stays NOT DETERMINED.

docs.local/ stays legible, "not just walls of MD files": daily items (YYYY-MM-DD-*) roll up into monthly folders (YYYY-MM/), and months older than N go to Brain Drive through § Archive a heavy artifact, with a _DRIVE-LEDGER.md pointer left behind. /fleet-wrap is to run it at sprint close (skillcreator owns that call site; golems owns this skill).

node "$GOLEMS_ROOT/skills/golem-powers/drive-filing/scripts/rollup.mjs" --repo <path> --keep-months N            # dry-run (default): report only
node "$GOLEMS_ROOT/skills/golem-powers/drive-filing/scripts/rollup.mjs" --repo <path> --keep-months N --json     # the full plan
node "$GOLEMS_ROOT/skills/golem-powers/drive-filing/scripts/rollup.mjs" --repo <path> --keep-months N --apply    # month moves + plan file

The last stdout line is the one-line summary /fleet-wrap records: drive-filing rollup: mode=… files=… bytes=… · monthly-moves=… · to-drive months=… files=… bytes=… · mtime-units=… bytes=… · held=… credentials-skipped=…. Dating (v2): an item's month is the first YYYY-MM-DD anywhere in its own name, else the first YYYY-MM (examplechannel-2026-09-19-015034/, probe-2026-03/); an exact YYYY-MM/ folder is the month itself. An undated folder with a dated name somewhere below it is an area and is descended. An undated folder with none is one mtime unit (the highest such folder), dated by the newest file inside; it joins the upload plan once old but is never moved; its planned Drive target keeps its own path (…/<repo>/<area>/<unitName>, no month segment: it mirrors the unmoved local path), so no two units share a target. At upload, an mtime unit gets a date level: …/<repo>/<area>/<unitName>/<YYYY-MM-DD>/, dated by its newest file (the date the plan used), recorded in the ledger and its MANIFEST.json. --json lists the 5 largest under mtimeUnits. A unit with no files or only empty ones is counted (empty-units=) and never planned. Undated files are counted and left alone. Regenerable dirs (__pycache__, node_modules, .venv, venv, .pytest_cache, .mypy_cache, .ruff_cache, .build, .next, .turbo, .probe) are never planned, never an mtime unit and never deleted; each is reported once as skipped: regenerable <path>/ with its size, and the summary adds regenerable-skipped=N bytes=B. A credential inside one still wins (the dir is held). A month rolls up once it is over; months more than N back form the upload plan, one unit per folder, targeting Brain Drive/06_ARCHIVE/docs-local/<repo>/<area>/<YYYY-MM> (the one named exception to the YYYY-MM-DD date level: a rollup unit is a month). --apply moves items into their month folders (never overwriting; a clash is reported as conflict:) and first saves immutable docs.local/_drive-filing/rollup-plan-<date>-<uuid>.json intent. A separate rollup-progress-<date>-<uuid>.json records source/destination locations (both during a move). Reruns reconcile file identities before publishing rollup-handoff-<date>-<uuid>.json (planFile in --json); conflicting or missing files stop with a progress path. Earlier plans stay intact. The script never uploads or deletes. Newly held sources remain in place as not-moved with a reason. Safety checks run before the first move. After the handoff is saved, completion markers keep settled intents out of future reads. With no moves or unfinished intents, --apply writes nothing and prints the current inventory (--json has no planFile). Human output names a saved handoff before its final summary. Receipts store absolute paths: resume at the same repo path. Upload exactly the files in that handoff through the archive procedure (ledger + brain_digest), and nothing that is not in it. The plan is not a manifest (it lists paths and sizes, with no hashes, host, producer or restore command): until rollup.mjs emits one, write each unit's MANIFEST.json by hand before its upload and upload it with the unit.

Credentials never move. Nothing whose name contains credential, secret, token or .env (.env*, deploy.env, .ENV.prod, .envrc) or has env as a word (prod-env.json, app-env.yml, staging_env), or ends in auth.json, .pem or .key — file or directory — and nothing under a codexhome/codex-home*, claudehome/claude-home*, .codex, .claude or *-HOME* directory or a browser profile (a dir holding Local State, Cookies, Login Data or Web Data), is uploaded, moved or deleted. Every name rule matches anywhere in the name, case-insensitively, because docs.local names are date-prefixed. token releases only proven-safe words: tokeniz*, design-token(s) and Trust Tokens are stripped first, so tokenizer-remap.md passes and github_token_tokenizer.txt does not (a browser profile is still held whole). Holds run before dating. rollup.mjs enforces this in code: each credential is reported as skipped: credential <path> (a credential directory is one line plus its credential-named files), and a month group (the YYYY-MM/ folder plus that month's dated siblings in the same folder) that holds one is held whole: no moves into or out of it, no upload unit. It is reported once as held: contains credentials <path> with its items and credentials listed under it. Content scan (B1). Every file the plan would move or upload is read (text only, in overlapping 1 MiB chunks; a file with a NUL in its first chunk counts as binary and is skipped) for high-confidence secret shapes: Supabase sbp_, Google AIza, GitHub gh[pousr]_ / github_pat_, OpenAI sk-, AWS AKIA, Slack xox?-, and PEM private-key headers. A hit holds the whole month group as held: credential-content <path>, listing content: <file> (<shape>). A matched value is never kept, logged or printed. The summary adds content-held=N. Cleaning them up is the owner's call.

After creating/editing this skill it must be REGISTERED (golem-install / symlink into ~/.claude/skills) before any agent can invoke it — committed ≠ installed.