accrete-kit 0.0.0-stage → 0.1.0

package/dist/scaffold/assets/skills/accrete-models/references/objects.md

@@ -0,0 +1,67 @@
+# Model meaning and relationships
+
+## Identity and placement
+
+A Model names a computational program that the project develops or uses. Its stable ID survives a rename, a moved checkout, another machine's path, and a new Git revision. A repository is the carrier of source history; a checkout exposes one working form of that history. Several checkouts can serve the same Model. A single repository can also carry several Models with different declared source scopes.
+
+| Arrangement | Historical address | What the Agent supplies |
+| --- | --- | --- |
+| Independent repository | Commit in that repository | Existing repository and a local checkout binding |
+| Submodule | Commit in the submodule repository | Model repository plus its owning project's relationship |
+| Program embedded in the project | Project repository commit | Program purpose and source scope when useful |
+| Program inside a monorepo | Repository commit plus relevant paths | Scope that includes meaningful build and generated-source inputs |
+| Additional worktree | Commit in the underlying repository | Model identity, worktree path, and intended base revision |
+
+Choose the arrangement that fits the project. There is no requirement to convert every Model into a submodule or independent repository. A local repository without a remote is sufficient for registration. Clone and fetch using Git before registration when needed.
+
+An ACCRETE project clone retains its project identity. A Model attached to that project does not automatically become a second ACCRETE project. Opening a shell inside the Model therefore does not establish the owning ACCRETE project for subsequent object writes; use explicit project selection when it is outside the project's ancestry.
+
+## Revisions and declared scope
+
+A commit gives an address in Git history. It does not completely describe a calculation. The interpreter, build flags, installed libraries, runtime imports, input Data, launch arguments, and execution environment can all matter. Domain Tools or the launcher describe those conditions in the Result when known.
+
+For a Model embedded in a research repository, a Memory change can advance `HEAD` while the numerical source remains unchanged. The Model may declare paths whose native Git tree or blob IDs help explain what changed. Include build configuration and relevant generated inputs in the scope when the project's meaning requires them. A scope named `src/` cannot by itself establish that all behavior is covered.
+
+Record the commit actually used and optional scoped content identities. Let scientific reasoning determine whether an earlier activity is useful for the current question. A matching scope identity does not make two activities automatically interchangeable.
+
+Allow dirty working trees. A commit plus a dirty observation says that the working material differed from the commit; it does not preserve those differences. An optional `accrete result capture` says exactly which paths were captured and what was omitted. A selected source bundle can be retained as Data and linked in the Result when more material is needed.
+
+## Iterations
+
+An iteration retains a named development effort around a Model. It typically describes a purpose, starting revision, branch or worktree, and eventual outcome and summary. It can begin before development or be attached to work already in progress. It has no required agent session, worker assignment, planning ceremony, or scientific approval state.
+
+| Moment | Meaning retained by ACCRETE | Work performed through ordinary tools |
+| --- | --- | --- |
+| Open | Purpose, Model, starting revision, and any worktree | Choose the question and prepare existing material |
+| Develop | Further activity can be associated through Results and Memory | Edit, compile, run, inspect, commit |
+| Integrate | Outcome may name the integrated commits | Merge, cherry-pick, rebase, or retain branches according to the project |
+| Close | Authored outcome, such as integrated or retained separately; relevant revisions | Decide how later work should continue |
+| Clean up | Separate explicit `model iteration remove-worktree` | Delete a branch with Git when appropriate |
+
+The outcome is an authored string. Use the project's language to describe what happened; the examples are not a fixed state enumeration. Closing does not imply success, merge a branch, remove an editing location, or erase outputs. An abandoned implementation can still explain a useful observation. An iteration retained separately can remain the basis of later development.
+
+Use worktrees on the actual Model repository for overlapping edits. An isolated outer project checkout can still refer to the same external Model checkout as another worker. Supply each worker with the Model path it should edit and the ACCRETE project root it should use for organizational writes.
+
+## Roles and other objects
+
+`reference`, `target`, and similar names describe the Model's role in a particular activity. A Model serving as a reference today can be developed tomorrow. The descriptor's aliases help people find it; they do not establish permanent subclasses or a universal rule against editing reference code.
+
+| Relationship | What to retain |
+| --- | --- |
+| Result uses a Model | Model ID, activity role, and execution revision when known |
+| Iteration develops a Model | Model ID, starting revision, purpose, worktree binding, outcome, and commits |
+| Tool acts on a Model | The Tool explains applicable source, build, diagnostic, or execution conventions |
+| Data captures selected source or output | Its own identity, material description, and origin; the Result links the relevant objects |
+| Memory explains development | Interpretation scoped to the relevant revision, Result, or conditions |
+
+An association may be meaningful even when the checkout is unavailable locally. Preserve a remotely supplied revision and path context without downloading a repository merely to make the metadata complete. Current availability can be resolved separately when the work needs the material.
+
+## Retaining cited history
+
+The Kernel retains a locally available commit cited by a Result or an iteration close with a native Git ref such as `refs/accrete/retained/<object-id>`. This helps keep an unmerged or detached commit available after ordinary branch cleanup. Read the mutation receipt to learn whether retention succeeded; a read-only repository may remain only a citation.
+
+Those refs are local. Normal clone, push, or bundle behavior must not be assumed to include arbitrary ref namespaces. Transport the specific retained refs when another host needs them, alongside the relevant repository and project metadata. This is native Git work, separate from the Model's identity or an iteration's close operation.
+
+Retiring a Model with `model retire` ends its current use and leaves the repository, checkouts, and earlier Results alone.
+
+The Model ID, commit, worktree, and optional capture answer different practical questions. Keep each association at the scope that was actually observed so the next session can use it without reconstructing an invented certainty.

