fix(session-context): add --root flag for opencode's true parent session

.claude/agent-memory/archgate-developer/MEMORY.md

@@ -80,6 +80,11 @@ Non-enforceable lessons — environment/CI/platform quirks no static rule can re
 
 - **`archgate` command = `bun run cli`** — This is the CLI repo itself, so the `archgate` binary is not installed in PATH. Use `bun run cli <command>` (e.g., `bun run cli check`, `bun run cli adr list`) instead of `archgate <command>`. The `bun run cli` script maps to `bun run src/cli.ts`.
 
+## Sibling Repo: archgate/plugins
+
+- [Skill files for opencode/cursor are GENERATED, not hand-authored](project_plugins_generated_skill_files.md) — canonical source is `claude-code/plugins/archgate/skills/<name>/SKILL.md`; edit build scripts (`scripts/build-<platform>-plugin.ts`) for platform-specific wording, not the generated copies directly
+- [session-context opencode --skip 1 bug fixed via --root](project_session_context_skip_root_fix.md) — same bug class likely still open for claude-code/cursor/copilot, live-reproduced for claude-code but not fixed
+
 ## Distribution / Packaging
 
 - **npm shim + GitHub Releases** — The npm package is a thin shim (`bin/archgate.cjs`). On first run, the shim downloads the platform binary from GitHub Releases and caches it to `~/.archgate/bin/`. No platform-specific npm packages.

.claude/agent-memory/archgate-developer/project_plugins_generated_skill_files.md

