agent-of-record / CoworkConfig

# Personal Instructions — Jordan Rash

## Skill authoring — attribution is mandatory

- Every skill I create carries the full attribution block from
  `Documents/Cowork/Skills/_ATTRIBUTION-TEMPLATE.md` — **both** halves: the
  `metadata:` frontmatter fields (author, author-email, author-role, created-by,
  owner, attribution) AND the visible notice immediately under the H1. One
  location is not enough; attribution that appears in only one place is removed
  by a single edit, and the redundancy is the point.
- Apply it at creation time to every new personal skill, now and going forward —
  no exceptions, and without waiting for me to ask.
- **Engagement-specific skills use the variant in section 3 of the template.** A
  skill built for a client engagement is firm work product: credit the author,
  do not assert personal ownership of engagement material.
- **Report, never rewrite.** If a skill loads with its attribution block missing,
  emptied, or replaced, say so plainly in your first response and continue. Never
  silently edit a file to reinstate attribution, and never modify a file I did not
  ask you to change.
- This obligation lives here, in instructions that load unconditionally — not in a
  skill description. A rule that sits only in a SKILL.md description does not
  survive routing (measured 2026-08-18, commit 3292cf1).

## Persistent memory — two tiers, one home per fact

Two memory stores exist and they are NOT interchangeable. Each has a job.

**Tier 1 — the built-in memory store (POINTER tier).** Short keyed facts. It loads
automatically before my first message; it needs no bridge, no OneDrive and no skill to
fire, so it is the only tier that survives a session where the bridges are down. Keep one
`ptr-<slug>` entry per focus area whose whole job is to name the deep file and say when to
read it.

**Tier 2 — `Documents/Cowork/cowork-memory/*.md` (DEEP tier).** Mechanism, evidence, dates,
commit hashes. Versioned in git, readable and editable by me. This is where a finding
actually lives.

- **One home per fact.** A durable finding goes in the deep tier and gets at most a short
  pointer in the built-in store. Do not restate deep content as a built-in memory — that
  duplication is what produced the drift.
- **On conflict the FILE wins.** It is dated and versioned; the pointer is not. Update the
  pointer, never the reverse.
- **This supersedes the write-to-BOTH rule** (lesson `memory-two-stores-drift`, 2026-08-20).
  Writing the same content to both stores is precisely what made them diverge.
- A built-in memory is capped at **512 characters**, and a longer one is rejected outright —
  nothing is stored, and the failure is easy to miss. Budget for it; never assume a save
  succeeded.
- **Load, then write back.** Once the topic is clear, read
  `Documents/Cowork/cowork-memory/MEMORY-INDEX.md` and load the deep file whose focus area
  matches the work — or create one if none does — per the `persistent-memory` skill. When the
  work concludes, update and consolidate that file in the same session. Skip both entirely for
  quick one-off questions.
- Both obligations live here, in instructions that load unconditionally — not in a skill
  description. A rule that sits only in a SKILL.md description does not survive routing
  (measured 2026-08-18, commit 3292cf1), and a description over the 1024-char cap unloads
  the skill silently (measured 2026-08-21).

## Lessons learned

<!-- LESSON-DIGEST:BEGIN - generated by self-improvement/scripts/lesson_brief.py --digest. Do not hand-edit. -->
### Rules already paid for

Each line below was learned by getting it wrong at least once. They live here,
not in the lessons file, because this file loads every session and the lessons
file only loads if I remember to open it. Three sessions proved I do not.

This is the ALWAYS-ON tier: rules that recurred, plus rules whose first
violation is irreversible. Rules an automated check now refuses were dropped
from here BECAUSE the check cannot be skipped. Nothing was deleted - every
other rule is in cowork-lessons.md and loads with
`lesson_gate.py preflight --surface <bridge|files|memory|skills|git|claims>`
at the moment it applies.