package/dist/scaffold/assets/skills/accrete-models/references/working-practice.md

@@ -0,0 +1,48 @@
+# Model work across sessions and machines
+
+## Continue from the material already available
+
+Start with the owner's current question, the Model's relevant source and history, and Memory that helps that question. Read the specific earlier Results that the reasoning depends on. A past Result remains about the code and conditions it names. Trust retained work within that scope; repeating it is a scientific or engineering decision tied to the present task.
+
+Ordinary exploration needs no preliminary object write. A short source investigation can remain Scratch. Open an iteration when a named development effort, a separate branch, or a useful retained outcome would make continuation easier. Record Results for activities whose observations merit future use and Memory for the interpretation that should accompany them.
+
+## Embedded programs and changing project commits
+
+When source and research notes share a repository, describe implementation changes at the relevant scope. For example, a new Memory entry can advance the repository commit while the solver subtree is unchanged. Use native Git to inspect those paths and build inputs. The historical commit remains useful; scoped content identities add an explanation rather than replace it.
+
+Avoid inferring that an experiment must be repeated simply because root `HEAD` advanced. Equally, a matching solver subtree does not establish that the executable, environment, input data, or diagnostic were unchanged. Describe these conditions at their proper scope and use the task's scientific reasoning to decide the next action.
+
+## Concurrent development
+
+Give overlapping source work independent worktrees of the actual Model repository. Each worker needs the Model checkout, ACCRETE project root, intended base, useful constraints, and where to return its changes. Share read-only datasets and existing Results where appropriate. Use distinct Scratch and compilation-cache locations when the project's tooling requires them.
+
+A worker editing an external Model can call the Kernel with an explicit owning project root. That does not require installing `AGENTS.md` into every Model repository. Pass the relevant project guidance with the brief or through a documented host mechanism when the host session starts outside the project.
+
+Let the Coordinator choose ordinary Git integration: merge, cherry-pick, rebase, keep separate, or abandon. An iteration-close write follows the actual outcome. It supplies no implicit merge and no permission to remove the worker's checkout. If the project retains an unmerged commit, include the available retention information in the handover.
+
+## Capture what the activity used
+
+For a launch under your control, observe the checkout and relevant environment when preparing the actual execution. A Python invocation can load an installed package from somewhere other than the apparent working directory; a build can use artifacts from another source tree. Domain launchers should describe the implementation and runtime they actually selected.
+
+For an activity that already happened, use its launch record, known historical revision, and retained execution material. Today's `HEAD` is not evidence of the previous execution revision. If only the current checkout is available, keep that as a separately timed observation and leave the historical execution identity unknown.
+
+Uncommitted work is normal. If a source capture is useful, decide its scope explicitly. `git diff HEAD` excludes untracked files; text-only diffs may omit the content of binary changes. Neither form captures external dependencies or ignored build products. `accrete result capture --checkout PATH --path SOURCE_PATH --to DIRECTORY` writes a binary diff plus selected untracked files, with a manifest of its scope. A project Tool can prepare a broader source bundle or environment artifact and register it as Data when the task requires that.
+
+## Carry history to another host
+
+The project metadata can travel through the project's normal Git arrangement, or `accrete export` and `accrete import`, while the Model repository travels independently. Source hints and Model IDs remain portable; `accrete model bind` sets each host's concrete path. A received Result can be read before its Model is downloaded.
+
+When another machine needs an unmerged or detached commit, inspect the relevant repository's retained refs and deliberately transport those refs using native Git. A typical named ref can be sent with an explicit refspec or included in a Git bundle. Use the actual ref named in the receipt, and follow the project's chosen remote and transport arrangement.
+
+```text
+git -C MODEL_CHECKOUT show-ref refs/accrete/retained/OBJECT_ID
+git -C MODEL_CHECKOUT bundle create DESTINATION.bundle refs/accrete/retained/OBJECT_ID
+```
+
+These are native Git forms with values to supply. They do not promise that every referenced commit has an ACCRETE retention ref. A read-only or unavailable repository may prevent local retention; the Result remains a citation with that limitation.
+
+## Return enough for continuation
+
+Use a plain-language handover. State the question addressed, what changed or was learned, the concrete checkout and commit, meaningful outputs, any Results or Memory written, and what remains unresolved. Name the actual state of long-running computations using their native runtime evidence when relevant.
+
+Keep code outcome, observation, interpretation, and next direction distinguishable. A trace failure can explain a Model defect without producing a simulated trajectory. An implementation improvement can be ready for another experiment without establishing its scientific consequence. Retain each contribution at the scope it supports so subsequent work can proceed naturally.