@@ -0,0 +1,12 @@
+---
+name: project-plugins-generated-skill-files
+description: archgate/plugins skill files for opencode/cursor-plugin/cursor-install are GENERATED from claude-code source — never hand-edit them directly
+metadata:
+  type: project
+---
+
+The sibling repo `E:\archgate\plugins` (separate git repo, `github.com/archgate/plugins`) holds the AI-facing skill/agent markdown consumed by the `archgate` Claude Code plugin, opencode, Cursor, VS Code Copilot, etc. `claude-code/plugins/archgate/skills/<name>/SKILL.md` is the **only** canonical source (per that repo's ARCH-003 "Platform Distribution Build Pattern"). Every other platform's copy — `opencode/plugins/archgate/skills/archgate-<name>/SKILL.md`, `cursor-plugin/...`, `cursor-install/...` — is a build artifact generated by `scripts/build-<platform>-plugin.ts`, which applies regex-based text transformations (tool-name rewrites, `@mention` syntax, editor-specific `session-context <editor>` substitutions, etc.) and is checked into git for diff review, but is NOT hand-authored.
+
+**Why:** Hand-editing a generated copy (e.g. `opencode/plugins/archgate/skills/archgate-lessons-learned/SKILL.md`) works until the next `bun scripts/build-opencode-plugin.ts` (or `build-artifacts.ts`) run, which silently overwrites it back to whatever the regex transform of the canonical claude-code source produces. Learned this the hard way on 2026-07-01: edited the opencode SKILL.md directly to fix the `--skip 1` bug (see [[project_session_context_skip_root_fix]]), then ran the build script to regenerate the tarball artifact — it reverted my edit instantly.
+
+**How to apply:** To change platform-specific wording that should NOT apply to all editors (e.g. opencode needing `--root` while claude-code/cursor keep `--skip 1`), add a new transformation step inside that platform's `adaptForOpencode()`-equivalent function in `scripts/build-<platform>-plugin.ts` (do a literal string/regex replace keyed off the exact canonical source text), NOT a direct edit to the generated file. To change wording that SHOULD apply to all editors, edit the canonical `claude-code/plugins/archgate/skills/<name>/SKILL.md` source instead. Either way, finish with `bun scripts/build-artifacts.ts` (regenerates all platform artifacts + embedded bridge files in one pass) then `bun scripts/check-artifacts.ts` to confirm everything is back in sync before considering the change done. That repo's `package.json` `validate` script and ARCH-003 are the authoritative references — read ARCH-003 in full via `archgate adr show ARCH-003` in that repo before making build-script changes.

.claude/agent-memory/archgate-developer/project_session_context_skip_root_fix.md

@@ -0,0 +1,16 @@
+---
+name: project-session-context-skip-root-fix
+description: opencode session-context --skip 1 sibling/inline-skill bug fixed via new --root flag (2026-07-01); same class of bug likely still open for claude-code/cursor/copilot
+metadata:
+  type: project
+---
+
+Fixed a real, reproduced bug in `archgate session-context opencode --skip 1`: it could return a completely unrelated sibling sub-agent's session transcript instead of the true parent/development session. Fix shipped 2026-07-01 as a new `--root` flag on `archgate session-context opencode` (see `src/helpers/session-context-opencode.ts` and `src/commands/session-context/opencode.ts`).
+
+**Why:** `readOpencodeSession`'s `--skip N` selected the Nth-most-recently-updated session sharing a project directory, ignoring opencode's real `session.parent_id` column entirely. This breaks in two ways: (1) the opencode `Skill` tool runs inline in the current session (no new session row), so "skip past my own session" skips past the actual parent instead; (2) sibling sub-agent sessions fanned out from the same parent (e.g. the `archgate:reviewer` skill's parallel domain-review agents) interleave in recency order with the parent, so `--skip 1` can land on any sibling. Verified this concretely against the user's real `~/.local/share/opencode/opencode.db`: a live `archgate-lessons-learned` skill invocation's `--skip 1` call returned the "General process ADR review" sub-agent's private transcript instead of the parent session.
+
+`--root` fixes this by filtering to `parent_id IS NULL` before applying `skip`, which is correct regardless of nesting depth or sibling count. The `archgate-lessons-learned` skill's opencode variant was updated to use `--root` instead of `--skip 1` — see [[project_plugins_generated_skill_files]] for where that source actually lives.
+
+**Open/unresolved:** The _same class_ of bug likely still affects the other 3 editors' lessons-learned skill guidance (`archgate session-context claude-code --skip 1`, `cursor --skip 1`). Live-reproduced for Claude Code in this same session: running `archgate session-context claude-code --skip 1` from within an inline Skill invocation (this very lessons-learned run) returned an unrelated, unconnected past session (`6ee6f0a5-...` about "ExitWorktree"), not the current/parent conversation — because Claude Code's Skill tool also runs inline, so `--skip 1` skips past the correct (current) session file. Unlike opencode, Claude Code/Cursor have no `parent_id`-equivalent — sessions are flat per-conversation JSONL/directory files with no structural parent link, so the `--root` fix pattern doesn't directly transfer; a different fix (e.g. detecting "am I inline vs a real sub-agent" some other way, or defaulting to `--skip 0` for inline skill runs) would be needed. Not investigated for Copilot. This has NOT been fixed — flag to the user before doing more lessons-learned/reviewer work that depends on `--skip 1` being reliable for non-opencode editors.
+
+**How to apply:** If asked to investigate "session context returns wrong data" for claude-code, cursor, or copilot, start here — this is the same architectural flaw already fixed once for opencode, not a new mystery.

docs/public/llms-full.txt

@@ -4388,17 +4388,20 @@ archgate session-context cursor [options]
 
 ### archgate session-context opencode
 
-Read the opencode session transcript for the project. Sessions are matched by the project `path` field in session metadata.
+Read the opencode session transcript for the project. Sessions are matched by the `directory` field in session metadata.
 
 ```bash
 archgate session-context opencode [options]
 ```
 
-| Option              | Description                                                        |
-| ------------------- | ------------------------------------------------------------------ |
-| `--max-entries <n>` | Maximum entries to return (default: 200)                           |
-| `--skip <n>`        | Skip the N most recent sessions (useful when running as sub-agent) |
-| `--session-id <id>` | Specific session ID to read                                        |
+| Option              | Description                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200)                                                                                     |
+| `--skip <n>`        | Skip the N most recent sessions (combine with `--root` to skip within root sessions only)                                    |
+| `--session-id <id>` | Specific session ID to read                                                                                                  |
+| `--root`            | Read the top-level session (no parent) instead of guessing by recency — use this when running as a sub-agent or inline skill |
+
+Opencode records real parent/child session links. A plain `--skip 1` picks the second most-recently-updated session sharing this directory, which is only the parent when exactly one other session touched it — a fan-out of sibling sub-agents can land `--skip 1` on an unrelated sibling instead. `--root` resolves the actual top-level session directly, regardless of how many sub-agent or inline-skill sessions exist underneath it.
 
 ## Examples
 
@@ -4432,6 +4435,12 @@ Read the parent session (skip the sub-agent's own session):
 archgate session-context claude-code --skip 1
 ```
 
+Read the top-level opencode session from a sub-agent or inline skill:
+
+```bash
+archgate session-context opencode --root
+```
+
 ---
 
 ## Reference: archgate telemetry

docs/src/content/docs/nb/reference/cli/session-context.mdx

@@ -54,17 +54,20 @@ archgate session-context cursor [options]
 
 ### archgate session-context opencode
 
-Les opencode-sesjonsloggen for prosjektet. Sesjoner matches etter prosjektets `path`-felt i sesjonsmetadataene.
+Les opencode-sesjonsloggen for prosjektet. Sesjoner matches etter `directory`-feltet i sesjonsmetadataene.
 
 ```bash
 archgate session-context opencode [options]
 ```
 
-| Valg                | Beskrivelse                                                         |
-| ------------------- | ------------------------------------------------------------------- |
-| `--max-entries <n>` | Maksimalt antall oppføringer å returnere (standard: 200)            |
-| `--skip <n>`        | Hopp over de N nyeste sesjonene (nyttig ved kjøring som underagent) |
-| `--session-id <id>` | Spesifikk sesjons-ID å lese                                         |
+| Valg                | Beskrivelse                                                                                                                                |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--max-entries <n>` | Maksimalt antall oppføringer å returnere (standard: 200)                                                                                   |
+| `--skip <n>`        | Hopp over de N nyeste sesjonene (kombiner med `--root` for å hoppe kun blant rotsesjoner)                                                  |
+| `--session-id <id>` | Spesifikk sesjons-ID å lese                                                                                                                |
+| `--root`            | Les toppnivåsesjonen (uten forelder) i stedet for å gjette basert på nylighet — bruk dette ved kjøring som underagent eller innebygd skill |
+
+Opencode registrerer ekte forelder/barn-koblinger mellom sesjoner. En enkel `--skip 1` velger den nest nyeste oppdaterte sesjonen som deler denne mappen, noe som bare er forelderen når nøyaktig én annen sesjon har rørt den — en vifte av søsken-underagenter kan gjøre at `--skip 1` havner på et urelatert søsken i stedet. `--root` løser den faktiske toppnivåsesjonen direkte, uansett hvor mange underagent- eller innebygd-skill-sesjoner som finnes under den.
 
 ## Eksempler
 
@@ -97,3 +100,9 @@ Les foreldresesjonen (hopp over underagentens egen sesjon):
 ```bash
 archgate session-context claude-code --skip 1
 ```
+
+Les toppnivåsesjonen for opencode fra en underagent eller innebygd skill:
+
+```bash
+archgate session-context opencode --root
+```

docs/src/content/docs/pt-br/reference/cli/session-context.mdx

@@ -54,17 +54,20 @@ archgate session-context cursor [options]
 
 ### archgate session-context opencode
 
-Lê a transcrição de sessão do opencode para o projeto. Sessões são correspondidas pelo campo `path` do projeto nos metadados da sessão.
+Lê a transcrição de sessão do opencode para o projeto. Sessões são correspondidas pelo campo `directory` nos metadados da sessão.
 
 ```bash
 archgate session-context opencode [options]
 ```
 
-| Opção               | Descrição                                                           |
-| ------------------- | ------------------------------------------------------------------- |
-| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200)                         |
-| `--skip <n>`        | Pular as N sessões mais recentes (útil ao executar como sub-agente) |
-| `--session-id <id>` | ID específico da sessão a ser lida                                  |
+| Opção               | Descrição                                                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200)                                                                                      |
+| `--skip <n>`        | Pular as N sessões mais recentes (combine com `--root` para pular apenas entre sessões raiz)                                     |
+| `--session-id <id>` | ID específico da sessão a ser lida                                                                                               |
+| `--root`            | Lê a sessão de nível superior (sem pai) em vez de adivinhar pela recência — use isso ao executar como sub-agente ou skill inline |
+
+O opencode registra vínculos reais de pai/filho entre sessões. Um simples `--skip 1` seleciona a segunda sessão mais recentemente atualizada que compartilha esse diretório, o que só corresponde à sessão pai quando exatamente uma outra sessão a tocou — um leque de sub-agentes irmãos pode fazer `--skip 1` cair em um irmão não relacionado. `--root` resolve diretamente a sessão de nível superior real, independentemente de quantas sessões de sub-agente ou skill inline existam abaixo dela.
 
 ## Exemplos
 