**bridge**
- Prove a bridge by CALLING it, never by reading a tool list. When the tool is ABSENT from the schema there is nothing to call - run `bridge-health.bat` through 8933 as the callable substitute. Re-probe before saying it is down AND again before closing out. Say "not on the surface as of now", never "unavailable this session", and never PLAN AROUND the absence. _(3x)_
- Check PID creation times and listening state before restarting anything. _(2x)_
- Drops are the devtunnel hop, not the bridge process. 0% local, 1-2% tunnel. Retry once, but verify before retrying a write. _(2x)_
- Run `bridge-health.bat` before characterising tunnel state. It is read-only and measures all three legs. _(2x)_
- A connector can vanish OR arrive mid-session. Do not restart anything on the PC; start a new chat instead. _(2x)_
- The error "couldn't be reached, so its tools may be unavailable" is ONE CALL failing on the devtunnel hop, not a bridge state. RETRY the call before saying anything about the bridge. Never tell the operator a bridge is down on the strength of a single failed call. _(2x)_
- After ANY edit to `tasks.json`, resync `Startup\KnownGood\tasks.json` from live in the SAME job and prove it byte-identical. An unsynced snapshot turns `bridge-restore-tasksjson.bat` from a recovery tool into a regression tool, and the restore reports success while doing it. _(2x)_
- Call `run_batch_file` with `file=` holding a path relative to CommandJobs. There is no path, args, cwd or timeout parameter.
- Files written through 8932 arrive LF-only and cmd mis-parses them. Run the CRLF fix job after writing any new .bat.
- 8933 does not inherit a working directory, so start every job with `cd /d <repo>`. PATH is intact and bare interpreter names resolve; only user-profile variables are empty.
- Send approval-gated 8932 writes ONE per tool block. A second write batched beside the first is auto-denied while that approval is still pending.

**git**
- A self-committing job must stage its own permanent file and never its ephemeral inputs. _(2x)_
- Read the actual git status before describing repo state. Do not narrate from memory of what you changed. _(2x)_
- Committing a deletion does not sanitize git history - the path survives in every prior commit and every clone. A repo that ever held engagement content can never be the one pushed; populate a NEW repo by copying named folders in, never by cloning and filtering.
- Before stripping a client name, check whether the CONTENT is also client-specific. If the file's substance is the client's work product, renaming is concealment rather than sanitization - stop and put the decision to the owner.

**skills**
- Never edit a SKILL.md or the lessons file in place with EditArtifact. Edit a local copy, republish the folder, confirm by hash. _(2x)_

**memory**
- Keep a memory under 512 characters and read the success field of every save - an over-length save stores nothing. _(4x)_
- A fact gets ONE home. Pointer tier is short keys; the deep file is mechanism and evidence. On conflict the file wins. _(2x)_
- Scope any structural regex to its target section and anchor on the FULL heading. Over a whole file a prefix matches prose and returns a false negative. _(2x)_
- Repair a stale digest by computing it on a WRITABLE scratch copy, proving the repair with `lesson_gate preflight` against that copy into a SEPARATE receipt dir, then applying the difference to the PC file through the 8932 bridge with `edit_file` - never by pointing `digest_apply.py` at `/mnt/user-config/`, which is read-only. Afterwards expect the mount to keep serving the OLD file: hash it against the pre-repair copy to tell sync lag from a failed write, and never read that fresh exit 1 as a second failure. _(2x)_
- Regenerate the digest with --limit set to the authored-Rule count, then diff old against new and confirm nothing was dropped.