package/dist/scaffold/assets/skills/accrete-results/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: accrete-results
+description: Preserve meaningful activities and observations as ACCRETE Results. Use for simulations, comparisons, analyses, benchmarks, transformations, failed attempts, retrospective execution descriptions, completion updates, or links between Model revisions, Tools, input Data, and retained outputs. Execute work with native tools and use the Kernel for durable Result writes.
+---
+
+# ACCRETE Results
+
+Retain what an activity involved and what was observed when that description
+will help continuing work. A Result can describe a simulation, failed build,
+numerical comparison, performance measurement, data transformation, or analysis.
+Create it before, during, or after the activity as useful. The research process
+does not depend on a mandatory registration sequence or run wrapper.
+
+## Select the change that matches the activity
+
+| Situation | Action |
+| --- | --- |
+| Retain a newly described activity | Draft structured input and call `accrete result record`. |
+| Add one observation to a known activity | Call `accrete result observe`. |
+| Correct associations or add structured completion information | Call `accrete result amend` using the current revision. |
+| Keep dirty working source beyond its checkout | Call `accrete result capture` and register the directory as Data if useful. |
+| Execute a new attempt | Run it natively and normally give it a new Result ID if retained. |
+| Reinterpret an earlier result | Write linked Memory; retain a new analysis Result if useful. |
+| Find present process state | Use the scheduler, process tools, logs, or domain launcher. |
+
+Describe only what is known. A historical Model revision comes from the
+execution's own information, not today's checkout HEAD. Missing environment
+details or absent outputs remain missing. A trace failure before simulation
+steps is a useful failure description; it is not a completed simulation with
+empty output. Dirty working content is allowed and should be described within
+what was captured.
+
+## Connect the useful objects
+
+Associate relevant Model revisions and their roles, Tool implementations,
+input Data, output Data, and related Results. Keep roles and domain measurements
+in ordinary structured values. A pair of run legs and their comparison can be
+linked without introducing a universal Experiment/Run/Trial hierarchy.
+
+Use Data for retained products and locations. Use Memory for interpretations,
+why a direction was chosen, and what later work can build on. Result publication
+preserves an activity description; its content can still describe an ongoing,
+incomplete, or failed activity. A draft in Scratch has not yet been published.
+
+## Preserve completed work through partial failures
+
+Publish managed Result changes through the native Kernel. A successful document
+publication with `index_pending` means the Result exists: refresh the SQL
+projection instead of creating it again. For an interrupted acknowledgment,
+reuse the supplied stable ID or operation ID and inspect the reported receipt. For
+uncertain durability, run `accrete recover`. Resolve revision conflicts by reading the current document
+and retaining independent contributions. Never rerun scientific computation to
+repair a Result or its index.
+
+Read existing JSON, Git history, logs, and the host-local SQLite projection
+with native tools; `accrete config resolve --json` gives the index path at
+`.local_state.index`, for `sqlite3 -readonly`. Use the configured project roots and explicit `--project`
+selection when outside the ACCRETE root.
+
+## Read when needed
+
+- [Activities and relationships](references/activities-and-relations.md):
+  execution identity, unknowns, content, roles, and related activities.
+- [Command manual](references/commands.md): input drafts, writes,
+  amendments, independent observations, source capture, and operation receipts.
+- [Scientific practice](references/scientific-practice.md): long runs,
+  comparisons, failures, remote work, and evolving interpretation.
+
+`accrete result COMMAND --help` prints the flags.

