Release/v0.3

.agents/learnings.md

@@ -13,8 +13,9 @@ Reference document for AI agents. These are hard-won insights from past RFC impl
 - **Duckborrowing is codegen policy**: when work touches lowering/emission, call arguments, collection literals, returns, match scrutinees, Rust interop, or generated `.clone()`s, route ownership through `src/backend/ir/ownership.rs` / `ValueUseSite` and update trait-bound inference/tests instead of adding local `.clone()`, `.as_ref()`, `str(...)`, or `.into()` workarounds. (Issue #121, April 2026)
 - **Forward receivers by borrow shape**: when lowering wrappers or adapters around methods, model `self` as the callable's actual receiver borrow (`&Owner` or `&mut Owner`) and pass that through directly; inserting `.clone()` hides a compiler lowering shortcut as user-visible ownership behavior and breaks mutable receiver support. (RFC 036 / issue #170)
 - **PR conflict resolution must use `origin/main` as the merge base**: when a user asks to merge main or resolve PR conflicts, inspect and merge against `origin/main`, not the local `main` branch copy. Local `main` can lag the remote and give a false “merged main” result while GitHub still reports conflicts. (RFC 015 branch, April 2026)
+- **Match ladders are a smell**: in authored `.incn` code, avoid nested `match` ladders that only peel `Option`/enum variants before continuing; prefer `if let`, early returns, or a focused `match` with shallow arms. Do not "fix" the ladder by creating a forest of one-use helpers; keep helpers only when they name a real concept. (InQL #25 source-quality cleanup, May 2026)
 - **Name repeated kind checks**: when the language lacks grouped pattern arms, do not duplicate long `kind == A or kind == B ...` chains across functions; hide the grouping behind one predicate/helper so later enum-surface changes do not drift between call sites. (Prism output-column cleanup, April 2026)
-- **Never expose local paths**: Shareable artifacts must use repo-relative paths or plain command names; absolute workstation paths like `/Users/...` leak personal details and should be blocked in hooks and avoided in docs, issues, PR text, and examples.
+- **Never expose local paths**: Shareable artifacts must use repo-relative paths or plain command names; absolute workstation paths like `/Users/...` leak personal details and should be blocked in hooks and avoided in docs, issues, PR text, and examples. For GitHub issues/PRs, run the check before the first create/update call because edit history can preserve the original text.
 - **New AST variants need full pipeline wiring**: adding a `Statement`/`Expr` variant is never parser-only; you must update formatter, feature scanners, typechecker, lowering, and any AST bridge layers in the same change or compilation/tests will break in scattered places (RFC 027 Phase 6).
 - **Method defaults need emission tests**: method default arguments can pass typechecking but still emit invalid Rust if the method-call emitter does not synthesize omitted defaults; when adding or using method defaults, include a run/codegen test that calls the method with omitted arguments. (Issue #286)
 - **Stdlib function defaults cross stages**: imported stdlib free-function defaults must be preserved from AST loading through typechecking, lowering, and emission; a typechecker-only default fix can still produce generated Rust calls with missing arguments. Add end-to-end run coverage when public stdlib APIs rely on omitted defaults. (RFC 064 / issue #342)
@@ -78,14 +79,16 @@ Reference document for AI agents. These are hard-won insights from past RFC impl
 - **Implementation docs must be user-facing**: RFCs and release notes do not satisfy user documentation for a new language/compiler feature; when behavior is user-visible, update the authored explanation/how-to/tutorial/reference docs where users actually learn the surface, not just the RFC or changelog. (RFC 049 / issue #333)
 - **Markdown prose should not be short-wrapped**: when generating authored Markdown documents, do not manually wrap prose to artificial line lengths; use natural paragraph lines unless the structure itself requires line breaks, because short-wrapped prose reads fragmented and creates noisy diffs for whitepapers, RFCs, and research docs. (Pallay research docs, April 2026)
 - **RFC phase before code**: when using `ralph-loop` for an RFC implementation, move the RFC to `In Progress` and confirm the implementation plan/checklist before writing code; do not treat lifecycle edits and phase confirmation as a post-implementation cleanup step. (RFC 016 / issue #327)
+- **RFC PR means implementation PR**: in RFC headers, `RFC PR` is the PR where the RFC was implemented or shipped, not the proposal issue or the PR that first added the Draft RFC document. Leave it unset for Draft or otherwise unimplemented RFCs even when a proposal issue exists.
 - **North-star first for RFCs**: when a maintainer asks for an RFC, start from the desired end-state contract and only discuss incremental slices after that north-star is explicit; do not reflexively shrink RFC scope into the smallest implementable change unless the user asks for rollout planning.
+- **Pre-RFC research lives in root `__research__`**: capture exploratory north-star notes, spikes, and design parking lots under the repository root `__research__/` directory, not `.agents/`; `.agents/` is for reusable agent workflows/learnings rather than project research artifacts. (Android/Incan rustc bridge ideation, May 2026)
 - **RFCs are decision records, not diaries**: keep RFCs as moment-in-time intent/status documents, and move implementation details, drift notes, and current behavior into regular docs or release notes with issue links instead of rewriting RFC narrative in flight.
 - **Generated references are gates**: when adding or changing a stdlib namespace or language registry entry, run `cargo run -p incan_core --bin generate_lang_reference` and verify no diff before publishing; `make pre-commit` alone may miss generated `language/reference/language.md` drift that CI enforces. (RFC 065 / issue #343)
 - **Implementation work must check dev version first**: before landing an implementation on the active dev line, verify the repo's actual source-of-truth version instead of assuming an older release train from stale docs or a worker worktree; at minimum, implementation work should bump `-dev.N` by one and update any versioned docs/release-note targets that track `main`. (Issue #333, April 2026)
 - **Stdlib closeouts need reference-nav parity**: when a stdlib issue changes a module's implementation shape or canonical docs path, update the stdlib reference index, MkDocs nav, and any legacy standalone reference page together; otherwise modules like `std.testing` drift out of the `language/reference/stdlib/` structure even when release notes and how-to docs were updated. (Issues #301/#302)
 - **RFC lifecycle edits need graph updates**: When an RFC is renamed, moved, split, or superseded, update inbound RFC references and regenerate `workspaces/docs-site/docs/_snippets/rfcs_refs.md` plus `workspaces/docs-site/docs/_snippets/tables/rfcs_index.md`; otherwise the docs graph silently points at stale RFC paths and statuses. (RFC 012/050/051 split)
 - **RFC checklist gaps force replanning**: In a Ralph loop, unchecked RFC `Progress Checklist` items are scope failures, not PR-body residual risks; route them back through Plan -> Do -> Check -> Act before publishing, and only use closing keywords after the RFC is fully checked and bumped. (RFC 084 / issue #453)
-- **Ralph worktrees live in encero/tmp**: for `ralph-loop`, every implementation must start in a fresh worktree under `/Users/danny/Development/encero/tmp`, not `/tmp` and not the primary checkout, so VS Code discovers the workspace and orchestration stays consistent. (RFC 016 / issue #327)
+- **Ralph worktrees live in encero/tmp**: for `ralph-loop`, every implementation must start in a fresh worktree under the workspace root's `encero/tmp` directory, not a system temp directory and not the primary checkout, so VS Code discovers the workspace and orchestration stays consistent. (RFC 016 / issue #327)
 
 ## Builtin trait stubs and stdlib method lookup (#193)
 

.agents/skills/create-github-issue/SKILL.md

@@ -25,7 +25,30 @@ description: Drafts a GitHub issue title and body using the target repository's
 
 6. **Produce the draft** — See [Output format](#output-format). For YAML `body` block semantics (markdown vs textarea vs dropdown vs checkboxes), use [reference.md](reference.md).
 
-7. **Optional: related PR or branch** — If the issue tracks follow-up work, mention the branch or PR link in the body where the template has a freeform section.
+7. **Run the public text safety gate** — Before showing the draft to the user or calling any GitHub issue creation/update tool, inspect the exact title and body that will be published. Public issue text must not contain local absolute paths, personal workspace paths, usernames from local paths, machine-specific temporary directories, shell prompts, or environment details that are not needed to reproduce the issue. Replace them with repo-relative paths, generic commands, or neutral placeholders.
+
+8. **Optional: related PR or branch** — If the issue tracks follow-up work, mention the branch or PR link in the body where the template has a freeform section.
+
+## Public Text Safety Gate
+
+GitHub issues are public by default and edits may remain visible in history. Treat the first publication as permanent.
+
+Before creating or updating an issue, manually scan the title and body for these banned patterns:
+
+- local absolute paths, including `/Users/...`, `/home/...`, `/private/...`, `/tmp/...`, and `C:\Users\...`
+- personal workspace segments copied from a local checkout path
+- commands that invoke a binary through an absolute local path
+- local machine usernames, hostnames, shell prompts, or editor-specific transient paths
+- private notes, agent state paths, scratch files, or temporary repro directories
+
+Use these replacements instead:
+
+- repo-relative paths such as `examples/session_read_transform_write_csv.incn`
+- generic commands such as `incan run examples/session_read_transform_write_csv.incn`
+- neutral environment descriptions such as `macOS`, `Linux`, `release/v0.3`, or `Incan 0.3.0-rc6`
+- short repro files embedded directly in the issue body when possible
+
+If the only known command uses an absolute local path, rewrite it before publication. Do not publish first and clean it up afterward.
 
 ## Fallbacks
 
@@ -88,3 +111,4 @@ Actual: Compiler panics with ...
 - [ ] Dropdown and checkbox options match **that file’s** YAML, not another project’s.
 - [ ] Required sections are filled or explicitly flagged as missing.
 - [ ] Title prefix and labels match the YAML when present.
+- [ ] Public text safety gate passed on the exact issue title/body before publishing.

.agents/skills/flag-compiler-bug/SKILL.md

@@ -45,7 +45,7 @@ Do not flag a compiler bug when the issue is more likely:
 
 Capture:
 
-- exact command
+- exact local command for your private working notes, then derive a sanitized public command before filing
 - exact observed output, panic text, or wrong behavior
 - affected stage if inferable: parser, typechecker, lowering, emission, runtime boundary, formatter, CLI, or LSP
 - current branch / commit / task context
@@ -100,14 +100,16 @@ Include:
 
 - minimal repro
 - expected vs actual behavior
-- exact command
+- sanitized command, using repo-relative paths and tool names instead of local absolute binary paths
 - logs / panic text / snapshot diff if relevant
 - affected stage
 - blocker status
 - workaround, if any
 - environment and commit context
 - related issue, RFC, branch, or task
 
+Before creating the issue, run the `create-github-issue` public text safety gate on the exact title/body you will publish. Do not publish absolute local paths such as `/Users/...`, `/home/...`, `/private/...`, `/tmp/...`, or commands that expose a local checkout path. If the private reproduction used a local compiler binary, publish a generic equivalent such as `incan run path/to/repro.incn` and keep commit/version information in the Environment section.
+
 If the current workflow permits creating the GitHub issue directly, do that after the duplicate check. Otherwise return the ready-to-file draft.
 
 ### 6. Return to the original task
@@ -138,5 +140,6 @@ If a real workaround exists, continue the task and explicitly record:
 
 - Repro is minimal and copy-pastable.
 - Duplicate search is explicit, not assumed.
+- Public issue text is sanitized before the first GitHub create/update call.
 - Blocking vs workaround judgment is stated plainly.
 - The original task is either paused honestly or resumed with a real workaround.

.agents/skills/review-architecture/SKILL.md

@@ -24,14 +24,28 @@ Do not own:
 - test style
 - final branch-clean judgment
 
-## Output artifact
+## Output artifacts
 
 Write a slice report at:
 
 - `.agents/state/review-report.architecture.md`
 
 Do not write to the canonical `.agents/state/review-report.md`.
 
+When the architecture report has findings, also copy the scope and findings into a lightweight central snapshot outside the repo/worktree under:
+
+- `/tmp/incan-review-findings/`
+
+Use a deterministic, descriptive filename when possible:
+
+- `YYYY-MM-DD-pr-<number>-architecture-<slug>.md`
+- `YYYY-MM-DD-branch-<branch-slug>-architecture.md`
+- `YYYY-MM-DD-review-architecture.md` when no PR or branch context is known
+
+Do not create a snapshot for clean reviews. The snapshot is raw corpus for later analysis, not canonical guidance.
+Treat `/tmp/incan-review-findings/` as an append-only central corpus for local review work: create new snapshot files, but do not delete, overwrite, prune, or "clean up" existing snapshots unless the user explicitly asks for that exact maintenance.
+Snapshot content is evidence, not a fix log. Preserve the original finding blocks verbatim, including severity, category, file path, line reference, and explanatory text. If the finding is fixed before the snapshot is written, keep the original finding as observed and add a separate `Resolution` note after it; do not replace the evidence with a resolved checklist item or a summary of the fix.
+
 ## Workflow
 
 1. Review touched code by subsystem, not merely by file.
@@ -46,6 +60,7 @@ Do not write to the canonical `.agents/state/review-report.md`.
    - maintainability warnings,
    - or design tensions.
    All three are valid findings. Classify them so downstream fixers know how to treat them, but do not suppress them.
+6. If the report contains findings, create `/tmp/incan-review-findings/` if needed and write a new snapshot containing only the review source metadata, Scope, and Findings sections. Copy the finding blocks verbatim from `.agents/state/review-report.architecture.md`; do not generalize them into policy or rewrite them as fix summaries. Preserve exact file:line evidence when the report has it; if a finding is only file-level, make that explicit in the finding text. Do not overwrite an existing snapshot path; add a suffix if needed.
 
 ## Slice report shape
 
@@ -69,3 +84,26 @@ Do not write to the canonical `.agents/state/review-report.md`.
 ```
 
 If there are no findings, say so explicitly.
+
+## Findings snapshot shape
+
+Only write this file when findings are present.
+
+```md
+# Architecture Findings Snapshot
+
+- source: PR #<number> / <branch-or-context>
+- date: YYYY-MM-DD
+- reviewer: review-architecture
+
+## Scope
+- reviewed subsystems:
+  - ...
+
+## Findings
+- [ ] warning | design-tension | wrong layer | src/cli/commands/lifecycle.rs:210
+  Resolution policy duplicates env semantics that should stay in `src/project_lifecycle/**`.
+
+## Resolution
+- <optional, only if this snapshot is written after a fix loop>
+```