@memorax/memorax-code 0.1.0

package/lib/memorax-code-claude-marketplace/plugins/memorax-code-claude-adapter/skills/memorax-code/references/repo-build.md

@@ -0,0 +1,270 @@
+# Repo Memory Build
+
+## Core Principle
+
+The agent authors the repo memory. Scripts collect and validate mechanical evidence, but do not replace agent-authored memory.
+
+Do not let a script write `PROFILE.md`, `resources/commits.md`, `resources/prs.md`, or `resources/issues.md`. The agent must inspect the local project, understand the code, and author the human-facing memory. Scripts may create deterministic raw evidence only.
+
+This is the full-build operation, not the daily reader or incremental updater. Return to `SKILL.md` and use `repo-read.md` for task-time search over existing memory. For latest-change-only updates to an existing `.repo_memory`, use `repo-update.md`. Use this reference for first-time creation, full rebuilds, or full refreshes that recollect raw evidence and rewrite authored memory.
+
+## Output Layout
+
+The user selects a repository, not a memory directory. Do not ask for a `.repo_memory` path. Create this bundle inside the target repository:
+
+```text
+<repo>/.repo_memory/
+├── PROFILE.md
+├── raw/
+│   ├── prepare-report.json
+│   ├── git-commits.json
+│   └── github-facets.json or gitlab-facets.json
+└── resources/
+    ├── commits.md
+    ├── prs.md
+    └── issues.md
+```
+
+Script-generated artifacts: `raw/prepare-report.json`, `raw/git-commits.json`, and optional `raw/github-facets.json` or `raw/gitlab-facets.json`. Agent-authored durable artifacts: `PROFILE.md`, `resources/commits.md`, `resources/prs.md`, and `resources/issues.md`.
+
+User-managed sidecars may coexist under `.repo_memory/procedure-memory/` and `.repo_memory/user-profile/`. Builder scripts preserve them and exclude them from bundle validation; this skill must not create, edit, or summarize their contents as repo-memory evidence.
+
+## Repository Prerequisite
+
+The selected target must be a local git repository: either the directory contains `.git/` or is inside a git worktree. A GitHub/GitLab remote is optional; local-only git repositories are supported.
+
+If the directory is not a git repository, do not create `.repo_memory/` and do not fabricate a memory bundle from file inspection alone. Stop with a prominent notice:
+
+```text
+**Repo Memory Cannot Be Built Yet**
+
+> This folder is not a git repository, so repo memory cannot collect local commit history or provider-linked PR/MR/issue evidence.
+
+**Next steps**
+- If this is an existing project, open the real cloned repo directory.
+- If this is a new project, run `git init` first, make at least one commit, then rerun the `repo-build` operation.
+- If you only want file inspection, continue by inspecting files without repo memory.
+```
+
+## Path Convention
+
+`<skill-dir>` means the parent directory of the `references/` directory containing this file. Resolve it before running scripts, for example:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --pretty --progress
+```
+
+## Default Settings
+
+Default mechanical collection settings are intentionally visible in `<skill-dir>/defaults.json`:
+
+```json
+{
+  "schema": "repo_memory_builder_defaults.v1",
+  "limits": {
+    "commits": 30,
+    "prs": 30,
+    "issues": 30
+  },
+  "summaryChars": 4000
+}
+```
+
+To change defaults for future builder runs, edit `defaults.json`, not the Python scripts. To override one run, pass `--commit-limit`, `--pr-limit`, `--issue-limit`, or `--summary-chars` to `collect_all.py`.
+
+Provider collection is best-effort by default. Use `--skip-provider` for an explicit local-only run that does not call GitHub/GitLab, and use `--require-provider` only when the user explicitly requires PR/MR/issue evidence and the run should fail instead of falling back to local-only memory.
+
+## User Count Requests
+
+If the user mentions how many commits, PRs/MRs, or issues to collect, treat that as a one-run override and pass explicit limit flags to `collect_all.py`. Do not edit `defaults.json` for a one-run request.
+
+Examples:
+
+- "拉 50 条 commit" means add `--commit-limit 50`.
+- "PR 拉 20 条，issue 拉 30 条" means add `--pr-limit 20 --issue-limit 30`.
+- "commit、PR、issue 都拉 50 条" means add `--commit-limit 50 --pr-limit 50 --issue-limit 50`.
+
+Only edit `defaults.json` when the user asks to change defaults for future build runs, for example "以后默认都拉 50 条" or "把 repo memory 的默认 limit 改成 50".
+
+## Progress Display
+
+Skill instructions cannot render app-native progress components by themselves. For interactive builder runs, prefer `collect_all.py --progress`; it renders a terminal progress bar on stderr while keeping stdout as the final JSON report. Omit `--progress` only for strict machine-only runs that must avoid stderr progress output.
+
+The progress bar covers the mechanical collection steps: preparation, local commits, and provider facets. Provider warnings are not terminal notifications; they are returned in the JSON report as structured `notices[]` so the agent can show them as a normal user-visible assistant message. The progress bar does not replace the required provider warning notice, final JSON report review, agent-authored Markdown work, or final validation.
+
+## Build Modes
+
+Build mode controls only the local project understanding phase. The mechanical collection, authoring, and validation flow stays the same.
+
+- Default to lightweight mode when the user does not specify.
+- Use lightweight mode for a quick or docs-only pass. Read root README/high-level docs, repo-local agent instructions such as `AGENTS.md` or `CLAUDE.md`, and clearly linked overview/setup docs. Do not inspect source, manifests, scripts, or CI just to deepen the profile. Mark code-level architecture claims as doc-derived or unverified.
+- Use deep mode only when the user explicitly asks for deep/thorough/full work, or when docs are too thin to produce useful memory. Read docs and agent instructions, then inspect repository structure, module READMEs, representative source and entrypoints, manifests, scripts, and CI before writing `PROFILE.md`.
+- Do not stop to ask for a mode unless the user's request is contradictory.
+
+## Tool Roles
+
+### `scripts/collect_all.py`
+
+Use this as the primary mechanical path. It prepares the workspace, collects local git commit evidence, collects GitHub/GitLab PR/MR/issue evidence when provider auth is ready, and returns a JSON report describing completed steps and outputs. If provider collection fails after preparation reports `provider_evidence_state: "ready"`, the default behavior is to keep local commit evidence, emit a warning notice, and report `steps.provider_facets.degraded_to_local_only: true`. Only `--require-provider` turns this into a hard failure.
+
+Default run:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --pretty --progress
+```
+
+One-run limit override:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --commit-limit 50 --pr-limit 20 --issue-limit 20 --pretty --progress
+```
+
+Full refresh of an existing `.repo_memory` bundle:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --reuse --snapshot-ref HEAD --pretty --progress
+```
+
+Local-only memory or hard-required provider evidence:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --skip-provider --pretty --progress
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --require-provider --pretty --progress
+```
+
+Tell the user before starting long collection steps. After completion, report collected counts from the JSON report: local commits, PRs/MRs, issues, provider state, skipped steps, notices, and output files.
+
+#### Final Summary Notices
+
+If the final JSON report contains `notices[]`, the final user-facing summary must include those notices explicitly. Include the notice title, message, and next steps, especially `Provider Evidence Unavailable`.
+
+Do not silently collapse notices into counts, provider state, or a generic "local-only" sentence. If provider evidence degraded to local-only, say that directly and include the reason from the notice.
+
+#### Provider Sandbox and Transport Failures
+
+`gh/glab` provider collection needs external network access. If provider stderr or `notices[]` shows `fetch failed`, timeout, DNS, connection, TLS, `ENOTFOUND`, `EAI_AGAIN`, or similar transport text, report provider evidence unavailable and continue local-only unless `--require-provider` was requested.
+
+Verify provider authentication in the same normal shell with the command reported by `collect_all.py`; for GitHub Enterprise or self-hosted GitLab this may include `--hostname <host>`. Authenticate with `gh auth login` or `glab auth login` (also host-scoped when prompted), then rerun `collect_all.py`; do not paste tokens into the skill or call provider APIs directly.
+
+Do not use a restricted shell sandbox to verify provider/API availability. Verify in a normal shell or approved network-enabled mode. If only restricted shell access is available, report provider evidence unavailable and continue local-only unless `--require-provider` was requested. Do not treat a provider transport failure as empty PR/issue evidence, no PR/issue changes, bad login, or bypass the scripts with direct APIs, browser scraping, copied credentials, or hand-written raw facets.
+
+### `scripts/validate_memory.py`
+
+Use this as the final gate after authoring `PROFILE.md` and `resources/*.md`. It accepts either the repository root or the memory root, validates required files, JSON parseability, frontmatter counts, placeholder removal, and provider raw/resource consistency.
+
+```bash
+python3 <skill-dir>/scripts/validate_memory.py <repo-path> --pretty
+```
+
+### Internal scripts
+
+These are invoked by `collect_all.py`. Use them directly only for debugging or narrow recovery:
+
+- `prepare_repo_memory.py`: validates the target repo, handles `--reuse`, creates `.repo_memory/{raw,resources}`, updates `.gitignore`, and writes `raw/prepare-report.json`.
+- `git_commit_facets.py`: collects local commit facets from the selected snapshot. It needs only local git history.
+- `github_resource_facets.py` and `gitlab_resource_facets.py`: collect provider PR/MR/issue facets when `prepare-report.json` says the provider is ready. They share the same downstream resource shape; GitLab merge requests are normalized into PR resources.
+
+Provider resource facets share this contract: `--snapshot-ref HEAD` filters merged PRs/MRs by merge-commit ancestry against the local snapshot; open and closed-unmerged PRs/MRs are not retained as landed evidence; issues come from the current bounded provider list because issues do not have reliable commit ancestry. For PRs/MRs, `--pr-limit` is the retained count after snapshot filtering.
+
+## Agent Workflow
+
+Follow this order manually:
+
+1. **Collect mechanical evidence**
+   - Run `collect_all.py`.
+   - Use `--reuse` only for a full refresh/rebuild of an existing `.repo_memory`; for latest-change-only updates, prefer `repo-update.md`.
+   - Read the returned JSON report and `.repo_memory/raw/prepare-report.json`.
+   - Stop if preparation fails. Do not improvise around git/repo safety checks.
+
+2. **Show provider notices**
+   - If `notices[]` contains `Provider Evidence Unavailable`, show it as a normal assistant message before continuing and repeat it in the final summary.
+   - Render `title` as a bold heading, `message` as body text, `command` as the login command when present, and `next_steps` as recovery steps. Do not show raw JSON or put the notice inside a fenced code block.
+   - If `notices[]` is absent, fall back to `raw/prepare-report.json`: when `provider_notice_level` is `warning`, render `provider_notice_markdown` as a normal assistant message.
+   - If the user explicitly required PR/MR/issue evidence, run with `--require-provider`, stop after provider failure, and ask them to install/login or fix repository access before rerunning.
+
+Use this visible shape:
+
+```text
+**Provider Evidence Unavailable**
+
+<notice.message>
+
+**Next steps for provider evidence**
+Run: `<notice.command>`
+
+<notice.next_steps rerun item>
+```
+
+3. **Understand the local project**
+   - Choose lightweight by default; choose deep only when requested or clearly needed.
+   - Form project-level understanding before looking at PR/issue history.
+   - Record whether conclusions are doc-derived or code-inspected.
+
+4. **Draft `PROFILE.md`**
+   - Read [repo-templates.md](repo-templates.md) before writing memory files.
+   - Include repo identity, checkout state, evidence inspected, agent consumption rules, module map, verification gates, architecture boundaries, resource pointers, and retrieval flow.
+   - Record the selected build mode and avoid overstating code-level claims in lightweight mode.
+
+5. **Review raw evidence**
+   - Confirm `raw/git-commits.json` exists.
+   - When provider evidence is available, confirm the matching provider facets exist.
+   - If provider evidence is missing, skipped, or degraded to local-only, keep PR/issue resources explicitly marked unavailable instead of inventing provider evidence.
+
+6. **Author human-readable resources**
+   - Use the resource templates in [repo-templates.md](repo-templates.md).
+   - Read raw facets and write `resources/commits.md`, `resources/prs.md`, and `resources/issues.md` yourself.
+   - Keep resources compact. Use one fixed-field section per commit, PR/MR, or issue, separated by `---`; do not use Markdown tables.
+   - Every section must include a search-grade `Description`.
+
+7. **Finalize and validate**
+   - Add final pointers and provider snapshot notes to `PROFILE.md`.
+   - Run `validate_memory.py` as the final gate.
+   - Fix authored Markdown placeholders, frontmatter counts, or resource mismatches before reporting success.
+
+## Refresh/Update Workflow
+
+For incremental updates to recent commits, PRs/MRs, or issues in an existing `.repo_memory`, use `repo-update.md`.
+
+Use builder refresh only when the user wants a full rebuild/full refresh while preserving the existing memory directory:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --reuse --pretty --progress
+```
+
+Then rewrite affected human-authored resources from the new raw evidence. Preserve useful existing notes only when they are still supported by current raw evidence and live repository inspection. Never append or patch raw/provider JSON by hand; rerun the collection scripts instead.
+
+## Description Quality Standard
+
+`Description` is the main agentic-search surface for `resources/commits.md`, `resources/prs.md`, and `resources/issues.md`. Keep only the core rule here; the full quality standard and section scaffolding live in [repo-templates.md](repo-templates.md).
+
+Every description must say what the item explains, when a future agent should open it, which modules/files/commands/config it points to, concrete search cues, and evidence strength. Do not copy raw summaries, headings, or tables into descriptions, and avoid vague descriptions like "fix bug" or "update docs".
+
+## Generated Knowledge Contract
+
+Generate memory that the `memorax-code` repo-read operation can consume progressively:
+
+- `PROFILE.md` is the stable entry point and should summarize identity, evidence, architecture, verification gates, and resource pointers.
+- `resources/*.md` are compact human-readable routing resources with search-grade descriptions.
+- `raw/*.json` contains optional build/debug evidence for deep inspection when compact resources are insufficient.
+
+Do not duplicate the daily retrieval workflow here. The `repo-read` operation owns trigger timing, silent background-maintenance handoff, and task-specific search behavior.
+
+## Trust Rules
+
+- Local code and targeted verification are stronger evidence than generated memory.
+- Local git commit evidence is checkout history and does not require provider login.
+- GitHub/GitLab PR/issue evidence is historical/contextual, not proof of current checkout behavior.
+- Open PRs are active branch intent, not landed behavior.
+- Closed unmerged PRs are weak or superseded evidence.
+- Merged PRs are useful history but still require current code verification.
+
+## Authoring Templates
+
+When writing `PROFILE.md`, `resources/commits.md`, `resources/prs.md`, or `resources/issues.md`, read [repo-templates.md](repo-templates.md) and use it as fill-in scaffolding. Remove placeholders from final files and delete sections that are genuinely unavailable.
+
+Apply these rules even before loading the templates:
+
+- Use fixed-field resource sections separated by `---`; do not use Markdown tables for PRs or issues.
+- Write search-grade `Description` fields that explain what the PR/issue covers, when future agents should open it, affected modules/files/behaviors, concrete search cues, and evidence strength.
+- Do not copy raw summaries or headings into descriptions; synthesize routing cues from raw facets and current project understanding.
+- Do not add persistent `indexes/*.json` files or `index:` frontmatter; search `resources/*.md` directly and open raw JSON only for build/debug evidence.

package/lib/memorax-code-claude-marketplace/plugins/memorax-code-claude-adapter/skills/memorax-code/references/repo-read.md

@@ -0,0 +1,96 @@
+# Repo Memory Read
+
+## Role And Demand Gate
+
+Use existing `.repo_memory/` as a routing layer for repository identity, architecture, history, PR/issue context, remembered fixes, and cross-module search. Live code and tests remain authoritative.
+
+Select this reference for broad repo introduction, history, architecture background, cross-module routing, PR/issue context, design rationale, or stale-memory awareness. Skip this reference for narrow tasks with a clear live-code target.
+
+Only a relevant `repo-read` invokes `maintain`. Commit arrival, PR merge, and elapsed time alone do not invoke it. Explicit build, rebuild, or update requests still route through `SKILL.md` to `repo-build.md` or `repo-update.md`.
+
+## Repository And Helper
+
+Resolve the repository in this order:
+
+1. Use the user's explicit local path.
+2. Otherwise use the current workspace Git root.
+3. Infer a named local repo only when the match is unambiguous.
+4. Ask for the path only when multiple repos remain plausible.
+
+Derive memory as `<repo>/.repo_memory`; never ask for a memory-directory path. If the target is not inside a Git worktree, skip maintenance and continue from live files.
+
+`<skill-dir>` is the parent of this file's `references/` directory. The packaged client helper is:
+
+```bash
+node '<skill-dir>/../../hooks/repo-memory-job.mjs' maintain --repo '<repo>'
+```
+
+Use it only when it is a regular file. It validates the generated bundle, evaluates the configured local update policy without provider network access, and atomically selects one outcome:
+
+- `bundle_missing` or `bundle_invalid`: start supervised build;
+- a triggered policy decision: start supervised update;
+- `up_to_date`: no-op;
+- `active_job`: deduplicate against the running job.
+
+The default policy remains `adaptive(5 commits OR 24 hours)`. A missing or non-ancestor baseline always selects repair-capable update. The helper owns the detailed policy, validation, lock, snapshot, and launcher rules; do not reproduce them in the foreground.
+
+## Retrieval
+
+If `.repo_memory/PROFILE.md` is a readable regular file, read it once. Treat its descriptions as routing cues, not proof.
+
+Search `PROFILE.md` and `.repo_memory/resources/` with a combined query built from the user's strongest handles: path, basename, symbol, command, PR/issue number, error text, module, branch, environment variable, or config key.
+
+```bash
+rg -n '<handle-1>|<handle-2>' \
+  .repo_memory/PROFILE.md .repo_memory/resources
+```
+
+Use:
+
+- `resources/commits.md` for local history and regressions;
+- `resources/prs.md` for merged or active implementation context;
+- `resources/issues.md` for symptoms, requests, and requirements.
+
+If a read is missing, unreadable, or structurally mixed, discard conclusions that depend only on the bundle. Do not repair it in the foreground.
+
+## Retrieval Budget
+
+- Read `PROFILE.md` at most once.
+- Run at most 2 combined `rg` commands.
+- Stop repo-memory retrieval as soon as the hits are sufficient.
+- Open only the matched resource section when `rg` context is insufficient.
+
+Do NOT open these unless the user explicitly asks or a compact hit contains only a `facetId`:
+
+- `.repo_memory/raw/*.json`;
+- `docs/`, `packages/`, `tests/`, or other live source directories.
+
+The live directories restriction applies only during the bounded memory phase. Current implementation claims and code edits still require live-code verification after the maintenance handoff.
+
+## Single Maintenance Handoff
+
+After the final repo-memory read, run `maintain` as the very next tool action. Do not run it in parallel with a repo-memory read. Do not inspect live code, maintained documentation, Git evidence, run unrelated tools, or answer between them.
+
+If no repo-memory read was possible, run it immediately after detecting that state. The same handoff applies when hits already answer the question or the retrieval budget is exhausted.
+
+After it returns:
+
+- For `up_to_date`, a triggered update, or `active_job`, use consistent hits as best-effort context.
+- For `bundle_missing` or `bundle_invalid`, discard generated hits and continue from live code and maintained documentation.
+- If the helper is unavailable or fails, do not improvise maintenance. Use consistent hits only when they were readable; otherwise use live evidence.
+
+Do not read repo memory again after `maintain` returns. Do not wait, poll, retry, or expose the command, decision payload, job id, paths, prompt, final message, or logs. Never replace the packaged helper with a generic subagent.
+
+## Answer And Trust Rules
+
+Answer history, architecture, and context questions from sufficient memory hits after the handoff. If two bounded searches miss, say what was not found and ask whether to inspect more deeply.
+
+Continue into live evidence after the handoff when the user asks about current behavior, requests an edit, or the bundle was unavailable. Keep these distinctions explicit:
+
+- live code and targeted verification are stronger than generated memory;
+- tests are stronger than PR or issue summaries;
+- commits and merged PRs are historical evidence, not current-behavior proof;
+- open PRs describe intent;
+- issues describe problem context.
+
+Never create, update, delete, or repair repo-memory files in the foreground `repo-read` task.

package/lib/memorax-code-claude-marketplace/plugins/memorax-code-claude-adapter/skills/memorax-code/references/repo-templates.md

@@ -0,0 +1,270 @@
+# Repo Memory Authoring Templates
+
+Use these templates as fill-in scaffolds. Replace all bracketed placeholders with conclusions from local code inspection and raw facets. Remove sections that are genuinely unavailable; do not leave placeholders in final files.
+
+### `.repo_memory/PROFILE.md`
+
+```markdown
+---
+schema: "repo_memory_profile.v0.1"
+layout: "profile_with_progressive_resources.v0.1"
+disclosure_model: "progressive"
+repo_name: "[repo name]"
+repo_owner: "[owner or empty]"
+repo_full_name: "[owner/name or empty]"
+repo_url: "[remote URL or empty]"
+code_host_provider: "github|gitlab|none"
+source_repo_path: "[absolute repo path]"
+generated_at: "[ISO timestamp]"
+build_mode: "lightweight|deep"
+local_head: "[git HEAD]"
+local_branch: "[branch or detached HEAD]"
+working_tree_state: "clean|dirty|unknown"
+trust_state: "draft"
+code_host_resource_state: "available|unavailable|partial"
+resources:
+  commits: "resources/commits.md"
+  prs: "resources/prs.md"
+  issues: "resources/issues.md"
+raw:
+  prepare_report: "raw/prepare-report.json"
+  commit_facets: "raw/git-commits.json"
+  provider_facets: "raw/github-facets.json|raw/gitlab-facets.json|"
+---
+
+# [Repo Name] Repo Memory Profile
+
+## Identity And Checkout
+
+- Repository: `[owner/name]` at `[absolute path]`.
+- Local HEAD when prepared: `[sha]` on `[branch]`.
+- Prepared at: `[timestamp]`; working tree was `[clean/dirty + explanation]`.
+- License: `[license if known]`.
+- Primary purpose: [1-3 sentences explaining what this project does, based on docs and code].
+
+## Evidence Inspected
+
+- Build mode: `[lightweight|deep]`.
+- Root docs and agent instructions: `[README/docs/AGENTS.md/CLAUDE.md or similar files inspected]`.
+- Module docs: `[module README/docs inspected]`.
+- Representative source: `[important source/entrypoint files inspected, or 'not inspected in lightweight mode']`.
+- Manifests/scripts/CI: `[manifests, scripts, workflows inspected, or 'not inspected in lightweight mode']`.
+- Local commit snapshot: `[raw/git-commits.json status and count]`.
+- Historical code-host snapshot: `[raw/github-facets.json or raw/gitlab-facets.json status and counts]`.
+
+## Agent Consumption Rules
+
+1. Read this file first, then inspect the live code path you plan to edit. Memory is an index, not proof.
+2. [Repo-specific safety or ownership rule].
+3. [Repo-specific preferred extension pattern].
+4. Treat PR/issue resources as historical/contextual; verify current behavior in code and tests.
+
+## Coding Memory Boundary
+
+This repo memory is a cold-start repository map. Use it for module routing,
+historical PR/issue context, architecture boundaries, verification gates, and
+repository-specific conventions.
+
+Runtime coding memory is narrower and should take precedence when it matches
+the current repo, module, API, behavior, lifecycle surface, ownership boundary,
+or failure mode. Use runtime coding memory for verified repair invariants,
+failed-attempt evidence, mutable-state ownership, callback/hook boundaries,
+adapter behavior, validation contracts, and other task-learned engineering
+lessons.
+
+Do not treat repo memory, commits, PRs, or issues as implementation recipes.
+They are routing evidence and historical context. Always verify current
+behavior against live source and focused checks before editing.
+
+## Architecture Map
+
+- `[module/path]`: [What it does, important entrypoints, how it relates to other modules].
+- `[module/path]`: [What it does, important entrypoints, how it relates to other modules].
+
+## Runtime Flow
+
+- [Main runtime/request/training/build flow].
+- [How modules communicate or hand off data].
+- [Where state, artifacts, configs, or generated outputs live].
+
+## Verification Gates
+
+- [Documentation-only verification].
+- [Syntax/static checks].
+- [Unit/smoke/integration checks].
+- [Expensive or environment-dependent checks and required services].
+
+## Resource Pointers
+
+- Commit resource: `.repo_memory/resources/commits.md`.
+- PR resource: `.repo_memory/resources/prs.md`.
+- Issue resource: `.repo_memory/resources/issues.md`.
+- Raw local commit facets: `.repo_memory/raw/git-commits.json`.
+- Raw code-host facets: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets.json`.
+- Mechanical preparation facts: `.repo_memory/raw/prepare-report.json`.
+
+## Code Host Snapshot Notes
+
+- [Major merged PR themes].
+- [Recent local commit themes].
+- [Open PR themes and warning that they are not landed behavior].
+- [Issue clusters / user pain points].
+
+## Retrieval Flow
+
+1. Start here for module ownership, boundaries, and verification gates.
+2. Open the relevant module docs/source entrypoints for the target path.
+3. Search `resources/*.md` by module, file, symbol, branch, SHA, PR/MR number, or issue number when historical context matters.
+4. Open matched `resources/*.md` sections for compact human-readable commit/PR/issue routing.
+5. Use `raw/git-commits.json`, `raw/github-facets.json`, or `raw/gitlab-facets.json` only when compact resources are insufficient or a matched section points to a raw facet.
+```
+
+### `.repo_memory/resources/commits.md`
+
+Use fixed-field sections, not Markdown tables. Every commit needs a search-grade `Description` following the standard in `SKILL.md`. Do not paste the full raw summary; full raw summaries stay in `../raw/git-commits.json`.
+
+```markdown
+---
+schema: "repo_memory_commit_resource.v0.1"
+repo_full_name: "[owner/name or local repo name]"
+generated_at: "[ISO timestamp]"
+source: "git_commit_facets"
+resource_count: [count]
+trust_state: "draft_resource"
+raw_source: "../raw/git-commits.json"
+---
+
+# Commit Resource Snapshot
+
+Source: `.repo_memory/raw/git-commits.json`. Treat commits as local checkout history only: they are useful routing evidence, but current-code verification is still required.
+
+## Commit [short_sha]: [title]
+
+- SHA: `[full sha]`
+- Author: `[author name]`
+- Authored: `[ISO timestamp]`
+- Modules: `[semantic modules for human routing]`
+- Path modules: `[path prefixes from raw facets or current inspection]`
+- Description: [2-4 search-grade sentences: what this commit changes, when future agents should open it, affected modules/files/runtime behavior, search cues, and evidence strength]
+- Key files: `[path/a.py]`, `[path/b.md]`
+- Diff: `[changed_files] files, +[additions]/-[deletions]`
+- Parent count: `[count]`
+- Agent note: [how future agents should treat this commit]
+- Raw lookup: `facetId=commit.abc1234`
+
+---
+
+## Commit [short_sha]: [title]
+
+- SHA: `...`
+- Author: `...`
+- Authored: `...`
+- Modules: `...`
+- Path modules: `...`
+- Description: ...
+- Key files: ...
+- Diff: ...
+- Parent count: ...
+- Agent note: ...
+- Raw lookup: `facetId=commit.abc1234`
+```
+
+### `.repo_memory/resources/prs.md`
+
+Use fixed-field sections, not Markdown tables. Every GitHub PR or GitLab MR needs a search-grade `Description` following the standard in `SKILL.md`. Do not paste the full raw summary; full raw summaries stay in `../raw/github-facets.json` or `../raw/gitlab-facets.json`.
+
+```markdown
+---
+schema: "repo_memory_pr_resource.v0.1"
+repo_full_name: "[owner/name]"
+generated_at: "[ISO timestamp]"
+source: "github_resource_facets|gitlab_resource_facets"
+resource_count: [count]
+trust_state: "draft_resource"
+raw_source: "../raw/github-facets.json|../raw/gitlab-facets.json"
+---
+
+# Pull Request Resource Snapshot
+
+Source: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets.json`. Treat PRs/MRs as historical context only: merged PRs/MRs still require current-code verification, open PRs/MRs are branch intent, and closed-unmerged PRs/MRs are weak evidence.
+
+## PR/MR #[number]: [title]
+
+- State: `MERGED|OPEN|CLOSED` [include draft if applicable]
+- Branch: `base <- head`
+- Modules: `[semantic modules for human routing]`
+- Path modules: `[path prefixes from raw facets or current inspection]`
+- Description: [2-4 search-grade sentences: what this PR explains, when future agents should open it, affected modules/files/runtime behavior, search cues, and evidence strength]
+- Key files: `[path/a.py]`, `[path/b.md]`
+- Diff: `[changed_files] files, +[additions]/-[deletions]`
+- Linked issues: `#[issue]` or `-`
+- Commit signal: [1-3 commit headlines or `-`]
+- Agent note: [how future agents should treat this PR]
+- URL: [PR URL]
+- Raw lookup: use `facetId=pr.123` for GitHub PRs or `facetId=mr.123` for GitLab MRs.
+
+---
+
+## PR/MR #[number]: [title]
+
+- State: `...`
+- Branch: `...`
+- Modules: `...`
+- Path modules: `...`
+- Description: ...
+- Key files: ...
+- Diff: ...
+- Linked issues: ...
+- Commit signal: ...
+- Agent note: ...
+- URL: ...
+- Raw lookup: use `facetId=pr.123` for GitHub PRs or `facetId=mr.123` for GitLab MRs.
+```
+
+### `.repo_memory/resources/issues.md`
+
+Use fixed-field sections, not Markdown tables. Every issue needs a search-grade `Description` following the standard in `SKILL.md`. Keep evidence compact; full raw summaries stay in `../raw/github-facets.json` or `../raw/gitlab-facets.json`.
+
+```markdown
+---
+schema: "repo_memory_issue_resource.v0.1"
+repo_full_name: "[owner/name]"
+generated_at: "[ISO timestamp]"
+source: "github_resource_facets|gitlab_resource_facets"
+resource_count: [count]
+trust_state: "draft_resource"
+raw_source: "../raw/github-facets.json|../raw/gitlab-facets.json"
+---
+
+# Issue Resource Snapshot
+
+Source: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets.json`. Treat issues as requirement, bug, support, or planning context; verify against current code before acting.
+
+## Issue #[number]: [title]
+
+- State: `OPEN|CLOSED`
+- Modules: `[semantic modules for human routing]`
+- Path modules: `[path prefixes from linked PR facets or current inspection, or -]`
+- Description: [2-4 search-grade sentences: what user problem/request this issue explains, when future agents should open it, affected behavior/modules, symptoms/errors, search cues, and evidence strength]
+- Evidence: [short evidence: label, error, user pain point, requirement, or theme]
+- Linked PRs: `#[pr]` or `-`
+- Linked branches: `base <- head` or `-`
+- Agent note: [how future agents should use this issue]
+- URL: [Issue URL]
+- Raw lookup: `facetId=issue.123`
+
+---
+
+## Issue #[number]: [title]
+
+- State: `...`
+- Modules: `...`
+- Path modules: `...`
+- Description: ...
+- Evidence: ...
+- Linked PRs: ...
+- Linked branches: ...
+- Agent note: ...
+- URL: ...
+- Raw lookup: `facetId=issue.123`
+```