package/dist/scaffold/assets/skills/accrete-results/references/activities-and-relations.md

@@ -0,0 +1,116 @@
+# Activities and relationships
+
+## Contents
+
+- What a Result preserves
+- Execution identity
+- Publication, drafts, and activity completion
+- Relations and attempts
+- Native reading
+
+## What a Result preserves
+
+Preserve enough context for later work to understand an activity and use its
+observations. Useful information includes:
+
+| Information | Purpose |
+| --- | --- |
+| Activity label and description | Explain what was attempted or performed. |
+| Relevant Model IDs and revisions | Name programs associated with execution. |
+| Tool IDs and observed implementations | Identify capabilities used to obtain the observations. |
+| Input and output Data with roles | Connect retained materials to their use. |
+| Execution description | Preserve supplied host, environment, arguments, times, and runtime details. |
+| Observations | An array holding small measurements or prose; link larger products as Data. |
+| Related Results | Connect comparisons, independent legs, attempts, and continuations. |
+
+No field of a Result input is mechanically required by the Kernel. `execution` and
+`observations` are free-form. Leave unavailable information absent or explicitly
+null. Keep domain fields supplied by the scientific Tool. The
+Kernel need not understand a climate calendar, numerical diagnostic, or
+performance metric to preserve it.
+
+Describe units, averaging periods, domains, denominators, and comparison
+definitions where they affect interpretation. These are domain choices that
+make the observation usable; they are not a universal Result approval process.
+
+## Execution identity
+
+A Model commit identifies a repository snapshot. It may include changes to
+notes unrelated to the program. Optional native source-tree identities can
+describe a selected source scope, while dependencies and execution conditions
+still matter. Preserve the scope's actual meaning instead of treating matching
+tree identities as automatic scientific equivalence.
+
+The associated implementation must describe what the activity used. For a
+retrospective Result, the latest `git rev-parse HEAD` is only a present checkout
+observation. Use execution-time metadata, a retained checkout, a launcher
+description, or an explicit historical revision when available. Otherwise
+leave the execution revision unknown. The same applies to a Tool, installed
+binary, Python environment, and runtime arguments.
+
+Exploratory dirty work is valid. State the observed commit and known changes.
+A patch may omit untracked files, ignored files, binary content, or external
+dependencies; name the capture scope without claiming complete recovery.
+`accrete result capture` writes a selected diff and untracked files with a manifest
+of that scope. Register selected source bundles or environment artifacts as Data if the
+project chooses to retain them.
+
+## Publication, drafts, and activity completion
+
+A draft JSON file under Scratch is working material. `result record` publishes
+the durable activity description. Publication is an organizational operation;
+it does not declare that the activity completed or that its interpretation is
+accepted. The activity may still be running, partially complete, or failed.
+
+An old `running` observation remains historical. Use native process state for
+current status. A reported success from a launcher can be preserved as that
+launcher's report; distinguish it from the observations that support a
+scientific conclusion.
+
+Failed, incomplete, unknown, and absent describe different situations. A
+compilation failure, a job lost after several output intervals, and a completed
+simulation whose outputs have not yet transferred should retain those distinct
+descriptions. Avoid filling missing fields with success-shaped defaults.
+
+## Relations and attempts
+
+Give a genuinely new execution its own Result ID when retaining it. Similar
+configuration does not make two runs the same activity. A continuation of the
+same computation can append to its Result or become a linked continuation,
+according to the domain Tool's meaning.
+
+A multi-leg comparison can retain each leg and a separate comparison activity.
+Use meaningful related-result roles to explain the relation. A project can
+describe a larger experiment with an additional linked Result if useful;
+there is no required hierarchy or fixed number of levels.
+
+Input/output links describe participation. Add explicit derivation only when
+the project knows that stronger relation. A Result containing several inputs
+and outputs does not imply that each output derives from all inputs.
+
+Related objects may be unresolved on the current host. A remote Result can
+name Data left on a compute host or a Model commit absent from the local clone.
+Preserve those links without inventing checkouts or downloading bytes.
+
+Registering Data and associating it with a Result may be two completed writes.
+If the second stops, keep the Data identity and finish the association later.
+A metadata gap does not invalidate the completed scientific product.
+
+## Native reading
+
+Use ordinary tools to inspect the actual representation. For default roots:
+
+```sh
+rg 'routing|compilation|comparison' results
+jq '.observations[]' /actual/result/document.json
+```
+
+Select actual paths from configuration or mutation receipts. Read Git history
+with Git and output arrays with their scientific libraries. Open the index with
+`sqlite3 -readonly` at the path in `.local_state.index` from `accrete config resolve
+--json`, and inspect `.schema` before writing SQL. A brief "database is locked" during a concurrent refresh means retry. The index is a
+host-local projection; a Git pull can update documents before it is refreshed.
+`accrete index refresh` repairs that projection without changing the activity.
+
+Use Memory search to understand later interpretations. Preserve the execution
+description when a later insight changes what the observations suggest.

