@haaaiawd/skeinn 0.0.0-stage → 2.4.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/design.md ADDED
@@ -0,0 +1,230 @@
1
+ # Skeinn 2 System Design
2
+
3
+ Status: implemented core, evaluation pending independent trials.
4
+
5
+ ## Product decision
6
+
7
+ Skeinn is for the Agent, not the human. Its job is to make a normal capable Agent substantially better at
8
+ understanding a personalized project, acquiring the right professional judgment, continuing after context
9
+ loss, and completing real work. The human experience remains natural conversation.
10
+
11
+ The system therefore optimizes for four observable outcomes:
12
+
13
+ 1. The Agent can explain the intended whole rather than mirror a feature list.
14
+ 2. Consequential uncertainty becomes useful conversation instead of silent guessing or a fixed questionnaire.
15
+ 3. Consequential product, experience, system, contract, and verification decisions remain navigable as
16
+ separate documents rather than collapsing into one summary.
17
+ 4. Each relevant professional field changes decisions and produces a distinctive project stance without
18
+ being blended into an invented hybrid capability.
19
+ 5. A fresh Agent can resume the current Task from disk without inherited chat memory.
20
+
21
+ Document production, role performance, stage completion, and graph density are not success metrics.
22
+
23
+ ## Minimal closed loop
24
+
25
+ ```text
26
+ Understand → Clarify → Record → Map professional fields
27
+ ↑ ↓
28
+ └──── update whole ← Design document graph → Work Map
29
+ ↑ ↓
30
+ └── Keeper gaps ← fresh Keeper
31
+ ↓ passed
32
+ blocked/reopen ← Active Task → Evidence → next Task
33
+ ```
34
+
35
+ ### Understand and clarify
36
+
37
+ The Agent inspects the workspace when the user's request makes it relevant. It describes the emerging
38
+ result naturally and identifies the current uncertainty frontier. The frontier contains only decisions
39
+ whose answers could materially change outcome, behavior, boundary, system, risk, or completion.
40
+
41
+ The prompt constrains judgment, not question content. It requires a coherent high-value round, adaptive
42
+ grouping, first-principles re-evaluation, and a convergence condition. It does not mandate headings,
43
+ question counts, or a universal sequence.
44
+
45
+ Convergence means the Agent can explain the whole result, its boundaries, the professional capability it
46
+ needs, and how completion will be observed. Remaining unknowns must be reversible and local, explicitly
47
+ delegated to the Agent, or explicitly skipped by the human after a concrete warning.
48
+
49
+ ### Record
50
+
51
+ Markdown stores human-readable project truth. JSON stores machine state that people do not need to edit.
52
+ Important corrections do not leave contradictory truths scattered through the corpus: PROJECT.md maps the
53
+ current whole, `.skeinn/design/` owns detailed decisions, and DECISIONS.md records consequential supersession
54
+ with rationale and impact.
55
+
56
+ ### Design document graph
57
+
58
+ `PROJECT.md` is an entry point, not a compression target. Product definition, experience, independent
59
+ systems, contracts, verification, operations, and research receive separate documents when they have their
60
+ own decisions, interfaces, failure modes, or proof. Project size determines document count. This keeps a small
61
+ project small while allowing a large system to become fully legible instead of “minimal” in the anemic sense.
62
+
63
+ ### Acquire capability
64
+
65
+ Capabilities are project-scoped professional-field dossiers, not reusable expert personas or task methods.
66
+ One dossier maps to one recognizable field. UI/UX design, visual art direction, game design, psychology,
67
+ biology, security, and distributed systems remain separate when they use different evidence or judgments.
68
+ Cross-field synthesis lives in the design document whose decision it changes. A dossier contains:
69
+
70
+ - the field boundary, the decisions it changes, and the project reality grounding it;
71
+ - specialist principles, evidence, sources, conflicts, and uncertainty;
72
+ - an authored, falsifiable project stance and deliberate refusals;
73
+ - questions whose answers could change the decision;
74
+ - design and implementation consequences;
75
+ - generic failure modes and observable verification signals;
76
+ - opened sources, what each changed, conflicts, and uncertainty when research is used.
77
+
78
+ Acquisition can happen quietly. The Agent may briefly name the capability it is obtaining, but does not
79
+ turn research logistics into user workflow.
80
+
81
+ Scenario authority is explicit. `capability confirm --source human` records a confirmed scenario;
82
+ `--source agent` records a provisional, reversible selection when the human is unavailable. Context and
83
+ health checks preserve that distinction instead of allowing an Agent assumption to masquerade as user confirmation.
84
+
85
+ ### Work Map and Task
86
+
87
+ Planning uses progressive resolution. A broad initial Work Map protects whole-project coverage and may be
88
+ very long. Only the active horizon receives detailed actions. The context compiler returns counts and the
89
+ current Task rather than injecting the whole plan.
90
+
91
+ Task is the single execution contract:
92
+
93
+ ```json
94
+ {
95
+ "id": "TASK-001",
96
+ "title": "Implement restartable context",
97
+ "outcome": "A fresh Agent receives only decision-relevant context",
98
+ "done_when": ["A forced-reset transcript resumes correctly"],
99
+ "boundaries": ["The human never operates Skeinn"],
100
+ "depends_on": [],
101
+ "reads": [".skeinn/PROJECT.md", ".skeinn/design/context-system.md", ".skeinn/capabilities/human-agent-interaction.md", "fixtures/reset-case.md"],
102
+ "touches": ["cli/src/context.js"],
103
+ "implements": ".skeinn/design/context-system.md#Context selection",
104
+ "capability_hooks": [{ "node": "human-agent-interaction#C1", "at": "selecting reset context" }],
105
+ "status": "active",
106
+ "progress": {
107
+ "completed": [],
108
+ "current": "Implementing selector",
109
+ "next": "Run reset transcript"
110
+ },
111
+ "evidence": []
112
+ }
113
+ ```
114
+
115
+ There is at most one active Task. Completion requires a concrete evidence mapping for every exact `done_when`
116
+ criterion. A completed Task can be reopened with a reason when later evidence disproves it. The Task plan may change without
117
+ human approval when the change is a reversible implementation refinement inside the agreed whole; outcome,
118
+ authority, risk, or material cost changes return to the conversation.
119
+
120
+ New Tasks must make design and capability applicability explicit: use `implements` and `capability_hooks`, or
121
+ record a concrete `design_exemption` / `capability_exemption`. Task start rejects an unclassified active horizon.
122
+ Completion verifies that every declared local `touches` path exists, and `skeinn check` detects later filesystem drift.
123
+
124
+ ### One-time Keeper
125
+
126
+ Keeper is not a recurring role. It is a single isolation test at the transition from shaping to material
127
+ execution. A fresh Agent receives no prior conversation, runs `skeinn context --keeper`, explains the whole,
128
+ selects a first Task, navigates its design documents and professional capabilities, and identifies concrete evidence. Every attempt binds a unique
129
+ fresh-thread `run_id` to the digest frozen by `project ready`. A passing record also carries an explicit independent
130
+ review attestation (`review.mode`, reviewer identity, and isolation evidence); known self-review cannot be recorded as
131
+ passed. This is an auditable host assertion, not cryptographic identity proof. It may return gaps; summary, evidence and exact gaps
132
+ are injected into the main Agent's next context. Revision must change project truth or Task definitions before a
133
+ new digest and fresh Keeper run are allowed. Once passed, normal Task evidence replaces further Keeper ceremony.
134
+
135
+ If the host lacks subagents, Skeinn supplies a one-sentence prompt for a new window. Explicit skip is possible
136
+ but must preserve a concrete reason and reduced confidence.
137
+
138
+ ## Runtime structure
139
+
140
+ ```text
141
+ cli/bin/skeinn.js small command router
142
+ cli/src/store.js state, design, capability, Task, Keeper, context and eval operations
143
+ cli/src/protocol.js layered Agent prompts and every human-readable template
144
+ cli/test/run-all.js end-to-end contract tests
145
+ ```
146
+
147
+ The CLI has six responsibilities:
148
+
149
+ 1. Initialize the minimal project backbone.
150
+ 2. Record structured understanding and decision history safely.
151
+ 3. Scaffold a scalable design-document graph and separate professional-field dossiers.
152
+ 4. Maintain a large Work Map and a single active Task.
153
+ 5. Compile only decision-relevant context after reset.
154
+ 6. Adapt clarification to whether a human response channel is actually available.
155
+ 7. Prepare one-time Keeper and controlled Evil Eval artifacts.
156
+
157
+ It does not orchestrate models, browse the web, generate project documents, or pretend that a CLI command
158
+ clears model memory. Those capabilities belong to the host Agent and its tools.
159
+
160
+ ## State transition
161
+
162
+ Project status is a compact orientation signal, not a phase bureaucracy:
163
+
164
+ ```text
165
+ shaping ⇄ question, design-document, and professional-capability loop
166
+ ↓
167
+ ready_for_keeper ⇄ fresh Keeper needs_revision or blocked → shaping
168
+ ↓ passed
169
+ build_ready → building ⇄ Task repair or block or reopen → complete
170
+ ```
171
+
172
+ `project ready` checks only structural prerequisites: PROJECT.md is no longer a template, at least one design
173
+ document and a Work Map exist, and no high-impact open question remains. Keeper judges semantic build-readiness. Task start requires Keeper
174
+ pass or an explicit recorded skip. An unchanged revision, duplicate Keeper run, wrong digest, or stale prepared
175
+ state is rejected. Imported Tasks start open, `task start` rejects missing or directory-level context reads and
176
+ unclassified design/capability applicability, generic updates cannot change status, and completion requires
177
+ criterion-by-criterion evidence plus existence of every declared local output.
178
+
179
+ ## Context selection
180
+
181
+ `skeinn context` always injects:
182
+
183
+ - the stable Agent protocol;
184
+ - compact state counts and open uncertainty;
185
+ - PROJECT.md, with decision history identified as on-demand context;
186
+ - the active Task, if one exists;
187
+ - the exact design, capability, source, contract, or fixture files named in that Task's `reads` list.
188
+
189
+ ### Environment adaptation and isolated state
190
+
191
+ The host supplies human-channel availability at context time. With `available` (the default), the Agent may
192
+ ask the human for consequential intent, preference, authority, or facts that only they hold. With
193
+ `unavailable`, it must not fabricate a user exchange or replace an intent/authority question with web search.
194
+ It first inspects discoverable workspace facts and permitted tools, researches only objective external facts when
195
+ the task allows it, then records a bounded assumption and chooses a safe reversible action or blocks on
196
+ unavailable authority.
197
+
198
+ `--state-dir <outside-workspace-dir>` places Skeinn's state tree in a per-run sidecar rather than the workspace.
199
+ This is for benchmark or sandbox runners whose scored workspace must remain pristine. The sidecar remains
200
+ semantically `.skeinn/` to Skeinn documents and Task references, but initialization does not edit the workspace
201
+ or add an AGENTS.md anchor. Every command in that run must receive the same state directory.
202
+
203
+ When a Task is active, context also injects a short execution protocol. It tells a reset Agent to reconcile
204
+ the Task with the current workspace and version-control state, inspect relevant tests before editing, choose
205
+ verification according to risk and the exact `done_when` claims, persist `completed/current/next` at meaningful
206
+ handoff boundaries, and close only with reproducible criterion-level evidence. It deliberately does not require
207
+ a ceremonial unit test for every kind of work or a branch, commit, or pull request for every Task. Those
208
+ delivery mechanisms remain conditional on the human request and repository workflow.
209
+
210
+ Workspace code paths in `touches` are identified but not automatically copied into context. Full decision
211
+ history is not repeatedly injected because current truth belongs in PROJECT.md and linked design documents.
212
+ `skeinn context --keeper` includes history, every design document, and every professional capability dossier
213
+ because whole-project coverage and contradiction detection are exactly what the isolated handoff tests.
214
+
215
+ ## Compatibility decision
216
+
217
+ Skeinn 2 is a major redesign. It does not silently mutate `.skeinn/v1` projects and does not preserve the old command
218
+ surface. Encountering a legacy layout produces an explicit migration boundary. Git remains the recovery path;
219
+ an automated semantic migration can be designed only after real v1 projects reveal which history is valuable.
220
+
221
+ ## Known boundaries
222
+
223
+ - External capability acquisition is represented but not automated yet; the host Agent performs research.
224
+ - Markdown is intentionally human-editable. Skeinn validates file existence and structured state, not prose truth.
225
+ - Keeper independence depends on the host creating a fresh thread or window. Skeinn requires and records the
226
+ host's independent-review attestation but cannot cryptographically prove Agent identity.
227
+ - Evil Eval scaffolding controls experiment design but does not itself launch model runs.
228
+ - A one-time Keeper verifies build-readiness, not the eventual quality of every implementation Task.
229
+
230
+ These are honest capability boundaries, not deferred stages disguised as completion.
@@ -0,0 +1,139 @@
1
+ # Skeinn Prompt and Message Catalog
2
+
3
+ Skeinn's prompts are cognitive interfaces, not a collection of role-playing personas. The exact live
4
+ inventory is emitted by:
5
+
6
+ ```bash
7
+ skeinn prompts
8
+ ```
9
+
10
+ The command is the auditable source of truth. It returns the complete text, placeholders, and composition
11
+ order as JSON, so documentation cannot quietly describe a different prompt from the one Agents receive.
12
+
13
+ ## Instruction layers
14
+
15
+ | Layer | Message | Injected when | Purpose |
16
+ |---|---|---|---|
17
+ | Stable core | `layers.stable_core` | Every `skeinn context` | Durable collaboration judgment: user ownership, evidence classes, question threshold, corrections, reversible delegation |
18
+ | Environment adaptation | `layers.environment_adaptation_available` or `layers.environment_adaptation_unavailable` | Every `skeinn context` | States whether a human can answer; routes uncertainty through inspection, permitted factual research, clarification, bounded assumption, or block |
19
+ | Runtime adaptation | `layers.runtime_protocol` | Every `skeinn context` | Skeinn-specific disk model, document graph, capability boundaries, Work Map, and three production loops |
20
+ | Project state | `layers.project_state` | Every `skeinn context` | Dynamic status, uncertainty, assumptions, document/capability inventory, Task counts, blocked Tasks with reasons and recovery conditions, and Keeper feedback |
21
+ | Project state after failure | `layers.project_state_after_keeper_failure` | Keeper `needs_revision`/`blocked` | Prior finding text, the repair expectation, and the `skeinn project ready` → fresh-Keeper retry contract |
22
+ | Keeper review of prior failure | `layers.keeper_review_of_prior_failure` | `--keeper` after a failed attempt | The exact prior findings the fresh Keeper must re-verify before passing |
23
+ | Execution protocol | `layers.execution_protocol` | Active Task or `--task` | Recovery, workspace inspection, risk-based testing, progress persistence, exact proof, and delivery boundaries |
24
+ | Current task | `layers.current_task` | Active Task or `--task` | Exact Task JSON followed by the exact contents of every path in `reads` |
25
+ | On-demand map | `layers.on_demand_map` | Every `skeinn context` | Pointers to decision history, design documents, capability dossiers, and STRUCTURE.md for lazy loading |
26
+ | Keeper context | `layers.keeper_context` | `--keeper` | Full decision history, work-map summary, and every design and capability document for whole-corpus audit |
27
+
28
+ This separation is deliberate. Project-specific expertise does not inflate the stable prompt; it lives in
29
+ field dossiers. One-off Task instructions do not become global doctrine. Host permissions and tools are not
30
+ claimed by prompt text.
31
+
32
+ When the human channel is unavailable, the environment message explicitly forbids fabricated user interaction and
33
+ forbids treating web research as a substitute for user intent, preference, or authority. It preserves factual
34
+ research when the task and host actually permit it, then requires a reversible assumption or block for what cannot
35
+ be learned.
36
+
37
+ ## Workspace and document messages
38
+
39
+ `workspace_anchor` is the short block added to `AGENTS.md`. It tells an entering or reset Agent to run
40
+ `skeinn context`, rerun it before editing after an interruption, persist state at meaningful boundaries rather
41
+ than before every tool call, and keep CLI operation invisible to the human. The anchor is durable-only:
42
+ `skeinn init` never rewrites existing `AGENTS.md` content, and current mechanics always reach the Agent through
43
+ `skeinn context` output rather than through the anchor text.
44
+
45
+ `templates.project_index` creates `.skeinn/PROJECT.md` as a concise whole and document map. It explicitly
46
+ prevents a large project's systems from being compressed into one file.
47
+
48
+ `templates.design_documents` contains all seven live design templates:
49
+
50
+ 1. `product` — outcome, users, problem, product principles, scope, end-to-end behavior, success and failure.
51
+ 2. `experience` — journey, information architecture, states, content, visual direction, accessibility, recovery, usability proof.
52
+ 3. `system` — responsibilities, boundaries, control flow, data, interfaces, dependencies, failure, implementation, verification.
53
+ 4. `contract` — consumers, schemas or commands, invariants, permissions, errors, compatibility, fixtures, contract tests.
54
+ 5. `verification` — claims, environments, fixtures, acceptance matrix, commands, negative tests, blind spots.
55
+ 6. `operations` — authority, procedures, commands, safety, failure recovery, evidence and audit trail.
56
+ 7. `research` — decision, evidence, method, sources, findings, conflicts, consequences and follow-up proof.
57
+
58
+ These are possible document kinds, not a fixed seven-file checklist. The Agent creates as many actual
59
+ documents as the project's independent decision surfaces require.
60
+
61
+ `templates.professional_capability` is the only capability template. It enforces one recognizable field per
62
+ file, a project-specific diagnosis and stance, opened evidence, rejected generic defaults, concrete design and
63
+ verification consequences, failure modes, and links to adjacent fields without merging them.
64
+
65
+ `templates.decision_history` is the preamble for consequential superseding decisions. Current truth stays in
66
+ the project map and linked design documents.
67
+
68
+ ## Keeper message
69
+
70
+ `keeper` is the exact independent handoff prompt. It binds a unique fresh-Agent `run_id` to a frozen
71
+ `prepared_digest`, asks the Keeper to navigate the whole corpus and attempt the first Task, and defines three
72
+ verdicts:
73
+
74
+ - `passed`: a fresh Agent can responsibly begin.
75
+ - `needs_revision`: concrete disk-truth gaps can be repaired.
76
+ - `blocked`: progress needs unavailable authority or external state.
77
+
78
+ A `passed` verdict must carry independent review provenance (`review.mode: "independent"` plus a
79
+ `reviewer_id` and evidence that a separate Agent ran the review). A self-review or an unattested pass is
80
+ rejected at record time; a legacy unattested pass blocks `task start` and is an error in `skeinn check` until
81
+ replaced by a fresh review or an explicit `skeinn keeper skip --reason`.
82
+
83
+ Findings are cumulative across attempts: a pass must carry `closure_results` with evidence for every gap
84
+ still open from earlier rounds, not only the latest attempt's. A changed project digest proves that
85
+ something changed — never that findings were resolved. There is no auto-pass.
86
+
87
+ A failed result is injected into the next project-state message. A retry requires changed project truth, a
88
+ new digest, and another fresh Keeper. `skeinn review --help` describes the staging steps for opening that
89
+ fresh Agent without inherited conversation.
90
+
91
+ ## Evil Eval messages
92
+
93
+ `evaluation.baseline_condition` gives a normal capable Agent the identical brief and ordinary tools without
94
+ Skeinn. It does not weaken the baseline or prohibit normal planning.
95
+
96
+ `evaluation.skeinn_condition` gives the same brief, model class, tools, workspace facts, and budget, adding only
97
+ Skeinn continuity infrastructure and no extra authority.
98
+
99
+ `evaluation.unattended_baseline_condition` and `evaluation.unattended_skeinn_condition` are the same two
100
+ conditions when no user response channel exists. The environment fact is equal in both arms; only the Skeinn arm
101
+ uses `skeinn context --human-channel unavailable`.
102
+
103
+ `evaluation.blind_judge` scores anonymized output on intent fidelity, question value, whole coverage,
104
+ professional depth, buildability, reset continuity, implementation evidence, human burden, and cost. It
105
+ penalizes ceremony and runs an order swap.
106
+
107
+ ## Composition messages
108
+
109
+ `composition.normal_resume`, `composition.active_task`, and `composition.keeper_handoff` list the exact block
110
+ order. Keeper receives every design and capability document; a normal active Task receives only its declared
111
+ reads. This difference is intentional: Keeper audits whole-project coverage, while delivery protects context
112
+ focus.
113
+
114
+ The active Task composition adds `execution_protocol` between the recovered project whole and the exact Task.
115
+ It requires inspection of current workspace/version-control reality, risk-appropriate tests, restartable
116
+ progress, and criterion-level proof. It does not force a unit test for non-code claims or a branch/PR for every
117
+ Task; those are selected when the behavior, human request, or repository workflow makes them meaningful.
118
+
119
+ ## CLI operational messages
120
+
121
+ `skeinn --help` is the complete command-oriented message surface. `skeinn review` and `skeinn review --help` are
122
+ the read-only entry points an Agent uses to stage an independent Keeper handoff; `skeinn keeper --help` covers
123
+ `keeper prompt`, `keeper record`, and `keeper skip`. JSON command results report state and the next
124
+ host action. Validation errors are contract enforcement rather than cognitive prompts; they reject unsafe
125
+ references, template-only readiness, missing design documents, open high-impact uncertainty, unchanged Keeper
126
+ retries, stale digests, duplicate run identities, Task dependency violations, missing or directory-level Task
127
+ reads, Task references to nonexistent design sections or capability nodes, status bypasses, completion
128
+ without evidence for every done condition, silent rewriting of a done Task, and reasonless reopening of a
129
+ disproven completion or unmet block.
130
+
131
+ Warning channels are closable rather than permanent: a decision-affected done Task warns only until it is
132
+ reopened and re-completed after the decision, deliverable coverage distinguishes planned from delivered, and
133
+ blocked Tasks surface their recovery conditions in `skeinn context` until reopened with a concrete reason.
134
+
135
+ The short human fallback when the host cannot create a Keeper Agent remains:
136
+
137
+ ```text
138
+ Please open a new window in this project, run skeinn keeper prompt, and follow it.
139
+ ```
@@ -0,0 +1,53 @@
1
+ # Skeinn release checklist
2
+
3
+ This checklist stops a documentation-complete release from becoming a runtime-incomplete release.
4
+
5
+ ## 1. Confirm the release surface
6
+
7
+ ```bash
8
+ node cli/bin/skeinn.js --version
9
+ node cli/bin/skeinn.js --help
10
+ node cli/bin/skeinn.js prompts
11
+ npm test
12
+ npm pack --dry-run
13
+ ```
14
+
15
+ Confirm that the package contains the CLI runtime, English and Chinese READMEs, design, prompt catalog, UX flow, Evil Eval
16
+ protocol, changelog, license, contribution guide, and security policy. Check that it does not contain pilot
17
+ workspaces, eval artifacts, temporary browser profiles, or local project state.
18
+
19
+ ## 2. Confirm metadata and registry state
20
+
21
+ ```bash
22
+ npm whoami
23
+ npm view @haaaiawd/skeinn version
24
+ git status --short
25
+ git diff --check
26
+ ```
27
+
28
+ The version in `package.json`, `CHANGELOG.md`, and `skeinn --version` must agree. The new version must not
29
+ already exist in the registry.
30
+
31
+ ## 3. Publish deliberately
32
+
33
+ ```bash
34
+ git tag v2.0.1
35
+ git push origin HEAD
36
+ git push origin v2.0.1
37
+ npm publish --access public
38
+ ```
39
+
40
+ Run these commands only after reviewing the final diff and confirming the authenticated GitHub remote and
41
+ npm identity. Tags and published npm versions are externally visible and should not be used as test steps.
42
+
43
+ ## 4. Verify from the outside
44
+
45
+ In a clean temporary directory:
46
+
47
+ ```bash
48
+ npm view @haaaiawd/skeinn version
49
+ npx @haaaiawd/skeinn@2.0.1 --version
50
+ ```
51
+
52
+ Then open the GitHub README and npm package page to confirm the SVG header, diagrams, links, and changelog
53
+ render correctly. Record any unverified platform boundary instead of silently declaring it passed.
@@ -0,0 +1,188 @@
1
+ # Skeinn 2 Complete UX and Loop Specification
2
+
3
+ ## Experience promise
4
+
5
+ The human experiences one capable Agent who understands, asks, decides, builds, and recovers. They do not experience
6
+ framework stages, role handoffs, status commands, or document maintenance. Skeinn is the Agent's backstage continuity
7
+ system.
8
+
9
+ The system has three nested production loops and one external evaluation loop:
10
+
11
+ 1. Understanding loop — converge on the whole, its design-document graph, and the professional fields it needs.
12
+ 2. Readiness loop — let a fresh Keeper expose missing context and feed gaps back into understanding.
13
+ 3. Delivery loop — execute one restartable Task, test, repair or reflow, attach evidence, and continue.
14
+ 4. Evil Eval — compare the same Agent with no Skeinn against the Agent using Skeinn under equal conditions.
15
+
16
+ ## Surfaces and responsibilities
17
+
18
+ | Surface | Human visible | Responsibility |
19
+ |---|---:|---|
20
+ | Natural conversation | Yes | Desired result, meaningful questions, delegated decisions, risk authority, progress and delivery |
21
+ | Workspace and product artifacts | When useful | The real code, files, commands, reports, or operational result |
22
+ | PROJECT.md, design docs, capability dossiers | Optional | Human-editable whole, detailed system decisions, and separate professional judgments |
23
+ | `skeinn context` and structured state | No | Agent continuity after compression or a new session |
24
+ | Work Map and active Task | Normally no | Broad coverage, current outcome, boundaries, relevant context, progress and evidence |
25
+ | Keeper prompt and attempts | Only if a new window is required | One readiness handoff, with revision loops before execution |
26
+ | Evil Eval harness | No during normal work | Controlled evidence about whether Skeinn itself helps |
27
+
28
+ ## 0. Resume or receive a request
29
+
30
+ The Agent runs `skeinn context` when Skeinn exists. It then interprets the current request normally. Existing workspace
31
+ inspection is conditional: inspect only when the request depends on the existing project, not because Skeinn demands a scan.
32
+
33
+ Human UX: nothing framework-specific appears.
34
+
35
+ ## 1. Form the emerging whole
36
+
37
+ The Agent explains what it currently believes the finished result should be. This is conversational, not a mandatory
38
+ template recital. It is most useful initially, after a consequential correction, and before material execution.
39
+
40
+ The Agent identifies the current uncertainty frontier: decisions whose answers could materially change outcome,
41
+ experience, boundaries, architecture, risk, cost, or proof of completion.
42
+
43
+ ## 2. Ask one dense, adaptive round
44
+
45
+ The Agent asks all currently visible high-value questions in a coherent round. It may group by a natural decision cluster,
46
+ but it does not follow a fixed domain list or question count.
47
+
48
+ It does not ask facts reliably discoverable from tools, professional decisions it can responsibly make, speculative future
49
+ details that do not affect the current whole, or framework questions whose only purpose is filling a schema.
50
+
51
+ | Human response | Agent behavior |
52
+ |---|---|
53
+ | Direct answer | Record confirmed fact and update current truth |
54
+ | Correction | Update PROJECT.md and affected design docs; append a superseding decision with impact |
55
+ | `You decide` | Make the best reversible Agent decision, explain the important tradeoff, and record it |
56
+ | `I don't know` | Research or decide when safe; ask again only if the human owns the missing preference or authority |
57
+ | `Skip questions and continue` | Name the concrete quality or risk loss, record skipped uncertainty, then proceed |
58
+
59
+ After every answer round, the Agent re-evaluates the whole. If material uncertainty remains, it loops to another adaptive
60
+ round. If only reversible local uncertainty remains, it continues.
61
+
62
+ ### When no human response channel exists
63
+
64
+ Some unattended, sandboxed, or benchmark runs have no human to answer. The host invokes
65
+ `skeinn context --human-channel unavailable`; this does not create a synthetic user. The Agent first inspects
66
+ discoverable workspace facts and permitted tools, researches only objective external facts when the task permits it,
67
+ and never treats web research as a substitute for user intent, preference, or authority. It records a bounded
68
+ assumption and selects a safe reversible action, or blocks if the missing answer controls irreversible, high-risk,
69
+ or materially costly work.
70
+
71
+ ## 3. Build project-specific capability
72
+
73
+ The Agent maps which established professional fields could change questions, design, implementation, risk, or verification.
74
+ It creates one dossier per recognizable field. UI/UX design, visual art direction, game design, psychology, biology, security,
75
+ and other fields remain separate when their evidence or judgments differ. Task techniques such as triage, ranking, parsing,
76
+ or caching are design mechanisms, not replacements for the capability map. Cross-field synthesis belongs in the affected
77
+ design document.
78
+
79
+ A useful dossier changes action. It contains its field boundary, specialist evidence, a falsifiable project stance,
80
+ deliberate refusals, decision-changing questions, implementation consequences, failure modes, verification signals, sources,
81
+ and tensions. Generic summaries and expert roleplay fail this step.
82
+
83
+ Research can be quiet. A natural update is enough: `I need to strengthen the privacy, cognitive-load and information-architecture judgment; I will bring the consequences back into the design.`
84
+
85
+ ## 4. Shape the project corpus and Work Map
86
+
87
+ PROJECT.md is the concise entry point and map. DECISIONS.md holds only consequential supersession. The actual product,
88
+ experience, independent systems, contracts, verification, research, and operations decisions live under `.skeinn/design/`.
89
+ A document is split when its subject has independent responsibilities, interfaces, failure modes, or proof. Document count
90
+ therefore scales with project complexity: neither a fixed checklist nor an artificial one-file minimum.
91
+
92
+ The Agent creates a broad initial Work Map early. It may be thousands of lines because it remains on disk. Only the active
93
+ horizon receives detailed actions. Every Task states outcome, done conditions, boundaries, dependencies, relevant reads,
94
+ affected paths, progress, next action, and evidence.
95
+
96
+ ## 5. Transition to readiness
97
+
98
+ Before engineering or other material execution, the Agent tells the human what is about to happen and which important
99
+ assumptions remain. Ordinary reversible work does not require another approval. Irreversible, high-risk, or materially costly
100
+ action requires explicit authority.
101
+
102
+ `skeinn project ready` verifies structural readiness and freezes a digest of the project map, design documents, capability dossiers, and Task
103
+ definitions for the next Keeper attempt.
104
+
105
+ ## 6. Keeper readiness loop
106
+
107
+ A fresh Agent thread runs `skeinn keeper prompt` and `skeinn context --keeper`. It receives no prior conversation. Each attempt has
108
+ a unique `run_id`, attempt number, and prepared digest.
109
+
110
+ Keeper tests whether it can explain the whole, navigate every necessary design system, locate distinct professional capabilities, select the correct first Task, find all context,
111
+ name the first concrete action, and reproduce completion evidence.
112
+
113
+ ### Passed
114
+
115
+ A pass requires independent review provenance (`review.mode: "independent"`, reviewer identity, evidence) and
116
+ `closure_results` covering every finding still open across all earlier attempts. A changed digest alone never
117
+ closes a finding. When no separate Agent is available, the maintainer records an explicit
118
+ `skeinn keeper skip --reason` instead of simulating a pass.
119
+
120
+ State becomes `build_ready`. Keeper leaves the normal workflow permanently; Task evidence now carries delivery quality.
121
+
122
+ ### Needs revision or blocked
123
+
124
+ The result records summary, evidence, and exact gaps. State returns to `shaping`. The next `skeinn context` injects this feedback
125
+ as the highest-priority uncertainty.
126
+
127
+ The main Agent decides where the gap belongs, repairs everything it can, asks the human only for decisions they genuinely own,
128
+ changes the relevant disk truth, runs `skeinn project ready` again, and opens a new Keeper run with a new run_id and digest.
129
+
130
+ Skeinn refuses an unchanged revision, a duplicate run_id, a result for the wrong digest, and a result written before ready.
131
+
132
+ If the host has no subagents, the human sees one short request: `Please open a new window in this project, run skeinn keeper prompt, and follow it.`
133
+
134
+ ## 7. Delivery loop
135
+
136
+ The Agent selects `skeinn task next`, starts it, and runs `skeinn context`. Context contains the current whole, current Task, and the
137
+ exact design, capability, source, contract, and fixture files in `reads`—not the full Work Map or history.
138
+
139
+ - A local failure keeps the Task active. Update progress and evidence, repair, and test again.
140
+ - A missing permission, dependency, or upper-level contradiction uses `task block` with a reason and recovery conditions. `skeinn context` surfaces each blocked Task with its reason and recovery conditions until it is resolved.
141
+ - After the condition is repaired, use `task reopen --reason` describing how the recovery conditions were met, then start it again. A prior `done` may also be reopened with a concrete reason when its evidence is disproven; a done Task cannot be silently rewritten by `task update`.
142
+ - `task done` requires a check quoting every exact `done_when` criterion and mapping it to concrete evidence.
143
+ - Generic update cannot modify status, and imported Tasks must begin open.
144
+
145
+ When a Task is done, the Agent chooses the next dependency-ready Task. When every Task is done, project status becomes complete
146
+ and the Agent delivers the real result, evidence, remaining tradeoffs, and any user-owned follow-up.
147
+
148
+ ## 8. Mid-build change
149
+
150
+ New user information is first evaluated for impact. A local reversible implementation detail updates the active Task. A change
151
+ to the desired whole updates PROJECT.md and affected design documents, records a superseding decision, revises affected Task definitions, and blocks or reopens
152
+ the active Task as needed. The one-time Keeper does not return after initial build-readiness; implementation evidence and explicit
153
+ human authority govern later changes.
154
+
155
+ ## Recovery matrix
156
+
157
+ | Failure | Recovery |
158
+ |---|---|
159
+ | Context compressed | `skeinn context` compiles current truth and active horizon |
160
+ | User contradicts earlier answer | Update PROJECT.md and affected design docs; append superseding decision; revise affected Tasks |
161
+ | Important answer unavailable | Agent decides reversibly or records open or skipped uncertainty |
162
+ | Capability is generic or hybrid | Split into recognizable fields; move synthesis to design docs; add stance, consequences and proof |
163
+ | Keeper cannot start | Feedback returns to shaping; change disk truth; new digest and fresh run |
164
+ | Project changes after ready | Old Keeper result rejected as stale |
165
+ | Same Keeper identity reused | Duplicate run_id rejected |
166
+ | Local implementation test fails | Keep Task active, record observation, repair and repeat |
167
+ | Dependency or authority missing | Block Task with recovery conditions, then reopen |
168
+ | Attempt to mark done without evidence | CLI rejects it |
169
+ | Evidence disproves an earlier done state | Reopen with a reason, then repair, re-verify, or block |
170
+ | Host cannot spawn Keeper | Ask the human to open a new window with one short prompt |
171
+
172
+ ## Flow diagrams
173
+
174
+ - [Production loops](loom-production-loop.drawio) — editable Draw.io source; [SVG](loom-production-loop.svg).
175
+ - [Evil Eval](loom-eval-loop.drawio) — editable Draw.io source; [SVG](loom-eval-loop.svg).
176
+
177
+ ## Primary evaluation question
178
+
179
+ The causal baseline is a normal capable Agent with no Skeinn—not Skeinn v1. Both conditions receive the same raw brief, model,
180
+ tools, workspace, human-channel availability, user oracle when one exists, budget, and reset schedule. Skeinn v1 may be added as a secondary regression condition, but it does
181
+ not answer whether the framework itself creates value over no framework.
182
+
183
+ For an unattended external benchmark, both conditions receive `human_channel: unavailable` and no fabricated user
184
+ oracle. A fresh Skeinn sidecar sits outside the scored workspace and is passed through `--state-dir` on every Skeinn
185
+ command, so framework state cannot alter task files or hidden-test behavior.
186
+
187
+ The anonymization harness must preserve runnable relative layout, record a file/digest manifest, and rerun each condition's
188
+ declared tests and smoke command before judging. Packet-construction failures are eval failures, never evidence against a run.