@memorax/memorax-code 0.1.9 → 0.1.10

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

@@ -0,0 +1,390 @@
+# 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`
+
+`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.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]"
+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] 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
+
+- [`[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
+
+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
+
+- 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]`.
+```
+
+### `.repo_memory/_plan.md`
+
+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.
+
+```markdown
+# Repo Memory Wiki Plan
+
+## Candidate Domains Considered
+
+- [selected, merged, or skipped candidate domain] - [source evidence and decision].
+
+## Intended Final Pages
+
+| 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.] |
+
+## Canonical Homes And Overlaps
+
+- [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"
+---
+
+# [Human Documentation Title]
+
+## Purpose
+
+[Explain which future tasks should open this page and what decisions it helps route.]
+
+## Key Paths
+
+| Path | Responsibility | When to inspect |
+|------|----------------|-----------------|
+| `path/to/file-or-dir` | [What it owns.] | [Task cue, symbol, command, or failure mode.] |
+
+## Flow Or Boundaries
+
+[Explain the concept, lifecycle, dependency direction, or ownership boundary. Prefer short paragraphs and bullets over exhaustive API reference.]
+
+## Verification
+
+- [Fast command or source check relevant to this page.]
+- [Expensive or environment-dependent check, or say none identified.]
+
+## Agent Notes
+
+- 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`
+
+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]`
+- 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]`
+- 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: `...`
+- Evidence status: ...
+- Author: `...`
+- Authored: `...`
+- Modules: `...`
+- Path modules: `...`
+- Description: ...
+- Key files: ...
+- Diff: ...
+- Parent count: ...
+- Agent note: ...
+- 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`.
+
+```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]
+- 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]`
+- 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: `...`
+- Evidence status: ...
+- 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`
+- 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]
+- 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`
+```
+
+### 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-codebuddy-adapter/skills/memorax-code/references/repo-update.md

@@ -0,0 +1,127 @@
+# 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, 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.
+
+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` 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 `--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
+
+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 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 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 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.
+
+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 `--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
+
+`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.