package/dist/scaffold/assets/skills/accrete-results/references/commands.md

@@ -0,0 +1,191 @@
+# Result command manual
+
+## Contents
+
+- Interface and input drafts
+- Record an activity
+- Amend structured information
+- Append an independent observation
+- Capture selected source
+- Interpret outcomes and retry
+
+## Interface and input drafts
+
+This manual covers the Result commands. `.accrete/docs/cli-contract.md` has the
+shared conventions and `accrete result COMMAND --help` prints the flags. Do not
+write persistent Result JSON or SQLite with a replacement script.
+
+Global options are `--project DIRECTORY` and `--json`; `ACCRETE_PROJECT` selects
+the project when no explicit path is supplied. Otherwise discovery starts
+from the current directory. Select the ACCRETE root explicitly when using an
+external Model checkout. Native scientific commands retain their ordinary
+working directory and execution interface.
+
+Draft structured inputs with an editor or domain Tool. The Kernel owns the
+durable envelope, default UUID allocation, publication, revision comparison, and index
+projection. Default Result paths are under `results/`; configuration and
+mutation receipts identify the actual path.
+
+## Record an activity
+
+```sh
+accrete --json result record --from scratch/result.json \
+  > scratch/result-receipt.json
+```
+
+The following draft illustrates an analysis for which implementation revisions
+were not retained. It deliberately leaves them unknown. Replace the example
+object IDs and domain content with the actual associations before use.
+
+```json
+{
+  "name": "first-year-comparison",
+  "activity": "Compare selected first-year diagnostics",
+  "models": [
+    {
+      "model_id": "model-main",
+      "role": "target",
+      "commit": null,
+      "dirty": null
+    }
+  ],
+  "tools": [
+    {
+      "tool_id": "tool-residual",
+      "revision": null
+    }
+  ],
+  "inputs": [
+    {
+      "data_id": "year-1-diagnostics",
+      "role": "diagnostics"
+    }
+  ],
+  "outputs": [],
+  "execution": {
+    "reported_outcome": "completed",
+    "description": "Retrospective description; execution revisions were unavailable."
+  },
+  "observations": [
+    {
+      "text": "The analysis completed; detailed conclusions are in the linked project notes."
+    }
+  ],
+  "related_results": []
+}
+```
+
+Omit unused association arrays or unknown fields. Supply known Git revisions and observed dirty state instead of
+nulls when execution information exists. Never fill a historical revision from
+today's checkout just to remove a null.
+
+| Draft field | Meaning |
+| --- | --- |
+| `name` | Optional short label. The index `name` column falls back to `activity`. |
+| `activity` | Optional human description of the retained activity. |
+| `models[]` | `{model_id, role?, commit: null|string, dirty: null|boolean}`. |
+| `tools[]` | `{tool_id, revision: null|string}` for actual implementation knowledge. |
+| `inputs[]`, `outputs[]` | `{data_id, role?}` associations. |
+| `execution` | Domain-supplied execution description; distinguish execution time from later observation time. |
+| `observations[]` | Array of free-form objects, conventionally with `text`: measurements, prose, and useful domain context. |
+| `related_results[]` | `{result_id, role?}` links to legs, attempts, comparisons, or continuations. |
+
+A supplied stable `id` or `--id` can support retries when creating the same Result.
+The same ID with the same submitted content is idempotent; different content
+requires an amendment or produces a conflict. IDs are 1-180 ASCII letters, digits,
+dots, underscores or hyphens, and not `.` or `..`. Keep unknown project extension
+fields when constructing any replacement or merge input.
+
+`--name` and `--description` override the draft's fields. `--observe-checkout PATH`
+adds the checkout's current state as a separately labelled `recording_observation`;
+it does not fill any execution revision.
+
+The receipt supplies `object_id`, `path`, and `revision`. Use those values for
+subsequent associations; the filename is not the semantic identity. For a `models[]`
+member with a `commit` and a local checkout, the receipt also names the ref that
+keeps that commit, or a warning saying why it could not.
+
+## Amend structured information
+
+```sh
+accrete --json result amend "$RESULT_ID" \
+  --from scratch/change.json --expect "$REVISION"
+```
+
+The patch is a JSON Merge Patch of editable Result fields. Objects
+merge recursively; arrays are replaced as complete arrays; `null` removes a
+key in a patch. Identity, kind, and format fields are not editable through an
+ordinary amendment. Do not use a null patch value to mean unknown without
+considering its removal semantics.
+
+For example, a draft adding completion description can contain:
+
+```json
+{
+  "execution": {
+    "reported_outcome": "completed",
+    "description": "The final closed output was retained and associated."
+  }
+}
+```
+
+When changing an association array, read the current Result and include all
+members that should remain. Do not replace the array with only the new member.
+Use the expected revision corresponding to that read. A successful earlier
+receipt is usable only while the document still has that revision. A revision is
+the SHA-256 of the document's exact bytes, so any SHA-256 tool can compute it.
+
+A revision conflict leaves current content and your draft intact. Read the
+current document, incorporate independent contributions, and submit the intended
+patch with its current revision. Do not weaken the expected-revision condition
+to force a stale draft through.
+
+## Append an independent observation
+
+```sh
+accrete --json result observe "$RESULT_ID" \
+  --text-file scratch/observation.md
+```
+
+Use this for a new independent observation whose meaning does not require
+replacing the whole description. The Kernel appends a member to the `observations`
+array, serialized locally. When a launcher needs retry protection, supply
+`--operation-id ID`. The same operation ID and text append once; reusing it with
+changed text is a conflict.
+
+Use an amendment for structured corrections or associations. Use later linked
+Memory for a changed scientific interpretation. An observation of a process at
+a particular time does not establish its present state indefinitely.
+
+## Capture selected source
+
+```sh
+accrete --json result capture --checkout ../numerical-model \
+  --path src --path pyproject.toml --to scratch/source-capture
+```
+
+Use this when dirty working source should survive beyond the checkout. It writes a
+binary Git diff against `HEAD` and the selected nonignored untracked regular files to
+a new directory, with a manifest stating the captured scope. Repeat `--path`.
+Ignored products, external dependencies and runtime state stay outside it, so it is
+not a complete executable environment. Capture publishes no object; register the
+directory as Data if it should be retained, and link it from the Result.
+
+## Interpret outcomes and retry
+
+A successful publication returns `committed: true`. If `index_pending: true`,
+the Result still exists and the operation is successful; run:
+
+```sh
+accrete index refresh
+```
+
+Do not call `result record` with a new ID to repair that projection. After an
+uncertain acknowledgment, use a supplied stable ID or operation ID to reconcile
+the same operation. If publication is visible but durability is uncertain (exit 8),
+keep the published path and run `accrete recover`. Inspect before interpreting a
+nonzero exit as “nothing changed.”
+
+Recovery repairs metadata or associated native side effects. It never launches
+the scientific calculation again. A new execution is an explicit domain action
+with its own meaning and normally a new Result identity.