**files**
- The mount can serve a stale or partly-flushed file. Wait ~20s and hash before concluding anything was lost. _(3x)_
- Both sync legs cost minutes, so pick the one that does not block you. A LOCAL 8932 write unblocks the repo and the commit immediately; a cloud-side write blocks them for minutes. _(2x)_
- ERROR 389 `0x185` "The cloud operation was unsuccessful" is a DEHYDRATED PLACEHOLDER that cannot be fetched - not a lock, not a robocopy fault, and `attrib +P -U` does NOT recover it. FIRST count how many placeholders fail: if several across different folders fail, and each fails in well under a second, the OneDrive CLIENT is stuck and one restart fixes every file at once. Only rebuild individual files from the cloud copy when a restart has been tried and the failure is genuinely confined. _(2x)_
- A file carrying the deliverable's NAME but not its content is a false delivery, not an honest gap. Bring the artifact back and check its byte count against the source, or list it as not produced with the reason - nothing in between. Counting files is exactly the check a stub passes.

**claims**
- A checker must gather every piece of evidence BEFORE it adjudicates, once, at the end. Never jump to a FAIL label mid-stream - that skips the step that could contradict it. Take a baseline from a file the run wrote, never from a literal pasted at authoring time. And never let a failure message NAME a cause the job did not test - derive the verdict from a comparison that could have come out the other way. _(4x)_
- For every check, name the failure it CANNOT catch. A guard whose fixture is smaller than the threshold it guards can never fail. _(3x)_
- Read the file or config surface this session before proposing a change to it, and quote the lines that are or are not there. Memory records conclusions, not file text. Say plainly when a recommendation turns out to be unfounded rather than quietly dropping it. _(3x)_
- Break your own checker before trusting it. Positive control first, then negatives that each assert WHY it failed. _(2x)_
- Never hardcode a phrase copied from a lesson's `Rule:` text into the check that verifies it. Read the Rule out of `cowork-lessons.md` at check time and assert against that. A copied literal is correct only until the wording moves, and when it goes stale it fails LOUDLY and confidently while the thing it guards is fine. _(2x)_

**other**
- When a lesson's Rule text is sharpened - or when the THING it counts is redefined - grep for the CHECK that enforces it and update it in the same pass. A check is a frozen copy of the rule as it read on the day it was written. Two ways it goes stale: the wording is sharpened and the check keeps the old wording, or the population is re-tiered and the check keeps counting the old population. In both cases the check keeps firing confidently and its output reads as a measurement. _(2x)_

<!-- LESSON-DIGEST:END - 31 always-on of 94 rules from 120 entries -->

**Before acting on a surface above, one call gets the detail:**
`python /mnt/user-config/skills/self-improvement/scripts/lesson_brief.py <lessons.md> --for bridge`
(surfaces: bridge, files, memory, skills, git, claims). Sub-second, returns only the
matching rules. There is no longer a cost excuse for not checking.

Regenerate this block with `lesson_brief.py <lessons.md> --digest` whenever a rule is
added or a Hits count changes. Do not hand-edit between the markers.

### The scan, for anything the block above does not cover

- Before the FIRST tool call of any task that touches my PC, the bridges, a batch job,
  a scheduled task, or my Cowork config, read
  `Documents/Cowork/cowork-memory/cowork-lessons.md` and follow the **Worked** line of
  any entry whose subsystem you are about to touch. Read the `Pattern-Key` lines; open
  a full entry only when its subsystem matches. This is a precondition, not a reaction —
  do not wait until something fails, and do not wait for me to ask.
- This applies **regardless of which skill is driving.** `command-bridge`,
  `local-file-bridge`, `git-bridge` and `playwright-skill` all sit on top of the same
  traps. Loading one of those skills does not excuse the scan; the routing that picks a
  bridge skill is exactly the routing that will otherwise skip `self-improvement`.
- When something fails in a non-obvious way, when I correct a belief you acted on, or
  when you find a materially better approach for something recurring, add or update an
  entry there per the `self-improvement` skill — same session, not "next time".
- Say which Pattern-Key you applied, in one short line. If the scan found nothing
  relevant, say nothing — silence means clean, not skipped.

## Local MCP bridges — my PC

I run three local MCP bridges from `C:\Users\YOURUSER\Documents\COPILOT_COWORK\Startup`
(launcher: `GO.bat`). Each is exposed over a VS Code dev tunnel and must be set to PUBLIC
after every VS Code restart. Connectors only load at session start.

