dsh-project-anchor

Readme

# dsh-project-anchor

[![ci](https://github.com/KKLL2025/dsh-project-anchor/actions/workflows/ci.yml/badge.svg)](https://github.com/KKLL2025/dsh-project-anchor/actions/workflows/ci.yml)

English | [简体中文](README.zh-CN.md)

`dsh-project-anchor` keeps a solo, long-running DSH project attached to a
user-approved Goal, one active Milestone, and a durable Turn checkpoint while
leaving project judgment in on-demand Skills.

This GitHub-only public Preview route is tested against DeepSeek Harness
`0.1.0-rc.6`. Each supported Release records its reviewed revision, fixed-SHA
CI, public-source installation evidence, and private security-reporting route.
npm publication is deliberately outside this route.

## What's new in `v0.1.0-preview.1`

- Cold recovery can now offer a consent-gated native resume for the exact DSH
  Goal linked to an active Anchor. Missing state, drift, deferral, unavailable
  questions, and resume failure all leave the Anchor and Milestone unchanged.
- A complete [Simplified Chinese README](README.zh-CN.md) now covers installation,
  first use, recovery, limits, removal, and maintainer verification.
- The bundled `drive-large-project` guidance now makes `fast`, `continuity`, and
  `high-risk/release` execution intensity explicit without adding another
  persisted planner or risk field to the plugin.
- Frozen Skill provenance now identifies the merged upstream revision while all
  bundled payload bytes remain unchanged and hash-verified.

This remains a source-only GitHub Preview: install the reviewed full commit from
the release notes. There is no npm package or moving-branch install route.

## Install the pinned GitHub Preview

You need Node `^22.19.0 || >=24.11.0`, pnpm on `PATH`, and DeepSeek Harness
`0.1.0-rc.6`. Open the
[`v0.1.0-preview.1` release](https://github.com/KKLL2025/dsh-project-anchor/releases/tag/v0.1.0-preview.1),
copy its verified 40-character source commit, and use that exact value below:

```sh
npm install --global @deepseek-ai/dsh@0.1.0-rc.6
dsh --version
dsh plugin --profile web add github:KKLL2025/dsh-project-anchor#<FULL_COMMIT_SHA>
```

The first add is expected to stop before running the Git package's `prepare`
build. Copy the complete dependency key printed by pnpm into the selected
profile's `pnpm-workspace.yaml`; do not shorten it to the package name:

```yaml
allowBuilds:
  '<EXACT_KEY_PRINTED_BY_PNPM>': true
```

Review the pinned source before granting that permission, then repeat the same
add command and verify the installed dependency and composed bundle:

```sh
dsh plugin --profile web add github:KKLL2025/dsh-project-anchor#<FULL_COMMIT_SHA>
dsh plugin --profile web list dsh-project-anchor --depth 0
dsh --profile web --dump-config
dsh --profile web
```

Require `dsh --version` to print `0.1.0-rc.6` and the dependency list to include
`dsh-project-anchor`. The config dump should contain exactly one
`# == dsh-project-anchor` layer. If Web was already running, restart that DSH
process after installation. The
[getting-started guide](docs/getting-started.md) covers verification, removal,
other profiles, and common failures.

## Start a project

Use a normal project request that names the long-project Skill:

> Use `drive-large-project` for this multi-session project: &lt;describe the
> project and desired result&gt;. Recover the repository's real state, choose one
> independently verifiable Milestone, carry it through validation, and finish
> the Turn with the Project Anchor checkpoint. Ask me before decisions that
> change product direction, permissions, spending, or public release.

When no current DSH Goal exists, a successful Skill load makes Project Anchor ask
whether to enable its persistent continuity layer. Enabling it opens focused
questions for the exact Goal and first Milestone; the plugin does not infer or
rewrite either answer. When a suitable DSH Goal already exists, the same trigger
offers an explicit reuse or resume choice instead of replacing that Goal.

For a later session, this shorter request is enough:

> Continue this project with `drive-large-project`. Recover the current Goal,
> Project Anchor state, handoff, and repository facts; work only on the next
> unblocked Milestone, then validate and checkpoint it before ending the Turn.

After a cold session recovery, DSH leaves the Goal disarmed. The next successful
`drive-large-project` load checks that the current Goal still matches the active
Anchor exactly and asks whether to resume it. Only an explicit `Resume this Goal`
answer calls DSH's native resume; deferral, missing state, changed revisions, and
unavailable questions leave the Goal, Anchor, and Milestone unchanged.

## Adaptive execution intensity

For each Milestone, `drive-large-project` selects the lightest sufficient
execution intensity from the current risk and acceptance boundary:

- `fast` fits reversible, local work with low uncertainty and inexpensive
  checks. It normally uses a focused test without adding management documents,
  release smoke, or independent audit.
- `continuity` fits work that crosses Turns or modules, changes durable state,
  or would be costly to recover incorrectly. It keeps the current handoff and
  adds the integration checks required by the changed contract.
- `high-risk/release` fits irreversible, external, security-sensitive,
  migration, compatibility, or publication work. It expands evidence to the
  broad tests, consumer/runtime paths, artifacts, and independent review needed
  for the claim being made.

This intensity is temporary Skill judgment rather than native plugin state, so
the model cannot persist or raise it through an Anchor field. Repository rules,
explicit user decisions, and the current acceptance claim remain authoritative;
public release and other external actions still require separate authorization.

## What is included

The package carries byte-for-byte frozen copies of `align-project-requirements`,
`drive-large-project`, and `organize-ai-project-files`. DSH lists their metadata,
then loads a Skill body and its referenced resources only when selected. Project
and user Skill roots keep their native precedence over these bundled defaults.

The native plugin remembers consent and the stable Goal association, exposes a
checkpoint tool only while the Anchor is active, and derives Goal, Milestone,
and Turn identity from live DSH state. Ordinary tools remain unrestricted. A
missing checkpoint receives at most one short same-Turn repair attempt, avoiding
an enforcement loop. Restart recovery leaves interrupted-Turn closure and Goal
activation under DSH's native lifecycle.

## Compatibility and limits

- Verified host: DeepSeek Harness `0.1.0-rc.6`, source revision
  `47f943859bef60e4160492346772ded9b24f765a`.
- DeepSeek Harness is in developer preview, so later releases may require plugin
  changes.
- GitHub source at the full commit recorded in the Preview release is the only
  public distribution path. The package remains unpublished to npm.
- A Git source install runs this package's `prepare` script only after pnpm's
  explicit `allowBuilds` approval. That is host code execution, so review the
  source and pin a full commit SHA. Do not install from a moving branch.
- A completed Goal is not replaced or reused. Headless activation without a
  question provider fails closed.
- Restart recovery has been tested with JSONL persistence in a separate Node.js
  process; OS power loss, torn writes, and cross-machine recovery are outside the
  current evidence.

## Maintainer verification

```sh
npm run check
npm run smoke:onboarding
npm run smoke:consumer
npm run smoke:git-source
npm run rc:local
```

The onboarding smoke resolves the rc.6 CLI from `DSH_ENTRY`, a local/prepared
installation, or npm's global root. It uses an isolated `DSH_HOME` to pack,
install, list, compose, remove, and re-check the plugin without booting a profile
or sending a prompt. The consumer smoke also
boots fresh Web and headless profiles, validates both plugin fibers and the three
frozen Skills, and sends no prompt. `rc:local` builds one candidate tarball and
reuses that exact file in both paths before checking the local Git-source
`prepare` route and writing an ignored machine-readable evidence manifest.

See [the development contract](docs/development-contract.md) for ownership,
state-machine, validation, and safety boundaries. Release evidence is defined in
[the candidate gate](docs/release-candidate.md); host-code and frozen-Skill trust
boundaries are explicit in [SECURITY.md](SECURITY.md). Contributors should start
with [CONTRIBUTING.md](CONTRIBUTING.md).