@@ -97,3 +100,9 @@ Ler a sessão pai (pular a sessão do sub-agente):
 ```bash
 archgate session-context claude-code --skip 1
 ```
+
+Ler a sessão de nível superior do opencode a partir de um sub-agente ou skill inline:
+
+```bash
+archgate session-context opencode --root
+```

docs/src/content/docs/reference/cli/session-context.mdx

@@ -54,17 +54,20 @@ archgate session-context cursor [options]
 
 ### archgate session-context opencode
 
-Read the opencode session transcript for the project. Sessions are matched by the project `path` field in session metadata.
+Read the opencode session transcript for the project. Sessions are matched by the `directory` field in session metadata.
 
 ```bash
 archgate session-context opencode [options]
 ```
 
-| Option              | Description                                                        |
-| ------------------- | ------------------------------------------------------------------ |
-| `--max-entries <n>` | Maximum entries to return (default: 200)                           |
-| `--skip <n>`        | Skip the N most recent sessions (useful when running as sub-agent) |
-| `--session-id <id>` | Specific session ID to read                                        |
+| Option              | Description                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `--max-entries <n>` | Maximum entries to return (default: 200)                                                                                     |
+| `--skip <n>`        | Skip the N most recent sessions (combine with `--root` to skip within root sessions only)                                    |
+| `--session-id <id>` | Specific session ID to read                                                                                                  |
+| `--root`            | Read the top-level session (no parent) instead of guessing by recency — use this when running as a sub-agent or inline skill |
+
+Opencode records real parent/child session links. A plain `--skip 1` picks the second most-recently-updated session sharing this directory, which is only the parent when exactly one other session touched it — a fan-out of sibling sub-agents can land `--skip 1` on an unrelated sibling instead. `--root` resolves the actual top-level session directly, regardless of how many sub-agent or inline-skill sessions exist underneath it.
 
 ## Examples
 