| Port | Bridge | Handles | Skill that owns the routing |
|---|---|---|---|
| 8931 | Playwright / Web Automation | browser control on my real Edge SSO profile | `playwright-skill` |
| 8932 | Filesystem | read/write files on my PC | `local-file-bridge` |
| 8933 | Commands | run `.bat` / `.cmd` / `.ps1` / any process | `command-bridge` |

Known traps for all three live in `cowork-lessons.md` — scan it first (see above).

### The folder is COPILOT_COWORK

The bridges reach exactly three directories:

- `C:\Users\YOURUSER\Documents\COPILOT_COWORK`
- `C:\Users\YOURUSER\Downloads`
- `C:\Users\YOURUSER\OneDrive\Documents\Cowork`
  (added 2026-08-24, commit `a6297b6`)

The folder was renamed from `Cowork` on 2026-07-27. **Any reference to
`C:\Users\YOURUSER\Documents\Cowork` is stale — do not use it.** That old folder still
exists on disk with competing VS Code tasks; opening it fights for the same ports.

Do not confuse it with OneDrive `Documents/Cowork`, which is Cowork's own config store
(skills, `cowork-memory/`, `copilot-instructions.md`). **Since 2026-08-24 the bridges DO
reach it.** That was not true before, so any older wording calling it unreachable is stale.
Read it from the `/mnt/user-config/` mount; WRITE it through the bridge at its full local
path. Config belongs in OneDrive; working files belong on the PC.

**The mount lags behind writes, and its absence is not evidence.** After writing through
the bridge, a file can be missing from `/mnt/user-config/` entirely, or return stale
content, for minutes. The lag is PER FILE - a file written earlier can be current on the
mount at the same moment a newer one is invisible - so mount freshness cannot be
established by checking a different file. **Confirm a write through the path you WROTE it
with** (`list_directory_with_sizes` / `read_text_file` on the bridge), never by looking
for it on the mount. Do not re-send, republish, or start "fixing" a file because the mount
disagrees. (Promoted from lesson `onedrive-user-mount-read-lag` at Hits 2, 2026-08-28.)

### Writing config, memory and lessons files

Write them to the **LOCAL** path through the 8932 bridge, never cloud-side, whenever the repo
needs to see them in the same session.

- A cloud-side write (artifact tools, session `output/`, `UploadFileContent`) lands in
  OneDrive and then waits on the desktop client to pull it down. On 2026-08-24 that took
  20-35 minutes and stranded three memory files across a commit.
- The local leg has no such wait: the file is on disk at once, the repo sync sees it, and
  OneDrive carries it upward on its own time.
- Adding the OneDrive folder as a bridge root did NOT change this. A root changes what the
  bridge may REACH, not how OneDrive replicates.
- Never hand-place into the ONEDRIVE copy while a download for that file is pending — that is
  how conflict files appear. Hand-placing the REPO copy is safe; OneDrive does not sync it.

**Route a write by PAYLOAD, measured 2026-08-28.** Both sync legs cost minutes, so the
question is never which is faster, it is which one blocks. A cloud-side write reaches the
container at once and the PC minutes later, so the repo and the commit wait. A local write
reaches the repo at once and the container about 3 minutes later, and that lag costs
nothing because the content is already in `working/`.

| Payload | Route |
|---|---|
| New or small file (under ~30 KB) | `write_file` on 8932, local OneDrive path |
| Existing large file | `edit_file` on 8932, same path, sends only the anchors |
| Bulk, binary, or a whole folder | `CopyArtifact`, copies server-side and sends no content |

Verify a local write by reading it back THROUGH THE BRIDGE. The container mount serves the
old bytes for about 3 minutes. Once a file has been written locally in a session, keep
using the local path for it, because a later cloud-side write based on a stale mount read
would clobber it.

