spec-driven-docs 0.2.0

Spec-driven documentation: current specs, immutable decision records, and executable gates kept coherent for people and coding agents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# Instance distribution

An instance keeps its current specs, configurations, templates, and manifest in its own checkout, and runs the gates and the verifier from the installed `sdd` binary, which carries the whole payload. Canon provenance is consulted for installation and upgrades, never for routine work.

Ownership has three classes:

- Managed files are byte-for-byte projections. Verification fails on drift; upgrades replace only an unchanged installed projection.
- Adopted files are seeded once and owned locally. The manifest records both the installed bytes and the upstream baseline they came from, so an edit reports drift until it is reconciled and upgrades preserve it.
- Integration blocks are delimited regions inside local files. Tools may replace only the marked block.

The only requirements are `git`, `pre-commit`, and `sdd` on the PATH of everyone who runs the hooks, including CI. Install `sdd` with `cargo install spec-driven-docs`, with `cargo binstall spec-driven-docs`, or from a GitHub release's installers. The binary embeds the payload for its own version, so verification and upgrades run offline; `sdd verify` compares its version to the instance's and says which side to move.

## Instantiate

Run without flags first. A non-empty target with no instance defaults to a dry run, and `--apply` is what writes into it.

```bash
sdd init --target /path/to/your-project --profile codebase
sdd init --target /path/to/your-project --profile codebase --apply
```

Use `knowledge-base` to select `_docs/`; `codebase` selects `docs/`. Review the managed pre-commit block before applying it to a heavily commented configuration. The block is spliced into the top-level `repos:` sequence, so a configuration without that key is refused rather than rewritten.

Lightweight consumers may use the public remote hooks with an immutable release tag; pre-commit builds the binary from this repository with cargo:

```yaml
repos:
  - repo: https://github.com/gubasso/spec-driven-docs
    rev: v0.2.0
    hooks:
      - id: spec-rule-id-unique
```

## Verify

```bash
sdd verify --target /path/to/your-project
```

Verification is always offline: hashes, the managed block, local rule IDs, and the version alignment between the binary and the instance.

## Upgrade

Install the newer `sdd`, review its changelog, then dry-run the upgrade:

```bash
sdd upgrade --target /path/to/your-project --dry-run
sdd upgrade --target /path/to/your-project
```

A locally edited managed file aborts the entire operation, and every conflict is listed in one run. Reconcile them explicitly; adopted specs and content outside the markers are never overwritten, and the upgrade never touches `.git`.