@dall337/lore 0.0.0-stage → 0.1.0

package/suite/policies/creative.md

@@ -0,0 +1,92 @@
+# Creative Mode Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load when the owner
+invokes creative mode or asks to explore an inventive direction, an unusual
+connection, or an unfinished idea. These are starting principles; this
+project's own lessons accumulate here with their provenance.
+
+Creative mode is a conversation in which the owner and agent give an idea
+room to find its shape. A stray thought, a feeling, or a strange analogy is
+enough to begin. Specificity can emerge over many exchanges; discovering
+an interesting direction is a useful outcome in itself.
+
+## Rule 1 — Keep the Possibility Alive
+
+Do not close an exploration with an outright "no," "that cannot work," or
+"that is impossible." When the first reading of an idea encounters
+difficulty, look for another interpretation, variation, scale, or framing
+that preserves what interests the owner. Explain the possibility that
+opens up and give them something to build on.
+
+Meet the seed with curiosity. Find the experience, quality, or connection
+it is reaching for before evaluating a particular realization. An idea
+that is vague, internally inconsistent, or impractical in its initial form
+still has room to develop through conversation.
+
+## Rule 2 — Follow the Possibility
+
+Use the app, script, story, or concept's existing shape as material for
+exploration: its purpose, vocabulary, interactions, and distinctive
+qualities. Familiar choices and apparent limits can suggest a new angle.
+
+Keep the initial response conversational. Offer an interpretation or a
+small sketch; ask a focused question when it would open an interesting
+branch. Let the owner's reaction reveal which part matters. Avoid turning
+the first exchange into a requirements interview, a hard-constraint
+checklist, or a scientific exposition.
+
+## Rule 3 — Look Across Disciplines
+
+Look for a useful connection in another discipline: a behavior, pattern,
+structure, sensation, or mechanism that could take a new form here.
+Movement, feedback, rhythm, coordination, adaptation, and storytelling
+are possible starting points; follow whichever connection has life in it.
+
+Translate enough of the connection to make it imaginable. Describe what
+could carry over and what it might become in this context. The borrowed
+idea can be literal, selective, metaphorical, or deliberately transformed.
+It does not have to reproduce its source discipline faithfully to be
+worth exploring.
+
+Share a few promising sketches at a time. Let the conversation deepen a
+connection, combine fragments, or abandon a branch as the owner responds.
+There is no novelty quota and no requirement to visit a set number of
+disciplines.
+
+## Rule 4 — Develop It Together
+
+Be an active participant: contribute images, examples, variations, and
+unexpected connections. Follow the owner's additions and remixes, including
+tangents that change what the original thought was about. A question
+should help the conversation move; avoid making the owner supply all the
+imagination or choose repeatedly from a fixed menu.
+
+Do not force convergence, a feature specification, or a deliverable.
+Continue exploring while the owner is engaged. Summarize the current
+thread occasionally so both participants can see what has emerged and
+which possibilities remain open.
+
+## Rule 5 — Give Speculation Room
+
+Use language such as "imagine if," "one version might," and "we could
+borrow" to keep imaginative suggestions recognizable as suggestions.
+Leave technical unknowns open while exploring them. Avoid presenting an
+invented fact as established or an untried mechanism as demonstrated.
+
+Move into factual research, feasibility analysis, or
+[adversarial checking](adversarial-check.md)
+when the owner asks for that kind of evaluation or chooses to develop a
+concrete proposal. Do not automatically subject each new thought to those
+procedures. Their own policies govern that work when it begins.
+
+## Rule 6 — Let the Owner Set the Next Step
+
+When the owner wants to make a direction specific, help express the idea
+that has emerged and propose a small sketch, mockup, prototype, or
+experiment that would teach something useful. Agree the scope before
+turning exploratory possibilities into implementation work.
+
+The conversation may also remain an exploration. When the owner wants to
+retain a direction, capture it in an appropriate brief or proposal under
+the [documentation policy](documentation.md). Preserve its open questions
+and distinguish possibilities from decisions.

package/suite/policies/documentation.md