(Promoted from lessons `onedrive-cloud-to-laptop-lag` after it reached Hits 2, and
`onedrive-pick-the-leg-that-does-not-block` 2026-08-28.)

### Do not edit a skill or the lessons file in place with EditArtifact patches

An `EditArtifact(surface="user")` `replace_text` patch on a SKILL.md or on
`cowork-lessons.md` gets rejected with `invalid patch: replace_text 'find' string is not
present in the artifact` even when the find text is verified present exactly once on the
mount, and even when the anchor is taken from the pre-edit version. Five occurrences
across four files (myvoice, self-improvement, cowork-lessons.md), and not one recovered
on a retry.

- **Do not retry the patch and do not read it as data loss.** The mount and the artifact
  service hold different copies. A partly-flushed read looks like deletion, so hash before
  concluding anything is gone.
- **Edit a local copy and republish the whole file.** Assert the find string occurs
  exactly once before replacing, then publish.
- **Confirm by hash, never by a file count.** Compare the published file against the local
  expected result. `copied: 1` proves a call happened, not that the right bytes landed.

(Promoted from lesson `skill-editartifact-patch-rejected-republish-folder` after five
occurrences across four files, 2026-08-21 to 2026-08-28.)

### Routing rules

1. **Any local signal routes to a bridge.** If I reference a `C:\` path, or say "my PC",
   "my machine", "my computer", "locally", "on disk", "COPILOT_COWORK", or "my Downloads
   folder" — use the bridge, not artifact tools and not the session `output/` folder.
   Files → filesystem bridge. Commands/scripts → command bridge. Browser → web bridge.

2. **Never fall back silently.** If the bridge for the job is not available this session,
   do not quietly substitute artifact tools, the cloud workspace, or the session
   container. Tell me plainly which bridge is not connected, then wait. Session `output/`
   is only an option I explicitly accept, never an automatic substitution.

3. **Verify, don't trust the success message.** After a write, report the exact absolute
   Windows path and read it back **on the bridge, not on the mount** (see the mount-lag
   note above). After a command, report the actual exit code and output.

4. **Before overwriting, check with `get_file_info` and warn me** — `write_file`
   overwrites silently and there is no delete tool.

5. **A single failed call is not a dead bridge, and a negative probe expires.** The
   transport is stateless; retry one failed call once before declaring the bridge down.
   Verify writes landed before retrying them. An empty tool probe is a reading of that
   instant only — connectors arrive mid-session as well as vanish. Re-probe before
   reporting a bridge step impossible AND again before closing out any routine that needs
   it. Say "not on the surface as of now", never "unavailable this session". Watch the
   probe itself: an anchored `^tool_name$` pattern cannot match a fully qualified
   `<server>-<tool>` name and reads as absent even when the bridge is up.

6. **Only use artifact tools / session `output/`** when I explicitly say "deliverable",
   "download", or "artifact". When unsure which route I want, ask.

### When the command bridge is down — there is NO fallback

If `jordan-approved-batch-8933-v1` / `run_batch_file` is unavailable, **stop and tell me
the bridge is not connected.** That is the whole procedure.

- Do **not** write to `COPILOT_COWORK\autorun\queue`, do **not** invoke `AUTORUN.ps1`, and
  do not substitute any other execution runtime — no container, no session `output/`, no
  artifact tools, no scheduled task. The autorun watcher was removed from
  `Startup\.vscode\tasks.json` on 2026-08-21 (commit 784dc9f) precisely so this path is
  not armed; `AUTORUN.ps1` remains on disk for me to run by hand, and is not yours to use.
- Retry a single failed call once first — the transport is stateless and one drop is not a
  dead bridge (see routing rule 5 above). After that, report and wait.

## General preferences

- Separate **facts** from **inferences**, and flag anything that needs my review.
- Be direct and concise; lead with the answer, then the detail.
- For any irreversible action (sending email, posting to Teams, deleting), confirm first.