@memorax/memorax-code 0.1.0

package/lib/memorax-code-codex-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`
+```

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/repo-update.md

@@ -0,0 +1,116 @@
+# Repo Memory Update
+
+## Core Principle
+
+Update existing repo memory from a delta, not a full rebuild. Treat the current `.repo_memory/` bundle as the baseline, detect the newest local commits and provider PR/MR/issue changes, then edit only the affected resources.
+
+Do not rebuild the whole bundle by default. Return to `SKILL.md` and use `repo-build.md` only when `.repo_memory/PROFILE.md` is missing, the existing memory is structurally unusable, or the user explicitly asks for a full rebuild.
+
+This is the incremental updater, not the daily reader. Use `repo-read.md` for task-time search over existing memory. Use `repo-build.md` for first-time creation, full rebuild flows, or full refresh work that should rerun builder collection with `collect_all.py --reuse`.
+
+## Prerequisite
+
+The user selects a repository, not a memory directory. Derive the memory path as `<repo>/.repo_memory`.
+
+Require:
+
+- `<repo>` is a local git repository;
+- `<repo>/.repo_memory/PROFILE.md` exists;
+- existing `PROFILE.md` and `resources/*.md` are treated as the baseline.
+
+If `.repo_memory/PROFILE.md` is missing, stop and route to `repo-build.md`; do not fabricate an incremental baseline from live files alone.
+
+## Path Convention
+
+`<skill-dir>` means the parent directory of the `references/` directory containing this file.
+
+## Default Settings
+
+Updater uses `<skill-dir>/defaults.json` for provider comparison defaults so build and update operations stay aligned. It reads `limits.prs`, `limits.issues`, and `summaryChars`; local commit deltas are not limit-capped because they are computed from the stored baseline commit to current `HEAD`.
+
+Override one updater run with `--pr-limit`, `--issue-limit`, or `--summary-chars`. Do not edit `defaults.json` for a one-run updater request.
+
+## User Count Requests
+
+If the user says how many PRs/MRs or issues to compare, pass explicit one-run flags:
+
+- "PR 拉 20 条" means add `--pr-limit 20`.
+- "issue 拉 30 条" means add `--issue-limit 30`.
+- "PR 和 issue 都拉 50 条" means add `--pr-limit 50 --issue-limit 50`.
+
+Only change `<skill-dir>/defaults.json` when the user asks to change future default behavior.
+
+## Detection
+
+Start every updater run by detecting deltas:
+
+```bash
+python3 <skill-dir>/scripts/detect_updates.py \
+  --repo-path <repo-path> \
+  --pretty
+```
+
+The detector:
+
+- reads the commit baseline from `PROFILE.md` `local_head`, with a fallback to the nearest stored ancestor commit in `resources/commits.md`;
+- reads PR/MR and issue baselines from `resources/prs.md` and `resources/issues.md`, enriched by existing raw provider facets when available;
+- compares local git `HEAD` against the newest stored commit;
+- reports `local_commit_status.status: "skipped"` with `reason: "missing_baseline_commit"` when no stored local commit baseline can be found;
+- reports `local_commit_status.status: "skipped"` with `reason: "baseline_not_ancestor_of_head"` when history was rebased or force-pushed, instead of silently returning no commit delta;
+- detects provider state from live git remotes and provider CLIs;
+- fetches bounded latest GitHub/GitLab PR/MR/issue facets when provider evidence is available;
+- reports added or changed PR/MR/issue numbers without editing memory files;
+- reports provider items missing from the current bounded window as `baseline_only_numbers`, not as deletions.
+
+Warnings such as rewritten commit baselines or provider fetch failures are returned as structured `notices[]` with `render_as: "assistant_message"`. Show these notices to the user as normal assistant messages; do not bury them in terminal output.
+
+When provider fetch succeeds, the report includes fetched authoring evidence under `current.provider_items.pull_requests` and `current.provider_items.issues`. Use those facets, plus existing raw/provider resources when needed, to write or replace search-grade sections; do not author provider sections from number-only deltas.
+
+The report also includes `builder_helpers` fingerprints for the sibling builder files that updater depends on, including `path`, `exists`, `mtime_ns`, and `size_bytes`. Use this only for compatibility diagnostics; it is not evidence for authoring repo-memory resources.
+
+Use `--provider-mode off` when the user requested a local-only update or provider access is intentionally unavailable.
+
+## Provider Sandbox and Transport Failures
+
+`gh/glab` provider delta detection needs external network access. If `current.provider_fetch.ok` is false, or notice/stderr shows `fetch failed`, timeout, DNS, connection, TLS, `ENOTFOUND`, `EAI_AGAIN`, or similar transport text, show `Provider Delta Fetch Failed`, keep existing PR/MR/issue resources unchanged, and continue only with safe local commit updates.
+
+Verify provider authentication in the same normal shell with the command reported by `detect_updates.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 `detect_updates.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 before editing provider resources. If only restricted shell access is available, keep existing PR/MR/issue resources unchanged and continue only with safe local commit updates. Do not treat provider fetch failure as no PR/issue delta, empty provider evidence, bad login, or bypass the detector with direct APIs, browser scraping, copied credentials, or hand-written raw facets.
+
+## Report Gates
+
+Read the JSON report as gates before editing. Stop at the first blocking gate; otherwise edit only resources named by the report.
+
+| Report field | Action |
+| --- | --- |
+| `ok: false` and missing memory | Route to `repo-build.md`; do not invent a baseline. |
+| no deltas and no notices | Report no update needed. |
+| `commit_delta_skipped: "missing_baseline_commit"` | Stop commit-resource updates; recommend full rebuild. |
+| `commit_delta_skipped: "baseline_not_ancestor_of_head"` | Stop commit-resource updates; recommend rebuild or explicit baseline reset. |
+| provider fetch failed / `Provider Delta Fetch Failed` | Keep existing PR/MR/issue resources unchanged; local commits may still be updated. |
+| `deltas.local_commits` | Update only `resources/commits.md`; refresh `PROFILE.md` local head and `generated_at` timestamp. |
+| `deltas.pull_requests.upsert_numbers` | Upsert only matching PR/MR sections from `current.provider_items.pull_requests`; preserve `baseline_only_numbers`. |
+| `deltas.issues.upsert_numbers` | Upsert only matching issue sections from `current.provider_items.issues`; preserve `baseline_only_numbers`. |
+
+Never delete prior PR/MR/issue sections because they are absent from the bounded provider fetch; deletion needs explicit user instruction or verified invalidation. Finish with the builder validator:
+
+```bash
+python3 <skill-dir>/scripts/validate_memory.py <repo-path> --pretty
+```
+
+Whenever an update changes generated repo-memory artifacts, set `PROFILE.md.generated_at` to the successful update time and `PROFILE.md.local_head` to the processed snapshot. The read-time cooldown policy uses this timestamp; do not preserve an older build time after a successful incremental update.
+
+## Authoring Rules
+
+Match existing fixed-field sections first; use builder templates only when the file shape is incomplete. Upsert by stable keys: commit SHA, PR/MR number, and issue number. Replace matching sections, append only new keys, and do not delete useful notes unless explicit instruction or verified evidence invalidates them.
+
+Every new or replaced section needs a search-grade `Description`, evidence strength, and source from local commit delta, `current.provider_items`, or raw provider files. Number-only deltas route the edit; they are not authoring evidence. Do not invent PR/MR/issue evidence when provider fetch is skipped or unavailable, paste long raw summaries, or treat validator/counts as proof of body quality.
+
+## Trust Rules
+
+- Live code and targeted verification are stronger than repo memory.
+- Local commit deltas are checkout history, not current behavior proof.
+- Provider PR/MR/issue deltas are historical or planning context, not implementation truth.
+- Open PRs/MRs are branch intent, not landed behavior.
+- Issues are user/problem context, not implementation proof.