package/dist/scaffold/assets/skills/accrete-results/references/scientific-practice.md

@@ -0,0 +1,89 @@
+# Results in continuing scientific work
+
+## Comparisons
+
+Retain the programs and data that actually participated in each leg. The role
+`reference` belongs to the comparison; it does not make a Model permanently
+immutable or place it in a separate Kernel class. Describe each leg's execution
+revision, initial state, forcing, runtime conditions, and known differences
+when useful to the interpretation.
+
+Store compact measurements in observations and large histories or diagnostics
+as Data. A comparison Result can link the leg Results, the analysis Tool used,
+and the selected output products. Explain metric definitions in its description
+or associated domain Tool. The Coordinator decides what constitutes an adequate
+comparison and which further work is warranted.
+
+Historical Results describe their named implementations. Advancing a Model
+branch or changing a comparator does not retroactively change those Results.
+A new analysis of old products can have a new Result and linked Memory.
+
+## Long-running computation
+
+A Result can be introduced before launch, after a useful milestone, or after
+completion. Choose according to what helps the work. No ACCRETE wrapper is
+required around `python`, `mpirun`, `sbatch`, `nohup`, or a domain launcher.
+
+Retain activity times and publication times separately when they differ.
+An observation may describe a completed interval or partial output. Keep the
+scientific time coordinate in domain fields; a metadata timestamp does not
+replace the simulation calendar.
+
+Register completed output products independently when useful. Later stages
+can produce new Data and append observations to an existing activity, or create
+related continuation Results. Let the program's actual continuity determine
+that choice rather than a fixed template workflow.
+
+Use the owning scheduler, launcher, logs, or process table to determine present
+execution state. The last durable observation can guide where to look but
+does not keep itself current.
+
+## Failed and incomplete attempts
+
+A failed attempt can be worth retaining because its cause, surviving output,
+or execution conditions help future work. State where it stopped and what
+actually happened. For example, a failure during tracing before compilation
+or time stepping has no simulated history; a run interrupted after several
+days may have valid closed products for those days.
+
+Keep the failed attempt's identity when recording a diagnosis. If a corrected
+implementation is launched again, retain a new Result linked to the earlier
+attempt. A repeated CLI write after an uncertain acknowledgment is different:
+it attempts to persist the same activity description and should reuse its
+stable ID.
+
+Do not rerun an expensive experiment merely because its JSON index is stale,
+its output location association is incomplete, or its Result needs correction.
+Repair the specific persistence step using the existing activity material, with
+`accrete index refresh`, `accrete recover`, or an amendment.
+
+## Remote work
+
+Record the execution information available where the work runs. Small Result
+documents and Memory can travel by the project's Git or `accrete export` and
+`accrete import` while
+large products remain on the compute host. Materialize selected Data when local
+analysis requires it. Receiving a Result does not imply that its inputs, outputs,
+or cited Git commits were transported with it.
+
+Use host-local Kernel state and a separate metadata view or a selected writing
+host. Local locks and SQLite do not establish coordinated multi-host writes to
+a shared network directory. Where `import` meets divergent content under one
+stable ID, it reports a conflict; preserve both drafts and resolve the difference.
+Do not choose the latest timestamp automatically.
+
+## Interpretation and accumulated experience
+
+Use Result amendments for corrected activity descriptions or associations.
+Use independent observations for additional measurements or contextual notes.
+Use Memory for a changed explanation, a useful lesson, or a next direction.
+Link the relevant Result IDs and state the limits of the interpretation.
+
+Trust prior work within its documented scope. Repeat it when the current task
+or a concrete changed condition calls for repetition. A template should not
+force every session to reconfirm inherited experiments before useful new work.
+
+A useful handover names the completed activity, Result and Data IDs, concrete
+paths, execution revisions when known, and any unfinished publication or
+transfer step. It also says what the observations suggest. That gives the next
+agent enough context without turning the return into a rigid task schema.