@@ -97,3 +100,9 @@ Read the parent session (skip the sub-agent's own session):
 ```bash
 archgate session-context claude-code --skip 1
 ```
+
+Read the top-level opencode session from a sub-agent or inline skill:
+
+```bash
+archgate session-context opencode --root
+```

src/commands/session-context/opencode.ts

@@ -16,7 +16,7 @@ const maxEntriesOption = new Option(
 
 const skipOption = new Option(
   "--skip <n>",
-  "skip the N most recent sessions (useful when running as a sub-agent)"
+  "skip the N most recent sessions (for --root, skips within root sessions only; for finding a parent session use --root instead)"
 )
   .argParser((val) => Math.trunc(Number(val)))
   .default(0);
@@ -28,13 +28,18 @@ export function registerOpencodeSessionContextCommand(parent: Command) {
     .addOption(maxEntriesOption)
     .addOption(skipOption)
     .option("--session-id <id>", "Specific session ID to read")
+    .option(
+      "--root",
+      "read the top-level session (no parent) for the project instead of guessing by recency — use this instead of --skip when running as a sub-agent or inline skill"
+    )
     .action(async (opts) => {
       try {
         const projectRoot = findProjectRoot();
         const result = await readOpencodeSession(projectRoot, {
           maxEntries: opts.maxEntries,
           skip: opts.skip,
           sessionId: opts.sessionId,
+          root: opts.root,
         });
 
         if (!result.ok) {