@memorax/memorax-code 0.1.1 → 0.1.3

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

@@ -4,11 +4,13 @@ Use these templates as fill-in scaffolds. Replace all bracketed placeholders wit
 
 ### `.repo_memory/PROFILE.md`
 
+`PROFILE.md` is the only fixed conceptual wiki file. It is a wiki landing page, not a dense resource index. It should read like a wiki-style repository memory home page: concise project identity, first-use path, major areas, supporting pages, and historical/provider pointers. Keep MemoraX frontmatter so the validator and maintenance hooks can still trust the bundle.
+
 ```markdown
 ---
-schema: "repo_memory_profile.v0.1"
-layout: "profile_with_progressive_resources.v0.1"
-disclosure_model: "progressive"
+schema: "repo_memory_profile.v0.2"
+layout: "wiki_landing_page.v0.1"
+disclosure_model: "progressive_wiki"
 repo_name: "[repo name]"
 repo_owner: "[owner or empty]"
 repo_full_name: "[owner/name or empty]"
@@ -32,91 +34,146 @@ raw:
   provider_facets: "raw/github-facets.json|raw/gitlab-facets.json|"
 ---
 
-# [Repo Name] Repo Memory Profile
+# [Repo Name] Repository Wiki
+
+[One short paragraph explaining what this repository is, who uses it, and the primary runtime/package/product surface. Ground this in inspected docs or source.]
+
+- Repository: `[owner/name or local repo]`
+- Local HEAD when prepared: `[sha]` on `[branch]`
+- Build mode: `[lightweight|deep]`; working tree was `[clean/dirty + explanation]`
+- License: `[license if known]`
+
+## What This Repo Contains
+
+| Area | What it does |
+|------|--------------|
+| `[repo-native product/module/workflow name]` (`path/`) | [Plain-language responsibility and primary entrypoint.] |
+| `[repo-native product/module/workflow name]` (`path/`) | [Plain-language responsibility and primary entrypoint.] |
+
+## How It Works
+
+[Five to ten sentences describing the main runtime/build/request/data flow. Link to supporting pages instead of explaining every detail here. Use conservative wording when lightweight mode did not inspect representative source.]
+
+## First-Use Path
+
+```bash
+[install or setup command]
+[one fast verification or smoke command]
+```
+
+[Explain the shortest safe path a future agent should use to orient, build, test, or run the project.]
+
+## Major Areas
+
+Choose these rows from `.repo_memory/_plan.md` after clustering inspected docs/source paths. Do not assume fixed page names; generic names are fallback names only when repository vocabulary gives no stronger topic.
+
+| Area | Page | What It Covers |
+|------|------|----------------|
+| `[repo-native area name]` | [`[human page title]`](./repo-native-topic.md) | [What task cluster this page routes and why it is a canonical home.] |
+| `[repo-native area name]` | [`[human page title]`](./repo-native-topic.md) | [What task cluster this page routes and why it is a canonical home.] |
+
+## Supporting Pages
 
-## Identity And Checkout
+- [`[human page title]`](./repo-native-topic.md) - open when [task cue, change surface, workflow, or risk].
+- [`[human page title]`](./another-repo-native-topic.md) - open when [task cue, change surface, workflow, or risk].
+
+## Agent Consumption Rules
+
+1. Read this file first, then open only the supporting page relevant to the task. Memory is a map, not proof.
+2. Verify current behavior against live source, configs, tests, or executable checks before editing or making strong claims.
+3. Treat commits, PRs/MRs, and issues as historical routing context; they do not prove current checkout behavior.
+4. Prefer source paths and commands linked from supporting pages over broad repository scanning.
+
+## Coding Memory Boundary
 
-- 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].
+This repo memory is a cold-start repository map presented as a repository wiki. Use it for module routing, architecture boundaries, verification gates, historical PR/issue context, 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.
+
+## Provider Context
+
+- [Historical commits](./resources/commits.md) - local checkout history and regression routing.
+- [Historical PRs/MRs](./resources/prs.md) - implementation context from provider facets when available.
+- [Historical issues](./resources/issues.md) - user/request/problem context when available.
+- Raw local commit facets: `./raw/git-commits.json`.
+- Raw code-host facets: `./raw/github-facets.json` or `./raw/gitlab-facets.json` when present.
 
 ## 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
+### `.repo_memory/_plan.md`
 
-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.
+Create this temporary planning artifact after discovery and before final wiki writing. Use it to cluster repository concepts and choose natural page boundaries. Remove `_plan.md` before final validation; it is not part of the durable bundle.
 
-## Coding Memory Boundary
+```markdown
+# Repo Memory Wiki Plan
+
+## Candidate Domains Considered
+
+- [selected, merged, or skipped candidate domain] - [source evidence and decision].
 
-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.
+## Intended Final Pages
 