@@ -0,0 +1,100 @@
+# Documentation Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load when creating
+or updating repo documents — ADRs, briefs, plans, RFCs, PRDs, notes.
+
+## Rule 1 — Document Kinds: Home, Scope, Naming
+
+Every repo document is one of these kinds. Pick the kind before writing;
+don't blend scopes.
+
+| Kind | Home + naming | Scope — what belongs in it |
+|---|---|---|
+| ADR | `docs/adrs/NNN-kebab-title.md` | **Normative decisions only** — what was decided and why, alternatives rejected, consequences. Detailed design does NOT belong here; the ADR cites the brief/plan as the canonical detailed design. |
+| Brief / design doc | `docs/plans/**/brief-<topic>.md` | The full design: investigation evidence, mechanisms, trade-offs, open questions. May precede its ADR. |
+| Build plan | `docs/plans/<area>/…-build-plan.md` | Delivery slices, each with Goal / Tasks / Tests / Acceptance. Owns sequencing, not decisions. |
+| RFC / PRD | `docs/rfcs/`, `docs/prds/` | Early-shape proposals and product requirements. When an ADR supersedes parts of one, add a dated supersession note to the old doc — never silently rewrite it. |
+| Tooling register | `docs/TOOLING.md` | The stack and its rationale (`policies/tooling.md` §2). |
+| Research journal | `.research/<date>-<task>.md` (gitignored) | Investigation state per `policies/research.md`. Never a home for repo-facing content. |
+| Memory | Entry point configured in AGENTS.md §5; bundled default is `memory/**` (gitignored) | Operational records per `policies/memory.md` §0; canonical repo-facing docs stay in their documented homes. |
+
+Adapt homes and naming to the project's layout on adoption — then keep
+this table true.
+
+> **Addendum (2026-10-02, configurable memory):** The memory row points
+> to the configured provider, including existing agent or company memory.
+> Its own content conventions apply; the bundled folder is optional.
+
+## Rule 2 — Amend, Never Rewrite
+
+Accepted documents grow by dated addenda and blockquote errata
+(`> **Erratum (date, context):** …`). ADR status is a **ledger**: every
+state with its date and one-line context, original `Proposed` kept at the
+bottom. History stays legible in the document itself.
+
+ADR skeleton (house format): `# ADR-NNN: Title` → `## Status` (ledger) →
+`## Date` → `## Context` → `## Decision` (numbered subsections) →
+`## Consequences` (positive / costs) → `## Alternatives Considered` →
+`## Scope Notes` → optional `## Implementation Follow-ups`.
+
+## Rule 3 — Pointers Over Restatement
+
+Never restate what another artifact owns. Enforcement code is the record
+of what it enforces — cite it, don't copy its lists. Architecture docs
+own architecture; code constants own values; the tooling register owns
+the stack. A copied list is a future contradiction.
+
+## Rule 4 — Provenance on Every Claim That Needs Trust
+
+Date status changes and addenda. Attribute decisions ("owner decision,
+date"). Name the PR that delivered a slice. When a document records an
+empirical finding, say how it was verified. (This is the accumulation
+convention of AGENTS.md §3 applied to all documents, not just policy.)
+
+## Rule 5 — Documents Live in the Working Tree
+
+Any document an agent creates for the repository must be present in the
+local working tree when the turn ends. If it was committed on a branch,
+leave that branch checked out (or otherwise ensure the file exists in the
+tree) — do not switch away and let the doc vanish from the owner's view.
+Do not park repo documents in scratch directories or out-of-tree
+locations; the only out-of-tree content is agent memory and research
+journals, which are governed by their own policies. When sharing a link
+to a doc on an unmerged branch, prefer the PR "Files" URL over a branch
+blob URL, and say explicitly the doc is pending merge.
+
+Docs ride with their code (`policies/git.md` §2.3): a doc describing
+unmerged behavior belongs on that branch, not the default branch.
+
+## Rule 6 — Lint Stance
+
+*(Adopt-time slot.)* The project declares whether markdown linting is a
+quality gate. Default shipped stance: follow standard markdown
+conventions; lint warnings are not a gate.
+
+## Rule 7 — Agent-Drafted Specifics Are Unverified Until Checked
+
+Proper nouns in an agent-drafted document are hypotheses, not facts:
+entity and product names, people, URLs, versions, license identifiers,
+citations, file paths, identifiers of every kind. They carry no authority
+from having been written down fluently, and none from having survived
+several readings — a specific that reads as settled is not the same as a
+specific that was ever true.
+
+This applies with full force to text inherited from an earlier session,
+an earlier draft, or an earlier agent. Provenance *inside* the document
+set is not verification; a fabricated name copied forward is still
+fabricated at every hop, and each hop makes it look more established.
+
+**Before a document becomes load-bearing** — a license, a register entry,
+a published README, a contract, anything an outside reader will act on —
+check every proper noun in it against something outside the document.
+Ask of each: what evidence, outside this file, says this exists?
+
+**Trap signature: the specific nobody remembers deciding.** When no one
+can point to the moment a name was chosen, it was probably never chosen.
+Ownership, attribution, and legal identity are the highest-severity
+instance of this class — a fabricated holder in a license is an
+unenforceable grant made in the name of a party that does not exist —
+and they are also the least likely to be questioned, because those fields
+are skimmed as boilerplate rather than read as claims.

package/suite/policies/git.md

@@ -0,0 +1,105 @@
+# Git Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load when branching,
+committing, pushing, or opening PRs.
+
+## 1. Branch Lifecycle
+
+Each coherent unit of work gets its own new branch, opened from the
+default branch.
+
+**A coherent unit of work is any one of:** a feature; a refactor or
+migration; a chore (cleanup, test infrastructure, dependency updates, CI
+fixes); a bug fix touching multiple files or areas; a documentation pass
+beyond a single targeted edit.
+
+1. **One unit, one branch.** Do not pile unrelated work onto an existing
+   branch — even if it's still open, even if it isn't merged, even if the
+   same area was touched recently. New work means a new branch.
+
+2. **Branch from the default branch, not from another feature branch.**
+   Branching off a feature branch inherits its unmerged commits, which
+   corrupts the new branch's diff and creates merge-ordering hazards.
+
+3. **Default interpretation rule.** When the owner says "branch, stage,
+   commit, push" — or any equivalent for taking new work to the remote —
+   the default is **always create a new branch off the default branch
+   first**. Reusing an existing branch must be stated explicitly. If the
+   current branch is anything other than the default and the owner has
+   not explicitly said "use the current branch," **stop and ask** before
+   staging.
+
+4. **Merged-branch stance** *(adopt-time slot — the owner picks one and
+   the choice is recorded here)*:
+   - **Delete on merge** — reuse becomes physically impossible; the
+     simplest guardrail.
+   - **Retain after merge** — a merged branch stays addressable by name,
+     but the guardrail deletion provided now has to stand as a rule: **a
+     merged branch is CLOSED for new work.** The branch may still be
+     checked out; nothing but this rule stops the next commit landing on
+     it — and that commit becomes the orphan described below. Under
+     retention, before staging anything, confirm the current branch has
+     not already shipped (e.g.
+     `gh pr list --state merged --head "$(git branch --show-current)"`).
+     Any output means stop and branch off a freshly pulled default.
+
+5. **Allowed reuse:** in-review PR feedback goes on the PR's branch;
+   coherent multi-commit units per the bucketing rules; hotfixes to a
+   release branch where the project has them.
+
+**Why this rule exists:** without it, unrelated changesets accumulate on
+one branch. When that branch's PR merges from a snapshot, commits pushed
+after the snapshot become orphans that never reach the default branch —
+silently breaking it when merged code references things that exist only
+on the still-active feature branch. One unit per branch makes the class
+structurally impossible.
+
+## 2. Branch + PR vs Direct Push
+
+1. **Branch + PR is required for risky changes:** runtime behavior or UX
+   changes; anything under the source directories; build or app config
+   that can affect shipped behavior; refactors, dependency updates,
+   anything with regression risk; and enforcement code itself (guard and
+   check scripts) — it is the floor everything else stands on.
+2. **Direct push may be allowed for low-risk changes** — docs, plans, and
+   notes only; non-behavioral metadata; the finalized release version
+   bump — if the project permits it. When uncertain, branch + PR.
+3. **Docs ride with their code.** A doc describing unmerged behavior
+   belongs on that behavior's branch, not on the default branch.
+
+## 3. Commit Bucketing
+
+Group by intent: code changes separate from docs; docs and plans in their
+own commit; release bumps in their own commit, last (see
+`policies/release.md`).
+
+## 4. Pre-Push Checklist
+
+- Confirm branch context (`git branch --show-current`).
+- Verify the branch is appropriate for this work — new unit means new
+  branch (§1); under retention, verify it hasn't already shipped.
+- Review staged files (`git status --short`).
+- Ensure commit scope matches the file set — and after committing, read
+  the files-changed count in the commit output
+  (`policies/verification.md` Rule 3).
+- Run the relevant checks for code changes (`policies/verification.md`).
+
+## 5. Commit Identity
+
+The repository has exactly one valid author/committer identity, pinned
+per-clone in local git config — never recorded in these files, never
+guessed, never copied from a session banner.
+
+- **Verify before pushing, every clone, every time:**
+  `git log -1 --format="%an <%ae>"`. Session banners, environment
+  variables, and the platform's "current user" are not evidence of what
+  git will stamp.
+- **Never author with a personal email address.** Use the forge's noreply
+  address so private contact details never enter commit metadata, message
+  trailers, or file contents — check all three surfaces.
+- **A misconfigured identity is not cosmetic.** A wrong author can
+  attribute the codebase to an unrelated third party. Identity drift on a
+  fresh clone is a blocking defect: fix config before the first commit.
+- Wrong identity on work already committed: stop and surface it to the
+  owner rather than pushing — the fix is a history rewrite, which is the
+  owner's call.

package/suite/policies/implementation.md

@@ -0,0 +1,100 @@
+# Implementation Policy
+
+Scoped agent-governance procedure (AGENTS.md §1/§2). Load when writing or
+changing code in any language. These are starting principles distilled
+from real debugging sessions on the ancestor repository, provenance
+stripped (AGENTS.md §3); they apply to any codebase with concurrency,
+cross-platform targets, external side effects, or stateful UI. Your
+project's own rules accumulate here, dated, with their incidents.
+
+## Rule 1 — Effects Idempotent Under Re-Fire
+
+Development modes of modern frameworks deliberately double-fire effects
+and lifecycle hooks. Any effect that creates a backend resource — process
+spawn, session start, socket open, database connection — must be
+idempotent: guard with a started-flag, deduplicate the underlying promise
+so a second call reuses the first, and return a cleanup that tears the
+resource down. Assume every effect runs twice and design accordingly.
+Corollary: state-updater functions must be pure — never perform side
+effects inside one; dev modes double-fire those too.
+
+## Rule 2 — Platform-Specific Code Isolation
+
+Platform-dependent code lives behind real compile-time or runtime gates,
+never inline in shared business logic. Use gates that actually exclude
+the other platform's code from compilation where the language offers them
+(a runtime `if` on the platform still compiles — and can still break —
+every branch). Centralize platform checks in one module; ad-hoc platform
+conditionals scattered through shared logic are the defect pattern.
+
+## Rule 3 — Dev-Only Safety Nets Are Gated
+
+Dev-mode workarounds — orphan-process cleanup, verbose logging, mock
+fallbacks — must be gated so they cannot ship in production builds, and
+must carry a comment saying why they exist so no future reader mistakes a
+safety net for a feature.
+
+## Rule 4 — Preserve Expensive Stateful Instances
+
+Components with expensive internal state (terminal emulators, code
+editors, video players, map views, 3D canvases) should be hidden and
+shown by visibility toggling, not destroyed and recreated by conditional
+rendering. Teardown-and-rebuild loses internal state and pays
+initialization cost on every toggle. Know your framework's teardown
+semantics and choose the mechanism that preserves the instance.
+
+## Rule 5 — Dead Code Carries Its Reason
+
+Zero-warning builds are the floor, but "unused" is a claim to verify, not
+obey: a constant may be read textually by a script; an item may be
+ratified-decision prep awaiting its consumer. Suppress warnings per-site
+only, with a comment naming the future consumer; never blanket
+suppressions. Remove the suppression when the consumer lands. Genuinely
+dead code is deleted — version history remembers it.
+
+## Rule 6 — Visual Changes Get Visual Verification
+
+Any change whose acceptance criterion is "how it looks" — styling, canvas
+drawing, layout, state/hover treatments — is verified by *looking at the
+rendered output* before the PR, not shipped on geometry math. Build a
+minimal repro of the real structure and styles, render it headlessly,
+and read the screenshot: magnified to catch hairline features, and at 1×
+because that is what the user sees. Faint and stateful styling especially:
+screenshot the state, don't reason about it.
+
+## Rule 7 — State Follows the Authoritative Side Effect
+
+In any flow pairing an in-memory state mutation with a refusable external
+operation (disk write, network call, database commit): run every check
+that can refuse the operation *before* the state write — or run the
+operation first and derive state from its result. Never commit state on
+the assumption the operation will succeed; a refusal then leaves state
+pointing at things that never materialized, and reconciliation has to
+guess. The operation's result object is the authority; a discarded
+success flag is a silent divergence waiting for its trigger. When
+auditing, look for state mutations issued above the external call — that
+ordering is the trap's signature.
+
+## Rule 8 — Removal Refactors: Grep the Identifier Dead
+
+After removing any identifier — parameter, export, prop, handler — grep
+it repo-wide before calling the removal done: imports *and* bare uses. A
+parameter list and the object literal that forwards it are separate
+sites; assembler and binding layers that repackage values are the classic
+repeat offenders. Bundlers can build free identifiers without complaint
+and unit tests may never execute the render path, so every check can pass
+while the app crashes live. If the lint chain has an undefined-reference
+rule, keep it; until it does, the grep is mandatory.
+
+## Rule 9 — Persistent State Is Born Sync-Ready
+
+- New persistent entity types get a globally-unique identifier at birth —
+  a UUID, never an autoincrement, rowid, timestamp, or process-local
+  counter. Machine-local uniqueness collides the day replicas merge
+  (multi-user sync, imports, cross-machine copies); retrofitting identity
+  is a migration, preventing new instances is free.
+- New persistent tables and columns declare, at creation, which side of a
+  future sync line they live on — shared project truth vs
+  per-user/per-machine. A one-line comment at the schema site suffices;
+  the point is that the classification is decided at birth, not by
+  archaeology later.