task-pipeline-skill 1.17.0 → 1.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +51 -0
- package/README.md +1 -0
- package/SKILL-CARD.md +1 -1
- package/package.json +1 -1
- package/plugins/task-pipeline/.claude-plugin/plugin.json +2 -2
- package/plugins/task-pipeline/skills/task-pipeline/SKILL.md +2 -0
- package/plugins/task-pipeline/skills/task-pipeline/references/deploy-targets.md +184 -0
- package/plugins/task-pipeline/skills/task-pipeline/references/grill.md +1 -0
- package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md +22 -0
- package/plugins/task-pipeline/skills/task-pipeline/references/learned.md +3 -0
- package/plugins/task-pipeline/skills/task-pipeline/references/portability.md +1 -0
- package/plugins/task-pipeline/skills/task-pipeline/references/stages.md +11 -2
- package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,55 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v1.19.0
|
|
4
|
+
|
|
5
|
+
### The copy you are about to edit may not be the copy that ships — `learned.md` rule 17
|
|
6
|
+
|
|
7
|
+
A machine keeps a skill twice: the working copy it publishes from and the installed plugin it runs.
|
|
8
|
+
On 2026-08-07 the working copy was **two commits behind its own origin** — `v1.16.2` against
|
|
9
|
+
`v1.18.0` — and the newer commits carried rule 16 itself. The tree was clean and nothing had
|
|
10
|
+
diverged; the copy had simply never been pulled. An edit there would have landed on 1.16.2 and the
|
|
11
|
+
release would have **deleted rule 16 and two versions of work by fast-forward** — not as a conflict
|
|
12
|
+
git would show, but silently. The project's own instruction names that directory as the source, so
|
|
13
|
+
whoever did it would have been following the documentation.
|
|
14
|
+
|
|
15
|
+
The check is one command and it runs **before the first edit**:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
git fetch -q && git rev-list --count HEAD..@{u} # 0, or stop and pull
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- `references/learned.md` — rule 17 and incident 17.
|
|
22
|
+
- `references/knowledge-sources.md` — a harvest section, because this is a property of the sources
|
|
23
|
+
that reading them cannot reveal.
|
|
24
|
+
- `references/grill.md` + `templates/brief.md` — autonomy-sweep row `0 Source`, in both files: the
|
|
25
|
+
grill asks it, the brief records it, and a topic in only one is a question with nowhere to land.
|
|
26
|
+
- `test/validate.py` — a guard in the shape of rule 16's, so dropping a citation fails the build
|
|
27
|
+
rather than quietly ending the coverage. Both halves were watched failing against planted defects.
|
|
28
|
+
|
|
29
|
+
## v1.18.0 — 2026-08-06
|
|
30
|
+
|
|
31
|
+
### Added
|
|
32
|
+
- **`references/deploy-targets.md`** — stages 7 and 8 knew what a deploy must
|
|
33
|
+
satisfy and never said what to run. This carries the runbook template, the
|
|
34
|
+
per-platform verbs (Heroku, DO App Platform, droplet over SSH, CI-as-deploy,
|
|
35
|
+
and the quick table for Fly/Vercel/Cloudflare), and the verification trio.
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
- **Stage 7: a missing runbook is now the stage's first deliverable**, not a
|
|
39
|
+
reason to improvise. A deploy performed from an agent's inference about the
|
|
40
|
+
project is one nobody can repeat or roll back, and the operator is already
|
|
41
|
+
standing at that manual gate — the questions cost two minutes there and cannot
|
|
42
|
+
be reconstructed during an incident.
|
|
43
|
+
- **Stage 8 names all three verifications, and says to check the deploy job**,
|
|
44
|
+
not only the build. A green build beside a skipped or failed deploy is the
|
|
45
|
+
commonest way a run reports success while nothing shipped — previously the
|
|
46
|
+
stage said "confirm clean boot" and left the shape of the confirmation open.
|
|
47
|
+
|
|
48
|
+
### Notes
|
|
49
|
+
- Ported from a standalone `deploy` skill that lived only in a Cursor skills
|
|
50
|
+
directory. The pipeline already owned the gates; what it lacked was the
|
|
51
|
+
concrete verbs behind them, so the skill folded in rather than shipping beside.
|
|
52
|
+
|
|
3
53
|
## v1.17.0 — 2026-08-06
|
|
4
54
|
|
|
5
55
|
**A carried-in claim is a recollection — `learned.md` rule 16, and the four places
|
|
@@ -98,6 +148,7 @@ landed and the floor stayed at 104 while the file carried 108. A floor below the
|
|
|
98
148
|
cannot notice losing the difference, which is the entire job. Now guarded, and the
|
|
99
149
|
guard was watched rejecting a lowered floor.
|
|
100
150
|
|
|
151
|
+
|
|
101
152
|
## v1.16.1 — 2026-08-06
|
|
102
153
|
|
|
103
154
|
### Fixed — frontmatter that a regex called valid and a YAML parser silently dropped
|
package/README.md
CHANGED
|
@@ -799,6 +799,7 @@ recommendation, so you arm the whole run in one exchange. Detail:
|
|
|
799
799
|
| [`references/conventions.md`](plugins/task-pipeline/skills/task-pipeline/references/conventions.md) | how stages 6–10 read the host project's `CLAUDE.md`, and how the documentation regime is detected |
|
|
800
800
|
| [`references/documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) | the doc system: the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
|
|
801
801
|
| [`references/gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) | the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs |
|
|
802
|
+
| [`references/deploy-targets.md`](plugins/task-pipeline/skills/task-pipeline/references/deploy-targets.md) | stages 7–8: writing the runbook when there is none, the template, per-platform deploy and log verbs, the verification trio |
|
|
802
803
|
| [`references/hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) | the `PreToolUse` contract, the fail-open hazard, placement, and the Claude-Code-only limit |
|
|
803
804
|
| [`references/knowledge-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md) | the code graph: install line, stage-0 reach queries, the stage-9 refresh, the graph↔docs divergence check |
|
|
804
805
|
| [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
|
package/SKILL-CARD.md
CHANGED
|
@@ -12,7 +12,7 @@ harmless.
|
|
|
12
12
|
|---|---|
|
|
13
13
|
| **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
|
|
14
14
|
| **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
|
|
15
|
-
| **Version** | 1.
|
|
15
|
+
| **Version** | 1.19.0 |
|
|
16
16
|
| **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
|
|
17
17
|
| **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
|
|
18
18
|
| **Evaluation status** | Suite authored (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "task-pipeline-skill",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.19.0",
|
|
4
4
|
"description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"task-pipeline": "bin/task-pipeline.js"
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "task-pipeline",
|
|
3
3
|
"displayName": "Task Pipeline",
|
|
4
|
-
"description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill
|
|
5
|
-
"version": "1.
|
|
4
|
+
"description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
|
|
5
|
+
"version": "1.19.0",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "ssheleg",
|
|
8
8
|
"url": "https://x.com/sshlg93"
|
|
@@ -49,6 +49,7 @@ gate stops until it is installed.
|
|
|
49
49
|
| 0 + 9 + any settled decision · The documentation system | [`references/documentation.md`](references/documentation.md) |
|
|
50
50
|
| any claim that will be read as true · The canons, and where each is enforced | [`evidence-docs`](../evidence-docs/SKILL.md) — the sibling skill in this plugin |
|
|
51
51
|
| 6–10 + any check you write · Gates | [`references/gates.md`](references/gates.md) |
|
|
52
|
+
| 7–8 · Deploy targets | [`references/deploy-targets.md`](references/deploy-targets.md) |
|
|
52
53
|
| any agent-time enforcement · Hooks | [`references/hooks.md`](references/hooks.md) |
|
|
53
54
|
| 0 Knowledge harvest (pre-grill) | [`references/knowledge-sources.md`](references/knowledge-sources.md) |
|
|
54
55
|
| 0 + 9 The code graph (graphify — recommended, never required) | [`references/knowledge-graph.md`](references/knowledge-graph.md) |
|
|
@@ -330,6 +331,7 @@ automation is on — `pipeline.schema.json` is the only contract.
|
|
|
330
331
|
- `references/retrospective.md` — stage 10's last act: the project retro (`docs/superpowers/retro.md`), the three grades of fix, the mandatory prune and its cap of ten
|
|
331
332
|
- `references/documentation.md` — cross-cutting: the doc inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built
|
|
332
333
|
- `references/gates.md` — cross-cutting: the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs
|
|
334
|
+
- `references/deploy-targets.md` — stages 7–8: writing the runbook when there is none, the template, per-platform deploy and log verbs, and the verification trio
|
|
333
335
|
- `references/hooks.md` — agent-time enforcement: the PreToolUse contract, the fail-open hazard, placement, and the Claude-Code-only limit
|
|
334
336
|
- `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks
|
|
335
337
|
- `references/learned.md` — cross-cutting: fifteen rules earned by failure on a real multi-repository build, each with the incident behind it, its check and its exit criterion; plus the two that no check can decide
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Deploy targets — the runbook, and the verbs when the runbook is thin
|
|
2
|
+
|
|
3
|
+
**Load this when:** stage 7 is about to deploy or stage 8 is about to verify, and
|
|
4
|
+
the project's own runbook either does not exist yet or does not say enough to
|
|
5
|
+
act on.
|
|
6
|
+
|
|
7
|
+
The project's `docs/DEPLOYMENT.md` outranks everything here. This file exists for
|
|
8
|
+
the two moments it cannot help: when there is no runbook to read, and when the
|
|
9
|
+
runbook names a platform whose verbs you have to recall. `conventions.md` says
|
|
10
|
+
where to look; this says what to run once you know.
|
|
11
|
+
|
|
12
|
+
## Contents
|
|
13
|
+
|
|
14
|
+
- If there is no runbook, write one first
|
|
15
|
+
- Runbook template
|
|
16
|
+
- Heroku
|
|
17
|
+
- DigitalOcean App Platform
|
|
18
|
+
- Droplet / bare server over SSH
|
|
19
|
+
- Deploy that happens in CI
|
|
20
|
+
- Other platforms, quick verbs
|
|
21
|
+
- The verification trio
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## If there is no runbook, write one first
|
|
26
|
+
|
|
27
|
+
A deploy performed from an agent's inference about the project is a deploy
|
|
28
|
+
nobody can repeat or roll back. Stage 7's authorization floor assumes a
|
|
29
|
+
documented procedure; absent one, **the runbook is the first deliverable of the
|
|
30
|
+
stage**, gathered from the operator and committed before anything ships.
|
|
31
|
+
|
|
32
|
+
Ask for what the template below leaves blank — the target, the trigger, the
|
|
33
|
+
gate commands, where secrets live, the migration step, the health check, the
|
|
34
|
+
rollback — and write the answers down. The questions take two minutes at the
|
|
35
|
+
gate where the operator is already present. Reconstructing them during an
|
|
36
|
+
incident does not.
|
|
37
|
+
|
|
38
|
+
## Runbook template
|
|
39
|
+
|
|
40
|
+
Scaffold `docs/DEPLOYMENT.md` with this. Fill every placeholder, delete what does
|
|
41
|
+
not apply, keep it short — it is the source of truth stage 7 follows, and a long
|
|
42
|
+
one goes stale.
|
|
43
|
+
|
|
44
|
+
```markdown
|
|
45
|
+
# Deployment
|
|
46
|
+
|
|
47
|
+
## Overview
|
|
48
|
+
- Project: <name>
|
|
49
|
+
- Environments: <production | staging | ...>
|
|
50
|
+
- Deploy branch: <main>
|
|
51
|
+
- Deploy trigger: <CLI push | container registry | CI on push>
|
|
52
|
+
|
|
53
|
+
## Platforms / targets
|
|
54
|
+
| Env | Platform | App / service | Region | Notes |
|
|
55
|
+
|-----|----------|---------------|--------|-------|
|
|
56
|
+
| production | <Heroku / DO App Platform / Droplet / Fly / Vercel / AWS / SSH> | <app-name or id> | <region> | <notes> |
|
|
57
|
+
|
|
58
|
+
## Pre-deploy gate
|
|
59
|
+
Commands that must pass before deploying:
|
|
60
|
+
- Lint: `<command>`
|
|
61
|
+
- Type check: `<command>`
|
|
62
|
+
- Tests: `<command>`
|
|
63
|
+
- Build: `<command>`
|
|
64
|
+
|
|
65
|
+
## Deploy steps
|
|
66
|
+
1. <exact commands, in order>
|
|
67
|
+
2. <release / migration commands>
|
|
68
|
+
|
|
69
|
+
## Environment variables / secrets
|
|
70
|
+
- Stored in: <Heroku config vars | DO app-level secrets | .env on server | GitHub secrets>
|
|
71
|
+
- Required keys (NAMES ONLY, never values): <KEY_A, KEY_B, ...>
|
|
72
|
+
|
|
73
|
+
## Migrations / release-phase commands
|
|
74
|
+
- <e.g. release phase in Procfile, or `heroku run <migrate> -a <app>`>
|
|
75
|
+
|
|
76
|
+
## Post-deploy verification
|
|
77
|
+
- Health check URL: <https://.../health> → expected `<200 / payload>`
|
|
78
|
+
- Logs: <exact command per platform>
|
|
79
|
+
- CI build (if any): <workflow name / link>
|
|
80
|
+
|
|
81
|
+
## Rollback
|
|
82
|
+
- <exact procedure — the one thing nobody writes down and everybody needs>
|
|
83
|
+
|
|
84
|
+
## Contacts / ownership
|
|
85
|
+
- Owner: <who>
|
|
86
|
+
- Escalation: <who / where>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**Never write secret values into the runbook.** Names only. A runbook is
|
|
90
|
+
committed; a secret in it is a secret in git history.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Heroku
|
|
95
|
+
|
|
96
|
+
Check you are authenticated before relying on any of it: `heroku auth:whoami`.
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
# git-based deploy (build runs on Heroku)
|
|
100
|
+
git push heroku <local-branch>:main
|
|
101
|
+
|
|
102
|
+
# container-based deploy
|
|
103
|
+
heroku container:push web -a <app>
|
|
104
|
+
heroku container:release web -a <app>
|
|
105
|
+
|
|
106
|
+
# migrations / release-phase, when not automated in the Procfile
|
|
107
|
+
heroku run "<migrate command>" -a <app>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Verify:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
heroku ps -a <app> # dyno state — this is where a crash loop shows
|
|
114
|
+
heroku logs --tail -a <app> # boot and runtime errors
|
|
115
|
+
heroku releases -a <app> # confirm the new release landed; `heroku rollback` reverts
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## DigitalOcean App Platform
|
|
119
|
+
|
|
120
|
+
`doctl account get` first.
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# an app connected to a branch deploys on the push from stage 7; to force one:
|
|
124
|
+
doctl apps create-deployment <app-id> --wait
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Verify:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
doctl apps get <app-id> # active deployment and its phase
|
|
131
|
+
doctl apps logs <app-id> --follow # runtime
|
|
132
|
+
doctl apps logs <app-id> --type build # build — a different stream, and usually the answer
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Droplet / bare server over SSH
|
|
136
|
+
|
|
137
|
+
Shape only — the runbook's exact steps win, because this is the target where
|
|
138
|
+
"typical" is least likely to be true.
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
ssh <user>@<host> '
|
|
142
|
+
cd <app-dir> &&
|
|
143
|
+
git pull &&
|
|
144
|
+
<build command> &&
|
|
145
|
+
<restart command> # systemctl restart <service> | docker compose up -d
|
|
146
|
+
'
|
|
147
|
+
ssh <user>@<host> 'systemctl status <service> --no-pager'
|
|
148
|
+
ssh <user>@<host> 'journalctl -u <service> -n 100 --no-pager'
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Deploy that happens in CI
|
|
152
|
+
|
|
153
|
+
When the push itself is the deploy, stage 8 verifies the run, not the host:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
gh run list --branch <branch> --limit 5
|
|
157
|
+
gh run watch <run-id>
|
|
158
|
+
gh run view <run-id>
|
|
159
|
+
gh run view <run-id> --log-failed # only the failed step's log
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
**Confirm the deploy job, not just the build job.** A green build with a skipped
|
|
163
|
+
or failed deploy is the most common way a run reports success while nothing
|
|
164
|
+
shipped — and it is exactly what the stage-8 gate is for.
|
|
165
|
+
|
|
166
|
+
## Other platforms, quick verbs
|
|
167
|
+
|
|
168
|
+
| Platform | Deploy | Verify |
|
|
169
|
+
|---|---|---|
|
|
170
|
+
| Fly.io | `fly deploy` | `fly status`, `fly logs` |
|
|
171
|
+
| Vercel | `vercel --prod`, or CI on push | `vercel ls`, the deployment URL |
|
|
172
|
+
| Cloudflare Workers/Pages | `wrangler deploy` | `wrangler tail` |
|
|
173
|
+
|
|
174
|
+
## The verification trio
|
|
175
|
+
|
|
176
|
+
Whatever the platform, stage 8's gate needs the same three, and all three:
|
|
177
|
+
|
|
178
|
+
1. **Process/deployment state** — is the new version the running version
|
|
179
|
+
2. **Runtime logs** — clean boot, no error spike
|
|
180
|
+
3. **A health-check request** — from outside, against the live URL
|
|
181
|
+
|
|
182
|
+
One or two of the three is where "deployed successfully" gets said about a
|
|
183
|
+
service that is crash-looping. If any of the three cannot be obtained, that is
|
|
184
|
+
the honest degradation report the gate asks for — not a reason to call it green.
|
|
@@ -142,6 +142,7 @@ explicit "stop and ask me here":
|
|
|
142
142
|
| run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
|
|
143
143
|
| run-wide Pacing | the **run mode** ([`continuity.md`](continuity.md)): does the run advance item-by-item with no check-in between items, and on what interval? Read `pipeline.json` → `run.loop` first — a recorded mode is the answer and is not re-asked. **Absent, it is off**: recommend it, take the answer, record it. It never collapses a `manual` gate or an outward act, so this row buys pacing, not authorization |
|
|
144
144
|
| 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki, **the code graph** ([`knowledge-graph.md`](knowledge-graph.md): built / installed-not-built / absent) — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
|
|
145
|
+
| 0 Source | for a repository with an upstream — **is this checkout the one that ships**. `git rev-list --count HEAD..@{u}`, printed, before the first edit. Behind means stop and pull: an edit on a stale copy deletes newer work by fast-forward, and nothing complains (`learned.md` rule 17) | the count, stated |
|
|
145
146
|
| 0 Work-list | which register holds task **state** — a roadmap, a board, a backlog, a tracker — and the **command that reads it**. Recorded once; the harvest and every loop iteration re-run it, and a closing report that names what is left cites it. No register → record the row empty, and the rule costs nothing ([`knowledge-sources.md`](knowledge-sources.md) → *Carried-in claims*) |
|
|
146
147
|
| 0 Setup audit | doc map absent or stale: run the entry audit over the existing documentation before building on it ([`setup.md`](setup.md))? Asked once; a refusal is recorded and never re-asked |
|
|
147
148
|
| run-wide Escalation | cost of being wrong: decide alone while it stays inside the repository and reversible; escalate price, legal posture, promise, money, reputation, irreversible outward acts. Project exceptions? |
|
|
@@ -17,6 +17,7 @@ that goes stale when the answer changes.
|
|
|
17
17
|
- The knowledge wiki — recommended
|
|
18
18
|
- How to harvest — retrieval, not reading
|
|
19
19
|
- Record it — the source ledger
|
|
20
|
+
- The source is not the copy you have
|
|
20
21
|
- Carried-in claims — measured or recalled
|
|
21
22
|
- Phase 2 — validate the answers against the harvest
|
|
22
23
|
- Close the loop — stage 9 updates what stage 0 read
|
|
@@ -171,6 +172,27 @@ source nobody will update.
|
|
|
171
172
|
**"No sources found" is a valid, recorded outcome.** Write the row. An empty ledger
|
|
172
173
|
tells the next run that the search happened and came back empty — silence doesn't.
|
|
173
174
|
|
|
175
|
+
## The source is not the copy you have
|
|
176
|
+
|
|
177
|
+
`learned.md` rule 17. The harvest reads the project's own files, and one property of them is
|
|
178
|
+
invisible to reading: **whether this checkout is the one that ships.** A working copy two commits
|
|
179
|
+
behind its upstream looks exactly like a current one — clean tree, no conflict, `git status` says
|
|
180
|
+
nothing is wrong — and an edit on top of it deletes the newer work by fast-forward rather than by
|
|
181
|
+
collision.
|
|
182
|
+
|
|
183
|
+
Before the first edit, in any repository that has an upstream:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
git fetch -q && git rev-list --count HEAD..@{u} # 0, or stop and pull
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Print the number. `0` is the measurement; the absence of a complaint is not.
|
|
190
|
+
|
|
191
|
+
This matters most where it is least suspected — a skill, a plugin, a fork, a vendored library —
|
|
192
|
+
because those are the repositories a machine keeps **twice**, once to publish from and once to run,
|
|
193
|
+
and the one a person opens is chosen by a path in some documentation rather than by which is
|
|
194
|
+
current.
|
|
195
|
+
|
|
174
196
|
## Carried-in claims — measured or recalled
|
|
175
197
|
|
|
176
198
|
The harvest exists because *the operator misremembers*. This section exists because
|
|
@@ -41,6 +41,7 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
|
|
|
41
41
|
| 14 | **A document may not send a reader to something absent** | any instruction naming a command, file or install | resolve it | the gate fails when the target does not exist |
|
|
42
42
|
| 15 | **Identity before coordination** | any lease, lock, claim or run id | ask what two instances with the same identity would do, and make the tool answer it | two instances demonstrably get two identities |
|
|
43
43
|
| 16 | **A carried-in claim is a recollection** | any run resuming from a summary, a handoff or a compacted context | re-derive the claim from its source before acting on it or reporting it | every state claim the run makes is marked `measured` with the command behind it, or it is not made |
|
|
44
|
+
| 17 | **The copy you are about to edit may not be the copy that ships** | any run editing a repository that has an upstream — a skill, a plugin, a vendored library, a fork | `git rev-list --count HEAD..@{u}` **before the first edit**; non-zero means stop and pull | the run states the count it measured, or it has not started |
|
|
44
45
|
|
|
45
46
|
---
|
|
46
47
|
|
|
@@ -124,6 +125,8 @@ provenance on the way. Eleven iterations later a single command over the registe
|
|
|
124
125
|
rows out of 99**, not the handful being worked from. Nothing had failed, because nothing compares a
|
|
125
126
|
run's belief about the work-list against the register; the claim only ever appeared in prose.
|
|
126
127
|
|
|
128
|
+
**17 · The stale source.** A machine keeps its skills in two places: the working copy it publishes from and the installed plugin it runs. On 2026-08-07 the working copy was **two commits behind its own origin** — `v1.16.2` against `v1.18.0` — and the newer commits carried rule 16 itself. The repository was clean, nothing had diverged, and `git status` said so; the copy was simply never pulled. An edit made there would have landed on top of 1.16.2, and the release would have **silently deleted rule 16 and everything else in two versions** — not as a conflict, which git would have shown, but as a fast-forward over work that was already published. The project's own instruction names that directory as the source, so the person doing it would have been following the documentation. Nothing in the pipeline asked the one question that separates a source from a copy of one, and the check is a single command.
|
|
129
|
+
|
|
127
130
|
The same class had already bitten that project twice from the other side, and its roadmap names the
|
|
128
131
|
property exactly: seven rows read `blocked` on producers the dependency board recorded as delivered,
|
|
129
132
|
and *"no gate can catch it because it breaks nothing — it only removes work from consideration"*;
|
|
@@ -46,6 +46,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
|
|
|
46
46
|
| The knowledge harvest and its source ledger | `references/knowledge-sources.md` |
|
|
47
47
|
| The documentation system, the Doc Loop, supersede semantics | `references/documentation.md` |
|
|
48
48
|
| Gate types, the enforcement ladder, degrees of freedom, probing | `references/gates.md` |
|
|
49
|
+
| Deploy runbook template, per-platform verbs, the verification trio | `references/deploy-targets.md` |
|
|
49
50
|
| The Claude Code hook contract | `references/hooks.md` |
|
|
50
51
|
| First run in a project: greenfield and brownfield | `references/adoption.md` |
|
|
51
52
|
| The entry audit and what it inspects | `references/setup.md` |
|
|
@@ -339,7 +339,11 @@ never that the work was skipped quietly.
|
|
|
339
339
|
the **super-ux linter** (`python3 docs/ux/lint.py` / `/ux-lint`) is part of lint —
|
|
340
340
|
it must pass too (no UX drift merges). Then deploy per the project's convention;
|
|
341
341
|
if the project defines release automation (`pipeline.json` → `release`, toggle
|
|
342
|
-
on), that is what "deploy" runs here.
|
|
342
|
+
on), that is what "deploy" runs here. **No runbook, or one too thin to act on?
|
|
343
|
+
Write it first** ([`deploy-targets.md`](deploy-targets.md)) — a deploy performed
|
|
344
|
+
from inference about the project is one nobody can repeat or roll back, and the
|
|
345
|
+
operator is standing at this gate anyway. That reference also carries the CLI
|
|
346
|
+
verbs per target for when the runbook names a platform you have to recall.
|
|
343
347
|
- **GATE (manual):** lint clean (host linter **and**, for UI projects, the super-ux
|
|
344
348
|
linter) **and** suite green **before** deploy, **and no REQ is still `open`** — a
|
|
345
349
|
`partial` ships only with the operator's explicit acceptance. A gap is cheapest to
|
|
@@ -353,7 +357,12 @@ never that the work was skipped quietly.
|
|
|
353
357
|
## 8 — Post-deploy
|
|
354
358
|
- **Freedom: medium** — where the logs live varies; 'clean boot or an honest degradation report' does not ([`gates.md`](gates.md) → *Axis C*).
|
|
355
359
|
- Tail deploy logs / health-check per conventions. Confirm clean boot, no error
|
|
356
|
-
spike, live subsystems healthy.
|
|
360
|
+
spike, live subsystems healthy. **All three of the verification trio, not one of
|
|
361
|
+
them** ([`deploy-targets.md`](deploy-targets.md) → *The verification trio*):
|
|
362
|
+
deployment/process state, runtime logs, and a health-check request from outside.
|
|
363
|
+
Where deploy happens in CI, verify the **deploy** job and not only the build —
|
|
364
|
+
a green build beside a skipped deploy is the commonest way a run reports success
|
|
365
|
+
while nothing shipped.
|
|
357
366
|
- **Read the CI verdict for the deploy's own commit** ([`conventions.md`](conventions.md)
|
|
358
367
|
→ *The CI verdict*): the run's conclusion quoted, the **failing step's log quoted**
|
|
359
368
|
on anything but `success`, and one of the three states stated — including **`no run
|
|
@@ -120,6 +120,7 @@ is not neutral — it is a scheduled interruption.
|
|
|
120
120
|
| run-wide | Decide autonomously vs escalate to me | … |
|
|
121
121
|
| run-wide Pacing | Run mode: item-by-item with no check-in between items, and on what interval? (the skill's `references/continuity.md`; read `pipeline.json` → `run.loop` first) | … (**absent ⇒ off**; it never collapses a manual gate or an outward act) |
|
|
122
122
|
| 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki, the code graph; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push; graph built / not built) |
|
|
123
|
+
| 0 Source | `git rev-list --count HEAD..@{u}` before the first edit, printed. Behind means stop and pull — an edit on a stale checkout deletes newer work by fast-forward and nothing complains (`learned.md` rule 17) | |
|
|
123
124
|
| 0 Work-list | Which register holds task **state**, and the command that reads it — re-run at every harvest, at every loop iteration and at the close | … (e.g. `bash scripts/board.sh`; none → record empty) |
|
|
124
125
|
| 0 Setup audit | … (yes / no — recorded either way) | doc map absent or stale: run the entry audit over the existing documentation before building on it (the skill's `references/setup.md`)? Asked once; a refusal is recorded and never re-asked |
|
|
125
126
|
| 0 Docs regime | Where settled things live (register or ADR set — one home, never both); who may write it; lease mechanism present, or is this run `ungated`? Gate command + ratchet floors; may this run raise a floor? | … |
|