-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.
+| Page | Purpose | Source evidence | Boundary |
+|------|---------|-----------------|----------|
+| `repo-native-topic.md` | [Future-agent task this page routes.] | [Docs/source/tests/scripts inspected.] | [What belongs here and what belongs elsewhere.] |
 
-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.
+## Canonical Homes And Overlaps
 
-## Architecture Map
+- [Overlapping concept] belongs in `[page]`; link from `[other page]` instead of duplicating because [reason].
+
+## Weak Evidence And Verification Needs
+
+- [Claim/path/command] needs [specific verification] before final writing, or should be omitted.
+```
+
+### `.repo_memory/<repo-native-topic>.md`
+
+Create supporting conceptual pages after clustering inspected evidence. Name pages from repository vocabulary, not from this template. Use lowercase kebab-case filenames derived from product surfaces, runtime components, commands, protocols, adapters, workflows, data models, operations, or other durable repository concepts. Generic names are fallback names only when repository vocabulary gives no stronger topic. Every conceptual page must include frontmatter so validation can scan it.
+
+```markdown
+---
+schema: "repo_memory_wiki_page.v0.1"
+page_type: "architecture|workflow|data-model|integration|operation|testing|extension|domain"
+generated_at: "[ISO timestamp]"
+source_profile: "PROFILE.md"
+trust_state: "draft_wiki_page"
+---
 
-- `[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].
+# [Human Documentation Title]
 
-## Runtime Flow
+## Purpose
 
-- [Main runtime/request/training/build flow].
-- [How modules communicate or hand off data].
-- [Where state, artifacts, configs, or generated outputs live].
+[Explain which future tasks should open this page and what decisions it helps route.]
 
-## Verification Gates
+## Key Paths
 
-- [Documentation-only verification].
-- [Syntax/static checks].
-- [Unit/smoke/integration checks].
-- [Expensive or environment-dependent checks and required services].
+| Path | Responsibility | When to inspect |
+|------|----------------|-----------------|
+| `path/to/file-or-dir` | [What it owns.] | [Task cue, symbol, command, or failure mode.] |
 
-## Resource Pointers
+## Flow Or Boundaries
 
-- 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`.
+[Explain the concept, lifecycle, dependency direction, or ownership boundary. Prefer short paragraphs and bullets over exhaustive API reference.]
 
-## Code Host Snapshot Notes
+## Verification
 
-- [Major merged PR themes].
-- [Recent local commit themes].
-- [Open PR themes and warning that they are not landed behavior].
-- [Issue clusters / user pain points].
+- [Fast command or source check relevant to this page.]
+- [Expensive or environment-dependent check, or say none identified.]
 
-## Retrieval Flow
+## Agent Notes
 
-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.
+- Treat this page as routing context and verify current behavior in live source before editing.
+- [One repo-specific caution, extension rule, or likely pitfall.]
 ```
 
 ### `.repo_memory/resources/commits.md`
@@ -141,6 +198,7 @@ Source: `.repo_memory/raw/git-commits.json`. Treat commits as local checkout his
 ## Commit [short_sha]: [title]
 
 - SHA: `[full sha]`
+- Evidence status: [One short sentence describing local-history evidence strength and whether current source was verified.]
 - Author: `[author name]`
 - Authored: `[ISO timestamp]`
 - Modules: `[semantic modules for human routing]`
@@ -157,6 +215,7 @@ Source: `.repo_memory/raw/git-commits.json`. Treat commits as local checkout his
 ## Commit [short_sha]: [title]
 
 - SHA: `...`
+- Evidence status: ...
 - Author: `...`
 - Authored: `...`
 - Modules: `...`
@@ -169,6 +228,24 @@ Source: `.repo_memory/raw/git-commits.json`. Treat commits as local checkout his
 - Raw lookup: `facetId=commit.abc1234`
 ```
 
+When commit history is disabled by policy, still write a disabled resource file:
+
+```markdown
+---
+schema: "repo_memory_commit_resource.v0.1"
+repo_full_name: "[owner/name or local repo name]"
+generated_at: "[ISO timestamp]"
+source: "history_disabled"
+resource_count: 0
+trust_state: "disabled_by_policy"
+raw_source: ""
+---
+
+# Commit Resource Snapshot
+
+No commit evidence was collected because historical evidence was disabled for this build. This is a collection-policy statement, not proof that the repository has no commits.
+```
+
 ### `.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`.
@@ -191,6 +268,7 @@ Source: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets
 ## PR/MR #[number]: [title]
 
 - State: `MERGED|OPEN|CLOSED` [include draft if applicable]
+- Evidence status: [One short sentence describing historical/current relevance and whether current source was verified.]
 - Branch: `base <- head`
 - Modules: `[semantic modules for human routing]`
 - Path modules: `[path prefixes from raw facets or current inspection]`
@@ -208,6 +286,7 @@ Source: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets
 ## PR/MR #[number]: [title]
 
 - State: `...`
+- Evidence status: ...
 - Branch: `...`
 - Modules: `...`
 - Path modules: `...`