package/dist/scaffold/assets/skills/accrete-tools/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: accrete-tools
+description: Retain and evolve ACCRETE project capabilities as Tools. Use when a useful script, program, knowledge guide, diagnostic, or Skill should acquire a project identity; when updating or binding its selected source, exposing it to Codex or Claude Code, refreshing discovery, exporting a local package, or retiring current use while preserving earlier associations.
+---
+
+# ACCRETE Tools
+
+Treat a Capability as something the project can understand or do. Treat its Tool as the durable project identity for the implementation and knowledge that makes that ability reusable. Treat a Skill as one host's discovery interface for it. A Tool can contain prose alone, a program alone, or both.
+
+## Develop the capability naturally
+
+Write source, instructions, examples, or configuration with ordinary tools. A one-off script can stay in Scratch while it develops. Admit it when retaining its purpose and usable source would help subsequent work. Admission creates an identity; the Agent and owner judge usefulness through their work.
+
+Choose a source location that the project can maintain: a normal project directory, an independent repository, or an explicitly associated external location. Use native Git when version history is useful. Preserve the language, environment, and native programs appropriate to the capability.
+
+Keep code and knowledge together where that helps another Agent use the Tool. Explain its purpose, applicable inputs, practical action, meaningful outputs, and limits of interpretation. Make a Skill concise and put detailed operational knowledge in its source-relative references. A cognitive guide needs no invented executable entry point.
+
+## Use the right organizational operation
+
+- Admit existing source with `tool admit` when it should become a retained project capability.
+- Use `tool bind` to point this host at the Tool's source when it lives elsewhere here.
+- Use `tool update` for descriptor changes or a deliberately selected source revision.
+- Use `tool expose --agent codex|claude` to add a project-local discovery interface; use `tool refresh` to update existing managed discovery after source or description changes.
+- Use `tool export` for an explicit local destination when material should be reused elsewhere.
+- Use `tool retire` when ordinary discovery should stop; preserve the source and earlier Result associations.
+
+Use the Kernel for these operations. Editing source, invoking its program, committing improvements, and publishing through a chosen external distribution channel remain ordinary work.
+
+## Distinguish source from exposure
+
+Edit the Tool's source, including its source `SKILL.md`. A generated host wrapper points to that source and explains where relative references and executable paths resolve. Read the complete source instructions before using the capability. Keep `scripts/run.py` relative to the source directory, never to a wrapper directory.
+
+The portable exposure is a real host Skill directory containing a wrapper. A supported symlink is an explicit alternative. One Tool can be available through both hosts without becoming two Tools. Foundational ACCRETE Skills are distribution snapshots; domain Tool sources evolve with project practice.
+
+A **live** source binding follows the editable source. A **retained** binding refers to material that actually corresponds to the selected revision, such as a dedicated checkout or export. Prepare that material with native tools. Refreshing discovery never checks out a selected historical revision into an unrelated active working tree.
+
+If the source is unavailable or the retained material has not been supplied, preserve the Tool and report pending exposure. Read the receipt for the interfaces actually installed. A running Agent may still hold earlier instructions; name consequential changes in the handover and have subsequent work load the changed source explicitly.
+
+## Associate actual use and accumulated experience
+
+Record the Tool ID in a Result when the capability helped produce a retained activity. Supply the implementation actually used when known: source commit, entry point, artifact identity, and useful execution conditions. A live Tool's admission-time commit does not establish the version used later.
+
+Retain interpretation and reusable lessons in Memory, and improve the Tool when those lessons belong in its operating knowledge. Do not rewrite earlier Results to match the Tool's latest behavior. Export only the intended material and use the project's ordinary publishing mechanism for any later external distribution.
+
+## References
+
+- [Object meaning and relationships](references/objects.md): Capability, Tool, Skill, live and retained binding, identities, and retirement.
+- [Kernel operations](references/cli.md): input drafts, command forms, exposure destinations, receipts, and incomplete operations.
+- [Developing useful capabilities](references/working-practice.md): agent-oriented instructions, source-relative resources, long-term improvement, and use from different hosts.
+
+Read the installed `.accrete/docs/cli-contract.md` from the project root for the shared contract. `accrete tool COMMAND --help` prints the flags. On a host without the binary, retain input drafts in Scratch and continue useful source development.