@cratis/pi 7.37.0 → 7.38.1

package/package/corpus/harnesses/copilot/instructions/go.instructions.md

@@ -0,0 +1,116 @@
+---
+applyTo: "**/*.go,go.mod,go.sum,**/go.mod,**/go.sum"
+paths:
+  - "**/*.go"
+  - "go.mod"
+  - "go.sum"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Go conventions
+
+Use Go's own packages, constructors, explicit registration and standard `testing`.
+Do not import C# namespace layouts, one-type-per-file rules, `I` interface prefixes,
+`Async` suffixes or .NET specification mechanics. Product APIs belong in the
+matching Go skill; repository-owned context supplies module paths, layout and
+exact commands.
+
+## Minimum version and dependencies
+
+- Read the `go` directive, build constraints and CI before choosing a feature.
+  The minimum is not the newest locally installed compiler; a `toolchain`
+  preference does not replace minimum-version testing. Do not raise it incidentally.
+- Iterators require Go 1.23; `T.Context` and `B.Loop` require 1.24;
+  stable `testing/synctest` and `WaitGroup.Go` require 1.25.
+- Prefer the standard library when it meets the contract. Review dependency
+  capability, license and compatibility before adding one.
+- Change module files only for authorized dependency work. Review tidy changes,
+  including indirect minimum-version changes; keep sums consistent. A consumer
+  must not need a developer's workspace or local replacement.
+- Never edit generated code; change its authoritative inputs and pinned generator.
+
+## Names, public APIs and values
+
+- Format handwritten Go with `gofmt`; use its tabs and the repository's import grouping.
+- Use MixedCaps and preserve `ID`, `HTTP`, `URL`, `JSON` and `RPC` initialisms.
+  Avoid package stuttering and catch-all packages. Use American English.
+- Keep public surfaces small and caller-oriented. Define interfaces at consuming
+  boundaries or where public substitution is a supported contract, not for every type.
+- Document exported declarations with comments beginning with their names.
+  Explain nil/zero semantics, concurrency, ownership, cancellation, error identities
+  and cleanup. Add executable examples for important public workflows.
+- Make zero values useful where possible; reject invalid construction early.
+  Document option defaults, validation, ordering and duplicates.
+- Use named domain values instead of interchangeable primitives. Defined types
+  do not inherit codec methods; explicitly forward text/JSON codecs and test wire
+  formats. See `cratis-fundamentals-concept-go` when using Fundamentals.Go.
+- Document whether slices, maps, config and results are owned, copied or borrowed.
+  Copying a slice/map header is not a detached copy. Do not copy a used mutex,
+  wait group or atomic value, or expose pooled bytes after returning their buffer.
+
+## Errors, context and diagnostics
+
+- Return ordinary failures as the final `error`; inspect errors, including cleanup.
+  Libraries must not exit the process or panic for expected failures.
+- Preserve documented error identity with `errors.Is`/`errors.As`, not strings.
+  Wrapping with `%w` exposes that identity as API; do it deliberately. Do not
+  return an `error` interface containing a typed nil.
+- Add useful operation context. Handle/log an error at one boundary rather than
+  repeatedly logging and returning it. A partial or ambiguous write is not success
+  and must not trigger a blind retry.
+- Put `context.Context` first for blocking/cancelable work and propagate it through
+  RPCs, HTTP, storage and callbacks. Never escape caller cancellation by replacing
+  it with `Background`. Do not retain request contexts in long-lived clients.
+- Call acquired cancel functions. Context values carry request metadata, not
+  dependencies or configuration; use private keys with typed accessors.
+- Prefer injectable `log/slog` at a supported minimum. Do not mutate global logging
+  from a library. Redact credentials and sensitive payloads.
+
+## Goroutines, streams and iterators
+
+- Each goroutine needs an owner, termination condition and observable join path.
+  Cancellation requests termination; it does not join workers.
+- Bound workers, queues, subscriptions, buffers and retries; define backpressure.
+  Make blocking operations cancellation-aware. Close channels only after senders stop.
+- Do not hold locks while calling user code or performing slow I/O. Call
+  `WaitGroup.Add` before launching work when not using version-supported `Go`.
+- Stop immediately when iterator `yield` returns false. Release resources on
+  exhaustion, early exit, failure and cancellation; call `iter.Pull`'s stop function.
+  Specify ordering, errors and whether a stream can be consumed more than once.
+- Preserve protocol metadata, tenancy, checkpoints and duplicate-delivery semantics.
+  No generic retry or stream helper may promise exactly-once effects.
+- Validate remote TLS identities. Development exceptions must be explicit.
+  Use cryptographic randomness for secrets, never `math/rand`.
+
+## Specifications and checks
+
+- Use standard `testing`, meaningful subtests, useful got/want diagnostics and
+  table-driven cases where setup/assertions actually match. Use external `_test`
+  packages to exercise public contracts where practical.
+- Use `t.Helper`, `t.Cleanup` and `t.TempDir`. Isolate state before `t.Parallel`.
+  Synchronize with channels/joins, not guessed sleeps. Fake-time tests do not
+  establish real-network behavior.
+- Cover error identity, nil/zero input, cancellation/deadlines, partial outcomes,
+  early stream exit and resource ownership. Bound fuzz duration and preserve
+  failing seeds. Use race checks where supported; race-free does not mean leak-free.
+- Run the repository's build, tests, formatting, vet and pinned golangci-lint gates,
+  with race and vulnerability scanning as separate checks. Respect the declared
+  minimum without silent toolchain upgrades. Report absent tools honestly.
+
+## Adaptation and attribution
+
+This condensed rule adapts the repository-owned Go baseline at
+[Chronicle.Go v0.9.1](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/.cratis/ai/rules/go.md)
+and [Arc.Go v0.1.1](https://github.com/Cratis/Arc.Go/blob/v0.1.1/.cratis/ai/rules/go.md),
+not their project paths or commands. The baseline's adapted readability,
+error-boundary, public-option and goroutine recommendations retain attribution:
+[Google Go style](https://google.github.io/styleguide/go/guide.html), Google,
+[CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/); and
+[Uber Go style](https://github.com/uber-go/guide/blob/master/style.md), Uber
+Technologies, Inc., [Apache-2.0](https://github.com/uber-go/guide/blob/master/LICENSE).
+No community code snippets are reproduced here.

package/package/corpus/harnesses/copilot/instructions/guards-and-fuses.instructions.md

@@ -0,0 +1,61 @@
+---
+applyTo: "**/*"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Guards, scans and fuses
+
+A guard that cannot fail is worse than no guard: it converts "nobody looked" into a green
+check. Every line is tagged **[contract]** (binding) or **[convention]** (the house
+default) per the Three Levels of Authority in [`general.md`](../../../rules/general.md).
+
+**Scope.** This rule governs two situations: *authoring* a scanner, guard, allowlist or
+checker, and *running a pass* that mutates a computed set of subjects rather than the
+targets the request named. An ordinary edit, review, fix, or a change to the one file the
+user pointed at is outside it and carries none of the machinery below.
+
+## Non-vacuity
+
+- **[contract] A scan over a possibly-empty population carries a non-vacuity check.**
+  Assert the subject count is what you expect before believing the result, and fail when
+  the population is unexpectedly empty.
+- **[contract] Report the count on success.** "Checked 0 files, found 0 problems" and
+  "checked 412 files, found 0 problems" are different verdicts and must read differently.
+- **[contract] A pattern that matches nothing is a defect in the pattern** until proven
+  otherwise. Prove a matcher still matches by planting a violation; see
+  [`exit-codes-and-wrappers.md`](./exit-codes-and-wrappers.instructions.md).
+
+## Allowlists
+
+- **[contract] Every allowlist entry records its reason** — why this subject is exempt,
+  and what would end the exemption.
+- **[contract] Every allowlist entry has a sibling check** that fails when the entry
+  becomes unnecessary, so the list shrinks instead of accumulating forever.
+- **[convention] Prefer an expiry to a permanent exemption.** An entry nobody revisits is
+  a rule quietly deleted.
+
+## Bulk and irreversible passes
+
+These contracts are keyed to the *risk class* of the effect — bulk deletion, history
+rewriting, cross-repository migration, anything irreversible or high-fanout — not to
+whether a person is watching. An autonomous session runs them exactly as an interactive
+one does.
+
+- **[contract] Distinguish "subject set empty" from "qualifying set empty".** Finding no
+  candidates at all is a different situation from finding candidates that none qualified;
+  a pass must refuse to proceed on the first.
+- **[contract] Every pass carries a per-pass fuse** — a maximum number of subjects it may
+  act on in one run, which stops the run rather than trimming the work silently.
+- **[contract] Know the recovery before the forward action.** For a reversible effect,
+  know how it is undone. For an irreversible one, preserve what the recovery needs first —
+  a backup ref, a copy under `.ai-work/keep/`, the list of targets — and stop if nothing
+  can be preserved and the request did not name the targets. Do not demand an exact
+  inverse where none can exist.
+- **[contract] Re-read preconditions immediately before each mutation and stop when drift
+  invalidates the authorized scope, safety assumptions, or recovery plan.** Benign drift
+  within an already authorized bounded pass does not require another confirmation.
+- **[convention] When the targets were not already established in the conversation, show
+  the dry-run list and act on it once the user has answered.** A user who has reviewed
+  and authorized those targets is not asked to approve the same pass again. The list is a
+  message in the conversation, not a retained artifact: do not write receipts, ledgers,
+  snapshots or escrow copies of it.

package/package/corpus/harnesses/copilot/instructions/java.instructions.md

@@ -0,0 +1,138 @@
+---
+applyTo: "**/*.java"
+paths:
+  - "**/*.java"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Java Conventions
+
+Java is a supported, first-class Cratis application language alongside Kotlin
+— an Arc.Kotlin-based application can be entirely Java source, with Kotlin and
+KSP present only in the build (Arc generates Kotlin adapters for Java
+declarations under the hood). Write idiomatic modern Java; do not import
+Kotlin idioms into Java source, and do not treat Java as a second-class
+citizen of a Kotlin codebase. Arc/Chronicle-specific shapes (`@Command`,
+`@ReadModel`, `@EventType`, and the rest) live in the matching skill, not
+here.
+
+## Building
+
+- Use `./gradlew build` (or the repository's Maven equivalent) from the
+  command line; it is the definition of "the build is clean" — zero warnings,
+  zero errors.
+- Treat compiler warnings as errors (`-Xlint:all -Werror`); do not suppress a
+  warning to get to green.
+
+## Formatting
+
+- Four-space indentation, no tabs.
+- One public top-level type per file, named after that type.
+- Sort imports alphabetically; no wildcard imports.
+- Braces on the same line as the declaration (`if (...) {`), closing brace on
+  its own line.
+
+## Language — American English Only
+
+All identifiers, Javadoc, and string literals use **American English**
+spelling (initialize, serialize, behavior, color, organization, center,
+modeling, dialog, license, judgment, gray). See [general.md](../../../rules/general.md).
+
+## Naming
+
+- PascalCase for class and interface names.
+- camelCase for methods, fields, and local variables.
+- New application and Arc-style interfaces have no `I` prefix — name them
+  for what they do. Chronicle.Kotlin's published interfaces retain their names
+  (`IEventStore`, `IChronicleClient`, `IProjectionFor`, `IReactorMiddleware`).
+- Never suffix a class with `Impl`, `Manager`, or `Helper` purely to
+  disambiguate — name it for its role; reserve `Default<Name>` for the
+  concrete counterpart of an interface meant to be overridden.
+
+## Records and Immutable Data
+
+- Prefer a `record` for an immutable value holder (DTOs, command payloads,
+  query results, read models) over a hand-written class with a constructor,
+  getters, `equals`, `hashCode`, and `toString` — the record gives all of that
+  for free and keeps the file short.
+- Give a record component a validating compact constructor when the type must
+  never hold an invalid value, rather than validating at every call site that
+  constructs one.
+- Favor `sealed` interfaces with a closed set of `permits` implementations
+  over a discriminator field, when a value can genuinely only be one of a
+  known set of shapes — pattern matching over the sealed hierarchy replaces
+  the `instanceof` chain.
+
+## Nullability
+
+- Prefer `Optional<T>` for a method's **return type** when absence is a normal
+  outcome the caller must handle; never use `Optional` as a field type, a
+  constructor parameter, or a method parameter — that is not what it is for.
+- Prefer a non-null default and an explicit `Objects.requireNonNull(...)` at a
+  constructor boundary over accepting `null` and checking for it throughout a
+  class.
+- On a surface consumed from Kotlin (an Arc/Chronicle read model, event, or
+  command reached from Kotlin code), be deliberate about which fields are
+  genuinely optional — a Java field with no null-safety annotation reads as
+  non-null to Kotlin-facing generated code by default.
+
+## Classes
+
+- Favor composition over inheritance; an `interface` plus one or more
+  implementing classes is the house shape for an overridable collaborator, not
+  a base class meant to be extended.
+- Make a class `final` unless it is deliberately designed for extension.
+- Prefer constructor injection over field injection for a Spring-managed
+  bean — a `final` field set in the constructor over an `@Autowired` field.
+
+## Asynchronous Code
+
+- `CompletionStage<T>` (or its `CompletableFuture` implementation) is the
+  house shape for an asynchronous Java API, mirroring how Kotlin exposes
+  `suspend` — Arc's generated adapters await a returned `CompletionStage`
+  without reflection.
+- Never block on a `CompletionStage` inside a method that itself returns
+  one — compose with `.thenApply`/`.thenCompose` or `.thenAccept` instead of
+  calling `.get()`/`.join()` inside the async chain.
+- Give a Java caller its own explicit scope (an `ExecutorService`, or the
+  scope type the host library provides) rather than reaching for a shared
+  global one.
+
+## Javadoc
+
+- Every public type and method meant for consumption outside its package gets
+  a Javadoc comment (`/** ... */`) — what it does and why, not a restatement
+  of its name.
+- Use `@param`, `@return`, and `@throws` for parameters, return values, and
+  checked exceptions.
+
+## Exceptions
+
+- Use exceptions for genuinely exceptional, unrecoverable conditions — not for
+  control flow a caller is expected to handle. A command or query rejection a
+  user can act on is a validation result, not a thrown exception; see the Arc
+  validation skills.
+- Prefer an unchecked exception with a clear name over a checked exception
+  that forces every caller to catch or declare it; reserve checked exceptions
+  for conditions a caller genuinely has a recovery path for.
+
+## Dependency Injection
+
+- Constructor injection is the default for a Spring-managed bean; avoid field
+  injection (`@Autowired` on a field) even though Spring supports it.
+
+## Logging
+
+- Log through the host's structured logging facility (SLF4J via Spring Boot),
+  not `System.out`/`System.err`.
+- Log at the boundary where a decision is made or an error is handled, not at
+  every intermediate call.
+
+## Testing
+
+- JUnit Jupiter is the house test runner (the Cratis JVM repositories use
+  Jupiter 6.1.x).
+- A test for a Java-facing surface belongs beside the Java production code
+  (`src/test/java/.../<Thing>Test.java`) and must actually compile and run
+  against that surface — a Kotlin-only test does not prove Java call-site
+  compatibility for a mixed-language library.

package/package/corpus/harnesses/copilot/instructions/kotlin.instructions.md

@@ -0,0 +1,175 @@
+---
+applyTo: "**/*.kt,**/*.kts"
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Kotlin Conventions
+
+Kotlin is a JVM-first, coroutine-first language. Use its own idioms — data
+classes, `null`-aware types, coroutines, sealed hierarchies — instead of
+carrying Java or C# patterns across unchanged. A Cratis Arc or Chronicle
+application on Kotlin follows Spring Boot conventions for wiring and this
+file's conventions for everything else; Arc/Chronicle-specific shapes
+(`@Command`, `@ReadModel`, `@EventType`, and the rest) live in the matching
+skill, not here.
+
+## Building
+
+- Use `./gradlew build` from the command line; it is the definition of "the
+  build is clean" — zero warnings, zero errors.
+- Use `./gradlew test` to run tests.
+- Treat compiler warnings as errors. `allWarningsAsErrors` is the house
+  default for Kotlin compilation; do not add a suppression to get to green.
+
+## Formatting
+
+- Four-space indentation, no tabs.
+- One top-level public declaration per file, named after that declaration.
+- Sort imports alphabetically; no wildcard imports.
+- Trailing commas in multi-line parameter lists and call sites — they keep
+  diffs to one line when a member is added or removed.
+- Insert a blank line before the opening `{` of a multi-line `if`/`when`/`for`
+  block; keep single-expression bodies on one line.
+
+## Language — American English Only
+
+All identifiers, KDoc, and string literals use **American English** spelling
+(initialize, serialize, behavior, color, organization, center, modeling,
+dialog, license, judgment, gray). See [general.md](../../../rules/general.md).
+
+## Naming
+
+- PascalCase for class, interface, and object names.
+- camelCase for functions, properties, and local variables.
+- New application and Arc-style interfaces have no `I` prefix; name them for
+  what they do (`CommandPipeline`, not `ICommandPipeline`). Reserve
+  `Default<Name>` for a concrete/interface pair when needed. Chronicle.Kotlin's
+  published types retain their names (`IEventStore`, `IChronicleClient`,
+  `IProjectionFor`, `IReactorMiddleware`); do not rename framework APIs.
+- Never suffix a class with `Impl`, `Service`, or `Async` purely to
+  disambiguate — name it for its role.
+
+## Visibility
+
+- Kotlin's implicit-public default is what most declarations should use;
+  spelling `public` is a style choice, not a requirement — decide once per
+  file or module and stay consistent within it.
+- Mark a declaration `internal` when it must not cross a module boundary, and
+  `private` for anything a class does not need to expose. Do not default
+  everything to `public` "to be safe" — a wider surface than necessary is a
+  bigger contract to keep stable.
+- Compile-time discovery (KSP, reflection-based scanning) generally requires
+  **public** top-level types and members. A declaration silently excluded from
+  discovery because it is `internal` or `private` is a visibility bug, not a
+  framework limitation — check the matching skill's discovery rules before
+  assuming a narrower visibility is safe.
+
+## Nullability
+
+Kotlin's type system is the first line of defense against null-related bugs —
+trust it the same way C# nullable reference types are trusted.
+
+- Prefer a non-nullable type and a real default over a nullable one with a
+  defensive check.
+- Use `?.`, `?:`, and `requireNotNull()`/`checkNotNull()` instead of manual
+  `if (x != null)` guards.
+- A nullable outer collection (`List<T>?`) is supported; a nullable *element*
+  inside a collection (`List<T?>`) is a narrower, often-unsupported shape in
+  generated/serialized contracts — do not reach for it without checking
+  whether the surface you are writing actually allows it.
+- Data classes model state, not behavior — keep validation and invariants in
+  the type that owns them (a concept, a validator), not scattered across every
+  call site that happens to touch a nullable field.
+
+## Classes and Data
+
+- Prefer `data class` for immutable value holders (DTOs, events, command
+  payloads, read models) — value equality, `copy()`, and `componentN()`
+  destructuring come for free.
+- Prefer a primary constructor with `val` properties over a body full of
+  assignment statements.
+- Reach for a `sealed class`/`sealed interface` hierarchy instead of an enum
+  with a payload bolted on, whenever the variants carry different data.
+- Favor composition over inheritance; an `interface` plus a `Default*`
+  implementation is the house shape for an overridable collaborator, not a
+  base class meant to be extended.
+
+## Coroutines
+
+- An asynchronous API is `suspend`, not a returned `Future`/`CompletableFuture`
+  — Kotlin callers compose `suspend` functions directly, and a JVM-facing
+  bridge (`CompletionStage`) is layered on top for Java callers, never the
+  other way around.
+- Per-call state travels in a `CoroutineContext` element; never a
+  `ThreadLocal`. A coroutine can move between threads, and thread-local state
+  silently goes stale when it does.
+- Never launch on `GlobalScope`. Use the scope the host (Spring Boot's bounded
+  application coroutine scope, a test's `runBlocking`/`runTest`) already
+  provides.
+- Cleanup that must run even after cancellation goes in
+  `withContext(NonCancellable) { ... }`; everything else should stay
+  cancellable rather than swallow the cancellation.
+- Bridge a genuinely thread-bound third-party API with a
+  `ThreadContextElement`; do not leak a raw `ThreadLocal` into coroutine-facing
+  state as a shortcut.
+
+## Java Interop
+
+Kotlin/Java interop is a first-class concern whenever a library or an
+application may be consumed from Java — which every Arc/Chronicle application
+should assume by default:
+
+- Add `@JvmStatic` to companion-object factories a Java caller needs to call
+  without `Companion.`.
+- Add `@JvmOverloads` to a function with default parameter values so Java
+  gets the shorter overloads too.
+- Give a function returning a value class or an inline class a `@JvmName`
+  when Java needs to call it — the mangled synthetic name is not meant to be
+  called directly.
+- Prefer a `List<T>`/`Map<K, V>` parameter type over a Kotlin-only collection
+  interface on any Java-facing surface.
+
+## KDoc
+
+- Every public type, function, and property meant for consumption outside its
+  module gets a KDoc comment (`/** ... */`) — what it does and why, not a
+  restatement of its name.
+- Keep the summary to one or two sentences; use `@param`, `@return`, and
+  `@throws` for the rest.
+
+## Exceptions
+
+- Use exceptions for genuinely exceptional, unrecoverable conditions — not for
+  control flow a caller is expected to handle. A command or query rejection a
+  user can act on is a validation result, not a thrown exception; see the
+  Arc validation skills.
+- Define a custom exception type when a caller needs to distinguish it from
+  other failures; do not throw a bare `RuntimeException`/`IllegalStateException`
+  for something callers are expected to catch specifically.
+
+## Dependency Injection
+
+- Constructor injection through the primary constructor is the default; avoid
+  field/property injection.
+- Give a collaborator an interface and a `Default*` implementation when an
+  application might reasonably override it, bound with Spring's
+  `@ConditionalOnMissingBean` so a consumer can replace it without forking.
+
+## Logging
+
+- Log through the host's structured logging facility (SLF4J via Spring Boot),
+  not `println`.
+- Log at the boundary where a decision is made or an error is handled, not at
+  every intermediate call.
+
+## Testing
+
+- JUnit Jupiter is the house test runner for Kotlin and Java alike (the
+  Cratis JVM repositories use Jupiter 6.1.x).
+- A Kotlin test lives beside its Kotlin production code
+  (`src/test/kotlin/.../<Thing>Test.kt`); a Java-facing surface also gets a
+  Java test that compiles and runs against it, because Kotlin-only tests do
+  not prove Java call-site compatibility.

package/package/corpus/harnesses/copilot/instructions/local-work-artifacts.instructions.md

@@ -0,0 +1,56 @@
+---
+applyTo: "**/*"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Local AI work artifacts belong in `.ai-work/` only
+
+AI-assisted sessions produce working artifacts: plans, handover documents, session
+notes, continuation prompts, status boards, TODO and scratch analyses, research
+dumps, and similar coordination files. These are **work records, not documentation**.
+
+- Create every such artifact inside **`.ai-work/`** at the repository root — never at
+  the repository root itself, never under documentation folders, never anywhere else.
+- `.ai-work/` is listed in `.gitignore` and must stay untracked. Never commit anything
+  inside it, never `git add -f` anything inside it, and never remove the ignore entry.
+- These artifacts must never enter git history or reach GitHub — not on any branch.
+  If you find one tracked in git, move it into `.ai-work/` and remove it from
+  tracking in a dedicated commit.
+- A genuine follow-up that must survive the session is **not** a work record — suggest
+  opening a GitHub issue for it (or open one when asked) so future work is tracked
+  where everyone can see it, instead of leaving a planning file behind.
+- Knowledge that must outlive the session (real documentation, ADRs, operator
+  guides) is written deliberately into the repository's documentation structure
+  through normal review — not left behind as a work record.
+- **A session prompt or handover states when it is valid.** A fresh-session prompt,
+  continuation prompt or handover in `.ai-work/` opens with its preconditions: the
+  repository, the branch, the expected `HEAD` commit, every worktree path it names,
+  and the date it was written. Without them nothing tells a later session whether
+  the prompt still describes reality.
+- **Check the preconditions before acting on a prompt.** A session that starts from
+  one compares them with `git rev-parse --show-toplevel`, `git rev-parse HEAD`,
+  `git branch --show-current` and `git worktree list` first. A mismatch (a moved
+  `HEAD`, a missing worktree, another branch) means **the prompt is stale — not
+  that the work is lost.** Do not recreate
+  a worktree, reset, or discard anything because of it; look at the branches, the
+  reflog and the open pull requests for where the work is now, then update or
+  replace the prompt.
+- **A worktree is a work record too.** Create it outside the repository tree, for
+  example in a sibling `../.worktrees/` directory. A nested worktree inherits the
+  parent's `.globalconfig` alongside its own, causing .NET's `MultipleGlobalAnalyzerKeys`
+  errors or silently changing analyzer severities. Remove the worktree you created for
+  a task once its branch is merged to the default branch — pushed is not merged. Do it
+  from the parent checkout, after `git status --ignored` in the worktree, because a
+  nested `.ai-work/`, `.env` files and local databases are ignored and are deleted with it.
+  If the branch must outlive the task unmerged, leave the worktree and say so in the
+  handoff. Never `--force` a removal; a refusal means look, not push harder.
+- **A decision log is not a work record.** A decision — a durable choice with a
+  decider and a date — is documentation: it lives in **`decisions/`** (or the
+  repository's documented decisions folder) and is reviewed like any other
+  documentation. A handover may summarize decisions; it never holds the only
+  copy. If a session produced a real decision, land the record in `decisions/`
+  before the session's `.ai-work/` files are discarded.
+- The record's shape (front matter, status and stage values, supersession
+  pointers) is defined by the decision-record skill and the shared vocabulary
+  once this repository carries them; until then use the repository's existing
+  decisions folder and keep decider and date explicit.

package/package/corpus/harnesses/copilot/instructions/new-repository-intake.instructions.md

@@ -0,0 +1,35 @@
+---
+applyTo: "**/*"
+profile: framework
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# New Repository Strategy Intake
+
+This is Cratis organization process for maintainers creating repositories under the
+Cratis organization. It does not apply to applications built on Cratis.
+
+When a repository is created in the Cratis organization, prepare one transient,
+no-effect Strategy intake proposal. Do not create, comment on, assign, mention,
+link, or otherwise mutate a GitHub issue unless a current repository profile and
+the exact operation are separately accepted. Tool access and a request to create
+the repository do not supply that issue-effect authority.
+
+The proposal should include only the bounded facts needed for Strategy triage:
+
+- repository name, URL, visibility, and creation state;
+- purpose, intended users, lifecycle, and whether it is canonical, generated,
+  experimental, operational, or scheduled for retirement;
+- accountable owner or explicit vacancy and cross-repository boundaries;
+- upstream/downstream dependencies and current owning records;
+- release, distribution, credential, security, privacy, compliance, and data
+  expectations; and
+- requested Strategy identity, portfolio, metadata, ownership, and local AI
+  context review.
+
+First decide whether no record, an existing Strategy record, a bounded update
+proposal, a new proposal, or a sensitive human route is appropriate. Treat the
+result as Strategy intake, not strategic approval. Do not invent Strategy
+metadata or copy private Strategy content into a public repository. Repository
+creation does not require an issue URL; unresolved Strategy reconciliation is an
+explicit next action for the authorized human/owning process.