@@ -243,6 +322,7 @@ Source: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets
 ## Issue #[number]: [title]
 
 - State: `OPEN|CLOSED`
+- Evidence status: [One short sentence describing issue evidence strength, relevance, and whether current source was verified.]
 - 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]
@@ -268,3 +348,43 @@ Source: `.repo_memory/raw/github-facets.json` or `.repo_memory/raw/gitlab-facets
 - URL: ...
 - Raw lookup: `facetId=issue.123`
 ```
+
+### Disabled Or Unavailable Resource Files
+
+Use this pattern when historical evidence or provider evidence was intentionally not collected, unavailable, or degraded to local-only. Keep `resource_count: 0` and `raw_source: ""`; do not fabricate PRs, MRs, issues, or raw provider evidence. Use `source: "history_disabled"` when the entire history channel is disabled, `source: "provider_skipped_local_only"` when provider collection was skipped for a local-only build, and `source: "provider_unavailable"` when provider collection could not be completed.
+
+For PR/MR resources:
+
+```markdown
+---
+schema: "repo_memory_pr_resource.v0.1"
+repo_full_name: "[owner/name or local repo name]"
+generated_at: "[ISO timestamp]"
+source: "provider_skipped_local_only|provider_unavailable|history_disabled"
+resource_count: 0
+trust_state: "unavailable_local_only|disabled_by_policy"
+raw_source: ""
+---
+
+# Pull Request Resource Snapshot
+
+No provider evidence was collected for PRs/MRs in this build. This means PR/MR history is unavailable in the memory bundle; it does not mean the repository has no PRs or MRs.
+```
+
+For issue resources:
+
+```markdown
+---
+schema: "repo_memory_issue_resource.v0.1"
+repo_full_name: "[owner/name or local repo name]"
+generated_at: "[ISO timestamp]"
+source: "provider_skipped_local_only|provider_unavailable|history_disabled"
+resource_count: 0
+trust_state: "unavailable_local_only|disabled_by_policy"
+raw_source: ""
+---
+
+# Issue Resource Snapshot
+
+No provider evidence was collected for issues in this build. This means issue history is unavailable in the memory bundle; it does not mean the repository has no issues.
+```

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

@@ -2,7 +2,7 @@
 
 ## 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.
+Update existing repo memory from a delta, not a full rebuild. Treat the current `.repo_memory/` bundle as the baseline, follow the effective history policy, detect only the enabled local commit 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.
 
@@ -26,9 +26,18 @@ If `.repo_memory/PROFILE.md` is missing, stop and route to `repo-build.md`; do n
 
 ## 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`.
+Updater uses `<skill-dir>/defaults.json` so build and update operations stay aligned. It reads `repoHistory.mode`, `repoHistory.limits.prs`, `repoHistory.limits.issues`, and `summaryChars`, with compatibility fallback to legacy `limits.prs` and `limits.issues`; local commit deltas are not limit-capped because they are computed from the stored baseline commit to current `HEAD` when commit history is enabled.
 
-Override one updater run with `--pr-limit`, `--issue-limit`, or `--summary-chars`. Do not edit `defaults.json` for a one-run updater request.
+Override one updater run with `--history-mode`, `--pr-limit`, `--issue-limit`, or `--summary-chars`. Do not edit `defaults.json` for a one-run updater request.
+
+History policy modes:
+
+- `none`: skip local commit deltas and provider PR/MR/issue deltas.
+- `commits-only` or `local-only`: detect local commit deltas and skip provider PR/MR/issue deltas.
+- `provider`: detect local commit deltas and fetch provider PR/MR/issue deltas when provider evidence is ready.
+- `provider-required`: detect local commit deltas and require provider PR/MR/issue evidence rather than silently authoring provider resources without evidence.
+
+Do not re-enable commit or provider channels disabled by policy. Use the detector's `effective_settings.history` block as the authority for which history channels are enabled.
 
 ## User Count Requests
 
@@ -52,13 +61,15 @@ python3 <skill-dir>/scripts/detect_updates.py \
 
 The detector:
 
+- reads the effective history policy from `repoHistory.mode` and reports it in `effective_settings.history`;
 - 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;
+- compares local git `HEAD` against the newest stored commit only when commit history is enabled;
+- reports `local_commit_status.status: "skipped"` with `reason: "history_disabled_by_policy"` when `repoHistory.mode` disables commit history;
 - 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;
+- detects provider state from live git remotes and provider CLIs only when provider history is enabled;
+- fetches bounded latest GitHub/GitLab PR/MR/issue facets only when provider history is enabled and 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.
 
@@ -68,7 +79,7 @@ When provider fetch succeeds, the report includes fetched authoring evidence und
 
 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.
+Use `--history-mode local-only` or `--history-mode none` when the user requests a one-run history-policy override. `--provider-mode off` remains supported as a compatibility provider-only override when provider access is intentionally unavailable.
 
 ## Provider Sandbox and Transport Failures