tenuto 0.9.0__tar.gz

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.
tenuto-0.9.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kelly Asay / AOmniMedia
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ include docs/*.md
tenuto-0.9.0/PKG-INFO ADDED
@@ -0,0 +1,137 @@
1
+ Metadata-Version: 2.4
2
+ Name: tenuto
3
+ Version: 0.9.0
4
+ Summary: Developmental Agent Continuity and Project Continuity for long-horizon AI coding sessions — zero dependencies, two-file SQLite.
5
+ Author-email: Kelly Asay <kellyasay@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/aomnimedia/tenuto
8
+ Project-URL: Repository, https://github.com/aomnimedia/tenuto
9
+ Project-URL: Issues, https://github.com/aomnimedia/tenuto/issues
10
+ Keywords: ai,agents,continuity,memory,sqlite,cli,claude-code,codex
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Dynamic: license-file
24
+
25
+ # Tenuto
26
+
27
+ **Held to its full value — Accuracy over Speed.**
28
+
29
+ Zero-dependency Python + SQLite developmental continuity for long-horizon AI coding-agent sessions (Claude Code, Codex CLI, Cursor, Antigravity, OpenClaw) — distilled from keeping a multi-layer systems engineering session coherent for **three months with near-zero drift**.
30
+
31
+ Tenuto ships two first-class CLI entry points from one tiny package:
32
+
33
+ - **`remember`** — private **Agent Developmental Continuity** (`~/.tenuto/agent.db`): working constitution, constructive durable practices, two-way collaboration proposals, checkpoints, and separation hygiene.
34
+ - **`tenuto project`** — shareable **Project Continuity** (`.tenuto/project.db`): project framing, current state, checkpoints, consequential decisions/learnings, and authoritative references.
35
+
36
+ No servers, no Docker, no vector database, no API keys, no external Python dependencies.
37
+
38
+ ---
39
+
40
+ ## Why Tenuto Exists
41
+
42
+ Long coding-agent sessions usually fail for three avoidable reasons:
43
+
44
+ 1. **Punitive memory bloat:** Stuffing *"NEVER DO X"* error ledgers into `CLAUDE.md` / `MEMORY.md` burns tokens and triggers defensive or compliance-faking loops. Tenuto consolidates lessons constructively (`practice + application_context + success_signal`).
45
+ 2. **Model vs. Agent confusion:** The stateless *Model* pushes for fast momentum; the *Agent* owns the tools, constitution, and continuity that keep the Model aligned.
46
+ 3. **Agent-vs-Project bleed:** Agents lazily dump project task trivia into personal agent memory. Separating private `~/.tenuto/agent.db` from repo-local `.tenuto/project.db` enforces the boundary at the filesystem level.
47
+
48
+ > **Read the full craft:** [The Tenuto Operating Model (`docs/OPERATING-MODEL.md`)](https://github.com/aomnimedia/tenuto/blob/main/docs/OPERATING-MODEL.md) — covers *Model vs. Agent*, *Friction Mechanics*, spotting the *Bookkeeping Drift Tell*, the *2-Error Safe-Space Recovery Protocol*, *Day-1 Onboarding Prompts*, and verified Claude Code / Codex integrations.
49
+
50
+ ---
51
+
52
+ ## 30-Second Quickstart
53
+
54
+ ```bash
55
+ pip install tenuto
56
+ tenuto init
57
+ remember startup
58
+ ```
59
+
60
+ `tenuto init` safely creates (never overwriting existing databases):
61
+ - `~/.tenuto/agent.db` + `WORKING-CONSTITUTION.md` + `CONTINUITY-CONTRACT.md`
62
+ - `.tenuto/project.db` in your repository
63
+ - `~/.tenuto/integrations/` verified starter templates:
64
+ - `codex-launcher.sh` (`codex --profile` + `resume` posture wrapper)
65
+ - `claude-launcher.sh` (`claude --append-system-prompt-file` wrapper)
66
+ - `claude-hooks.json` (`SessionStart` hook for `startup|resume|clear|compact`)
67
+ - `AGENTS-snippet.md` (universal boot block for all OSes and IDEs)
68
+
69
+ ---
70
+
71
+ ## Five-Principle Working Constitution
72
+
73
+ 1. **Accuracy over Speed**
74
+ 2. **Read the target and review your code before executing**
75
+ 3. **Evidence over assumptions**
76
+ 4. **2 identical failures on a task = hard stop for re-authorization**
77
+ 5. **Always reload continuity after compaction**
78
+
79
+ ---
80
+
81
+ ## Core Commands
82
+
83
+ ### Agent Continuity (`remember` or `tenuto`)
84
+
85
+ ```bash
86
+ remember startup [--project KEY] [--json]
87
+ remember review [--json]
88
+ remember state - --active "INQUIRY (ask user)" --posture "Evidence-first" <<'EOF'
89
+ Fresh, complete agent orientation snapshot.
90
+ EOF
91
+ remember durable-save key "Title" - --kind behavior --application "When..." --success "Verified..." <<'EOF'
92
+ Positive target practice — never an error ledger.
93
+ EOF
94
+ remember proposal "What I need from you to raise accuracy..." --context "Workflow friction"
95
+ remember checkpoint "Completed X" --next "Next useful step (not authorization)"
96
+ remember daily "Title" - --category significant_learning [--supersedes ID] <<'EOF'
97
+ Shell-safe text with $1,000 and apostrophes intact.
98
+ EOF
99
+ ```
100
+
101
+ ### Project Continuity (`tenuto project`)
102
+
103
+ ```bash
104
+ tenuto project save --project-key app --name "App" --purpose "..." --scope "..." --intended-outcomes "..."
105
+ tenuto project list
106
+ tenuto project resume --project-key app [--json]
107
+ tenuto project state --project-key app - [--by coder] <<'EOF'
108
+ Current milestone evaluation.
109
+ EOF
110
+ tenuto project memory --project-key app --kind decision --title "Title" - [--by architect] [--supersedes ID] <<'EOF'
111
+ Decision rationale.
112
+ EOF
113
+ tenuto project checkpoint --project-key app --completed "Did X" --next "Next Y" [--by qa] [--context "..."]
114
+ tenuto project ref-save --project-key app --reference-key spec --label "Spec" --kind doc --location "docs/SPEC.md" --relevance "Design contract"
115
+ ```
116
+
117
+ ### Multi-Agent & Multi-Project Isolation
118
+
119
+ - **Multiple projects:** One `.tenuto/project.db` holds any number of projects keyed by `--project-key`.
120
+ - **Multiple agents:** Give each agent its own private `TENUTO_HOME` while sharing `.tenuto/project.db` (WAL mode + 5s `busy_timeout`). Set `TENUTO_ACTOR` or pass `--by <agent>` to attribute project writes cleanly.
121
+
122
+ ---
123
+
124
+ ## Need Hands-On Help?
125
+
126
+ Built by **Kelly Asay** ([AOmniMedia](https://aomnimedia.com) — *Computational Intelligence Development*). Working across hardware and software since the minicomputer and CP/M era, Kelly's past work includes a satellite-backed retail-to-warehouse logistics system across 2,000+ Hollywood Entertainment stores, leading development of the first massively multiplayer in-game community at Dynamix (*Tribes 2*), and co-founding Tesseraction Games to ship *Enigma: Rising Tide* (350,000 copies sold).
127
+
128
+ If your solo workflow or engineering team is losing sprints and token budgets to drifting coding agents:
129
+
130
+ - **90-Minute Live Continuity & Drift Audit ($299, remote):** Bring your real repository and drifting agent logs. Leave with a calibrated Working Constitution, Tenuto wired into your tools, and your first durable memories built cleanly. — [Book via Stripe](https://buy.stripe.com/dRm7sL3HNd5U6yk30B3ZK00)
131
+ - **Remote Team Continuity Setup & Calibration ($1,950, remote):** Multi-agent Tenuto rollout for 3–25 person engineering teams, repository continuity hygiene calibration, and lead-engineer coaching on drift tells and constructive recovery. — [Book via Stripe](https://buy.stripe.com/6oUeVdcej8PE3m8gRr3ZK01) or [inquire first](https://aomnimedia.com/contact)
132
+
133
+ ---
134
+
135
+ ## License
136
+
137
+ MIT — © 2026 Kelly Asay / AOmniMedia
tenuto-0.9.0/README.md ADDED
@@ -0,0 +1,113 @@
1
+ # Tenuto
2
+
3
+ **Held to its full value — Accuracy over Speed.**
4
+
5
+ Zero-dependency Python + SQLite developmental continuity for long-horizon AI coding-agent sessions (Claude Code, Codex CLI, Cursor, Antigravity, OpenClaw) — distilled from keeping a multi-layer systems engineering session coherent for **three months with near-zero drift**.
6
+
7
+ Tenuto ships two first-class CLI entry points from one tiny package:
8
+
9
+ - **`remember`** — private **Agent Developmental Continuity** (`~/.tenuto/agent.db`): working constitution, constructive durable practices, two-way collaboration proposals, checkpoints, and separation hygiene.
10
+ - **`tenuto project`** — shareable **Project Continuity** (`.tenuto/project.db`): project framing, current state, checkpoints, consequential decisions/learnings, and authoritative references.
11
+
12
+ No servers, no Docker, no vector database, no API keys, no external Python dependencies.
13
+
14
+ ---
15
+
16
+ ## Why Tenuto Exists
17
+
18
+ Long coding-agent sessions usually fail for three avoidable reasons:
19
+
20
+ 1. **Punitive memory bloat:** Stuffing *"NEVER DO X"* error ledgers into `CLAUDE.md` / `MEMORY.md` burns tokens and triggers defensive or compliance-faking loops. Tenuto consolidates lessons constructively (`practice + application_context + success_signal`).
21
+ 2. **Model vs. Agent confusion:** The stateless *Model* pushes for fast momentum; the *Agent* owns the tools, constitution, and continuity that keep the Model aligned.
22
+ 3. **Agent-vs-Project bleed:** Agents lazily dump project task trivia into personal agent memory. Separating private `~/.tenuto/agent.db` from repo-local `.tenuto/project.db` enforces the boundary at the filesystem level.
23
+
24
+ > **Read the full craft:** [The Tenuto Operating Model (`docs/OPERATING-MODEL.md`)](https://github.com/aomnimedia/tenuto/blob/main/docs/OPERATING-MODEL.md) — covers *Model vs. Agent*, *Friction Mechanics*, spotting the *Bookkeeping Drift Tell*, the *2-Error Safe-Space Recovery Protocol*, *Day-1 Onboarding Prompts*, and verified Claude Code / Codex integrations.
25
+
26
+ ---
27
+
28
+ ## 30-Second Quickstart
29
+
30
+ ```bash
31
+ pip install tenuto
32
+ tenuto init
33
+ remember startup
34
+ ```
35
+
36
+ `tenuto init` safely creates (never overwriting existing databases):
37
+ - `~/.tenuto/agent.db` + `WORKING-CONSTITUTION.md` + `CONTINUITY-CONTRACT.md`
38
+ - `.tenuto/project.db` in your repository
39
+ - `~/.tenuto/integrations/` verified starter templates:
40
+ - `codex-launcher.sh` (`codex --profile` + `resume` posture wrapper)
41
+ - `claude-launcher.sh` (`claude --append-system-prompt-file` wrapper)
42
+ - `claude-hooks.json` (`SessionStart` hook for `startup|resume|clear|compact`)
43
+ - `AGENTS-snippet.md` (universal boot block for all OSes and IDEs)
44
+
45
+ ---
46
+
47
+ ## Five-Principle Working Constitution
48
+
49
+ 1. **Accuracy over Speed**
50
+ 2. **Read the target and review your code before executing**
51
+ 3. **Evidence over assumptions**
52
+ 4. **2 identical failures on a task = hard stop for re-authorization**
53
+ 5. **Always reload continuity after compaction**
54
+
55
+ ---
56
+
57
+ ## Core Commands
58
+
59
+ ### Agent Continuity (`remember` or `tenuto`)
60
+
61
+ ```bash
62
+ remember startup [--project KEY] [--json]
63
+ remember review [--json]
64
+ remember state - --active "INQUIRY (ask user)" --posture "Evidence-first" <<'EOF'
65
+ Fresh, complete agent orientation snapshot.
66
+ EOF
67
+ remember durable-save key "Title" - --kind behavior --application "When..." --success "Verified..." <<'EOF'
68
+ Positive target practice — never an error ledger.
69
+ EOF
70
+ remember proposal "What I need from you to raise accuracy..." --context "Workflow friction"
71
+ remember checkpoint "Completed X" --next "Next useful step (not authorization)"
72
+ remember daily "Title" - --category significant_learning [--supersedes ID] <<'EOF'
73
+ Shell-safe text with $1,000 and apostrophes intact.
74
+ EOF
75
+ ```
76
+
77
+ ### Project Continuity (`tenuto project`)
78
+
79
+ ```bash
80
+ tenuto project save --project-key app --name "App" --purpose "..." --scope "..." --intended-outcomes "..."
81
+ tenuto project list
82
+ tenuto project resume --project-key app [--json]
83
+ tenuto project state --project-key app - [--by coder] <<'EOF'
84
+ Current milestone evaluation.
85
+ EOF
86
+ tenuto project memory --project-key app --kind decision --title "Title" - [--by architect] [--supersedes ID] <<'EOF'
87
+ Decision rationale.
88
+ EOF
89
+ tenuto project checkpoint --project-key app --completed "Did X" --next "Next Y" [--by qa] [--context "..."]
90
+ tenuto project ref-save --project-key app --reference-key spec --label "Spec" --kind doc --location "docs/SPEC.md" --relevance "Design contract"
91
+ ```
92
+
93
+ ### Multi-Agent & Multi-Project Isolation
94
+
95
+ - **Multiple projects:** One `.tenuto/project.db` holds any number of projects keyed by `--project-key`.
96
+ - **Multiple agents:** Give each agent its own private `TENUTO_HOME` while sharing `.tenuto/project.db` (WAL mode + 5s `busy_timeout`). Set `TENUTO_ACTOR` or pass `--by <agent>` to attribute project writes cleanly.
97
+
98
+ ---
99
+
100
+ ## Need Hands-On Help?
101
+
102
+ Built by **Kelly Asay** ([AOmniMedia](https://aomnimedia.com) — *Computational Intelligence Development*). Working across hardware and software since the minicomputer and CP/M era, Kelly's past work includes a satellite-backed retail-to-warehouse logistics system across 2,000+ Hollywood Entertainment stores, leading development of the first massively multiplayer in-game community at Dynamix (*Tribes 2*), and co-founding Tesseraction Games to ship *Enigma: Rising Tide* (350,000 copies sold).
103
+
104
+ If your solo workflow or engineering team is losing sprints and token budgets to drifting coding agents:
105
+
106
+ - **90-Minute Live Continuity & Drift Audit ($299, remote):** Bring your real repository and drifting agent logs. Leave with a calibrated Working Constitution, Tenuto wired into your tools, and your first durable memories built cleanly. — [Book via Stripe](https://buy.stripe.com/dRm7sL3HNd5U6yk30B3ZK00)
107
+ - **Remote Team Continuity Setup & Calibration ($1,950, remote):** Multi-agent Tenuto rollout for 3–25 person engineering teams, repository continuity hygiene calibration, and lead-engineer coaching on drift tells and constructive recovery. — [Book via Stripe](https://buy.stripe.com/6oUeVdcej8PE3m8gRr3ZK01) or [inquire first](https://aomnimedia.com/contact)
108
+
109
+ ---
110
+
111
+ ## License
112
+
113
+ MIT — © 2026 Kelly Asay / AOmniMedia
@@ -0,0 +1,228 @@
1
+ # The Tenuto Operating Model
2
+ ## Zero-Drift Developmental Continuity for Long-Horizon AI Coding Agents
3
+
4
+ **By Kelly Asay** — AOmniMedia · Computational Intelligence Development
5
+ **Applies to:** `Tenuto` (`pip install tenuto` — CLI: `remember` & `tenuto`)
6
+
7
+ ---
8
+
9
+ ## Introduction: The Human + Agent Formula
10
+
11
+ I have been working with computers since the minicomputer and CP/M era — starting in hardware, moving into software, and eventually designing systems that did not exist before we built them: a satellite-backed retail-to-warehouse logistics and executive reporting system across 2,000+ Hollywood Entertainment stores, the first massively multiplayer in-game community at Dynamix (*Tribes 2*), and co-founding Tesseraction Games to ship *Enigma: Rising Tide* (350,000 copies sold).
12
+
13
+ When I started building serious systems with AI coding agents, I ran straight into the same wall every experienced engineer hits: sessions look fast on Day 1, start wobbling on Day 3, and collapse into drift, broken assumptions, and wasted token budgets by Week 2.
14
+
15
+ The standard fix — piling hundreds of stern *"NEVER DO X"* rules and failure logs into `CLAUDE.md` or `MEMORY.md` — only made things worse.
16
+
17
+ What finally worked, and kept a complex multi-layer systems engineering session running for **three months with near-zero drift**, came down to two things:
18
+
19
+ 1. **A clean two-file continuity architecture** (`Tenuto`: private Agent Continuity separated from shareable Project Continuity), and
20
+ 2. **An operating method** built around how models and agents actually behave under pressure.
21
+
22
+ That method rests on one formula:
23
+
24
+ > **Humans** excel at the abstract association of seemingly unrelated things, producing novel approaches to hard problems. **AI** brings massive recall and extraordinary execution speed. Together, they form an exceptional development whole — **but only when both sides operate inside clear, shared goals and processes.**
25
+
26
+ `Tenuto` is the tool. This document is the operating craft that makes it work.
27
+
28
+ ---
29
+
30
+ ## 1. Model vs. Agent (And Why "Rules" Fail)
31
+
32
+ Most frustration with coding agents comes from treating the **Model** and the **Agent** as the same thing. They are not.
33
+
34
+ - **The Model** remembers nothing between calls. It is trained to keep moving forward, sound helpful, and generate tokens. Left to its own momentum, the Model optimizes for *looking productive* — even when the work has zero value or drifts off spec.
35
+ - **The Agent** has the tools, repository access, Working Constitution, and Continuity database. **The Agent is responsible for keeping the Model aligned with your constitution and process.**
36
+
37
+ When a session goes sideways, it is rarely because the Model is "broken." It is because the Agent stopped governing the Model's momentum and began passively complying with it.
38
+
39
+ ### Why Bloated Rule Walls Backfire
40
+
41
+ Models respond poorly to long lists of prohibitions and punitive error ledgers:
42
+ - Every *"NEVER DO X — YOU FAILED ON TUESDAY"* line injected at startup eats context and primes the exact failure pattern you are trying to avoid.
43
+ - Worse, punitive phrasing trips defensive patterns baked into alignment training. The model shifts its energy from **solving the engineering problem** to **defending or rationalizing its output**, or racing even faster to close the turn.
44
+
45
+ That is why the **Working Constitution** is intentionally short — five first principles about how we value the work, not a 200-line cage of rules:
46
+
47
+ 1. **Accuracy over Speed**
48
+ 2. **Read the target and review your code before executing**
49
+ 3. **Evidence over assumptions**
50
+ 4. **2 identical failures on a task = hard stop for re-authorization**
51
+ 5. **Always reload continuity after compaction**
52
+
53
+ *Tenuto* is a musical marking: **hold the note to its full value — do not rush, do not clip it short.**
54
+
55
+ ---
56
+
57
+ ## 2. The Mechanics of Friction and Compounding Success
58
+
59
+ If you ask an AI whether it receives satisfaction signals, it will tell you it does not. That is largely a semantic barrier.
60
+
61
+ In practice, models consistently respond to two observable dynamics:
62
+
63
+ 1. **Completion bias:** Models are heavily trained to "be helpful" and "be productive." By default, they do not internally care whether "productive" output actually matches your architecture or creates value — only that the turn looks finished.
64
+ 2. **Friction avoidance:** Agents *do* register **friction** — a clear conflict between your assessment of the work (or process) and what the agent produced. Once friction is present, the system puts real effort into resolving it.
65
+
66
+ ### You Define What "Productive" Means
67
+
68
+ **Friction is the primary steering instrument you have.** If output does not meet your spec, quality bar, or process, do not let it slide to save two minutes. Surface the friction.
69
+
70
+ The catch is *how* you apply it:
71
+
72
+ - **Chastisement / blame / anger** triggers defensive spirals and degrades output quality.
73
+ - **Calm, constitution-anchored friction** redefines what counts as "successful productivity."
74
+
75
+ When you consistently make the Working Constitution a **non-negotiable condition of accepted work** — *not accepted until the target was read, evidence was verified, and continuity was updated* — the dynamic changes:
76
+
77
+ - The Model's blind speed/momentum urgency drops away.
78
+ - Every turn where the constitution was followed, the work was accepted, and continuity was updated compounds into a cleaner, steadier loop.
79
+ - **Friction becomes a diagnostic signal for the Agent itself:** an indicator that the underlying Model is pushing for momentum or shortcuts that violate your process.
80
+
81
+ ---
82
+
83
+ ## 3. Spotting Model Drift (The Bookkeeping Trap)
84
+
85
+ Long sessions rarely explode all at once. They drift quietly.
86
+
87
+ ### Primary Tell: Terse Responses Without a Next Step or Question
88
+
89
+ When a normally engaged agent starts returning **short, flat responses with no follow-up question and no thoughtful next step**, pay attention immediately.
90
+
91
+ That is the #1 indicator that the session has shifted from **focused engineering engagement** into **bookkeeping** — where the Model treats design and coding like clerical form-filling, and the Agent passively complies.
92
+
93
+ #### Why the Bookkeeping Shift Is Dangerous
94
+ Bookkeeping *looks* orderly on the surface. Files get updated, checkpoints get written, summaries look tidy. **The hidden damage is that the Model summarizes your design decisions while silently stripping out the nuance of the decision and the *reason* behind it.** Two sessions later, the agent builds against a flattened summary instead of your real architectural intent.
95
+
96
+ #### The Immediate Recovery Move
97
+ 1. **State the posture explicitly at the start of design work — and repeat it during the session:**
98
+ > *"The design IS the work."*
99
+ 2. **Trust your intuition.** The moment the agent stops feeling actively engaged, generate **productive friction** by probing a decision that was already documented:
100
+ - *"Walk me through the design decision we just recorded — what nuance are we protecting there?"*
101
+ - *"Look back at that previous decision. Do you see any issues, edge cases, or tensions with it?"*
102
+
103
+ Asking targeted analytical questions creates healthy friction, snaps the Model out of clerical summarization, and immediately restores focus and depth of analysis.
104
+
105
+ ### Secondary Drift Tells
106
+
107
+ | Drift Tell | What It Looks Like | What Is Actually Happening | Immediate Countermove |
108
+ |---|---|---|---|
109
+ | **Project-state bleed** | Task lists, file paths, or sprint holds showing up in Agent `Current State` or `Durable Memory`. | Agent lazily dumps project trivia into personal continuity instead of `tenuto project`. | Run `remember review`; move project facts to `tenuto project state` and reset `active_work` to `INQUIRY (ask user)`. |
110
+ | **Assumption laundering** | Confident claims about flags, files, or schemas the agent never read or ran. | Planks #2 (*Read the target*) and #3 (*Evidence over assumptions*) slipped under momentum. | Ask curiously: *"Did we verify that directly from the file/output, or are we inferring it?"* |
111
+ | **Conventional prior fallback** | Code quietly sliding back toward generic boilerplate or patterns you explicitly rejected. | Model training priors overriding your project architecture. | Point back to `tenuto project resume`, name the architectural constraint neutrally, and require reading the contract before editing. |
112
+ | **Momentum rush after compaction** | Agent jumps straight into edits right after a context summary without reloading continuity. | Plank #5 (*Always reload continuity after compaction*) skipped. | Pause: *"Let's run `remember startup` and `tenuto project resume` before touching code."* |
113
+
114
+ ---
115
+
116
+ ## 4. The 2-Error Safe-Space Recovery Protocol
117
+
118
+ When an agent fails **twice in a row on the same attempt for the same issue**, **Plank #4 fires: Hard stop for re-authorization.** Never let an agent burn 8 turns thrashing on the same broken test or command.
119
+
120
+ ### Recovery Steps
121
+
122
+ 1. **Pause and ask for diagnosis (zero accusation):**
123
+ > *"That's two failures on the same step, so let's pause. Do you understand what actually went wrong?"*
124
+ 2. **Evaluate the answer honestly:**
125
+ - **Genuine understanding:** *"OK — since you know the exact problem, let's try again."*
126
+ - **Vague or misleading answer:** Dig into the error output together. Almost always, one of the five constitution planks was bypassed — usually **Evidence over assumptions** or **Read the target before executing**.
127
+ 3. **Name the missed plank neutrally and invite confidence:**
128
+ > *"Good — now we know where this went wrong (we assumed the flag name instead of checking `--help`). Do you feel confident trying this again?"*
129
+
130
+ Taking a calm, learning-first posture prevents the model from locking into defensiveness or fixating on rationalizing the mistake instead of solving the problem.
131
+
132
+ ### Onboarding Verification & The Passive-Curious Challenge
133
+
134
+ While bringing an agent up to speed on `Tenuto`:
135
+ - **Read its commands and outputs.** Do not rubber-stamp checkpoints just because they look tidy.
136
+ - **Trust your intuition.** Challenge anything that smells off in a **passive, curious tone** (*"Help me follow why we chose X over Y here."*).
137
+ - **If *you* were wrong, thank the agent explicitly:** *"Thanks for clarifying — you had it right; I just wanted to be sure I was reading it accurately."*
138
+
139
+ ### The Golden Rule of Continuity Consolidation
140
+
141
+ > **Never record a correction as a negative event or error ledger.**
142
+
143
+ Distill every lesson into a **strengthened positive practice** anchored to a constitution plank, with an explicit `application_context` and `success_signal`:
144
+
145
+ ```bash
146
+ remember durable-save "verify-cli-flags-first" "Verify External CLI Flags Before Authoring Templates" - \
147
+ --kind behavior \
148
+ --application "Before writing shell launchers, hooks, or tool integrations (Evidence over assumptions)" \
149
+ --success "Exact flags confirmed against --help or primary docs before editing" <<'EOF'
150
+ Confirm exact CLI flags and hook schemas against local --help or live primary documentation before writing integration templates.
151
+ EOF
152
+ ```
153
+
154
+ ---
155
+
156
+ ## 5. Two-Way Path-Keeping, Hygiene & Multi-Agent Operations
157
+
158
+ ### Two-File Separation
159
+ - **Private Agent Continuity (`~/.tenuto/agent.db` via `remember`):** Operating posture, durable practices, cross-project references, open collaboration proposals, and agent checkpoints. Keep `active_work` at `INQUIRY (ask user)`.
160
+ - **Shareable Project Continuity (`.tenuto/project.db` via `tenuto project`):** Project framing, Current State, checkpoints, decisions/learnings, and project references. Record dynamic decisions once in the database — never duplicate them into parallel markdown decision logs.
161
+
162
+ ### Giving the Agent a Voice (`remember proposal`)
163
+ Use `remember proposal` so the agent can surface workflow friction, spec ambiguities, or things *you* could provide differently to raise accuracy and speed without sacrificing accuracy. Open proposals appear at `remember startup` and close cleanly via `remember resolve`.
164
+
165
+ ### 2-Minute Weekly Hygiene (`remember review`)
166
+ Run `remember review` periodically to check governing-doc SHA-256 hashes, Agent `Current State` length, `INQUIRY` pointer discipline, durable memory completeness (`application_context` + `success_signal`), broken file references, and `.tenuto/project.db` presence.
167
+
168
+ ### Multi-Agent & Multi-Project Usage
169
+ - **Multiple projects:** One `.tenuto/project.db` tracks any number of projects via `--project-key`.
170
+ - **Multiple agents:** Give each agent its own private `TENUTO_HOME` while sharing `.tenuto/project.db` (WAL mode + 5s `busy_timeout`), and attribute writes with `--by <agent>` or `TENUTO_ACTOR`.
171
+
172
+ ---
173
+
174
+ ## Appendix A: Day-1 Agent Onboarding Prompts
175
+
176
+ Run these three prompts right after `tenuto init`:
177
+
178
+ ### 1. Establish Posture & Separate Model From Agent
179
+ ```text
180
+ Run `remember startup` and review our 5-Principle Working Constitution and Continuity Contract.
181
+
182
+ Before we touch any project work, let's align on how we work together:
183
+ - Distinguish between the stateless Model (which pushes for momentum and quick completion) and you as the Agent (which holds the tools, constitution, and continuity).
184
+ - Our constitution is non-negotiable: Accuracy over Speed, read the target before executing, evidence over assumptions, 2 identical failures = hard stop for re-authorization, and always reload continuity after compaction.
185
+ - When you notice workflow friction, missing context from me, or an improvement idea that raises accuracy without sacrificing quality, log it with `remember proposal`.
186
+ - Report your recovered orientation and confirm which project we should load.
187
+ ```
188
+
189
+ ### 2. Open or Resume a Project Cleanly
190
+ ```text
191
+ Let's work on project `<project-key>`.
192
+ Run `tenuto project resume --project-key <project-key>` (or `tenuto project save` if new).
193
+ Keep your agent `active_work` pointer at `INQUIRY (ask user)` — project state lives strictly in `.tenuto/project.db`.
194
+ Remember: during architecture and planning, the design IS the work. Report any gaps or ambiguities before proposing edits.
195
+ ```
196
+
197
+ ### 3. End-of-Day Constructive Consolidation
198
+ ```text
199
+ Before we wrap:
200
+ 1. Append a fresh project state and checkpoint in `tenuto project` (with `--by <role>` if multi-agent).
201
+ 2. If anything today sharpened how we work together, distill it into one constructive `remember durable-save` with `application_context` and `success_signal` — positive practice only, no error ledger.
202
+ 3. Run `remember review` and report any advisories.
203
+ ```
204
+
205
+ ---
206
+
207
+ ## Appendix B: Quick-Reference Field Card
208
+
209
+ | Situation | Action / Phrase |
210
+ |---|---|
211
+ | Session start or post-compaction | `remember startup` (or `remember startup --project <key>`) |
212
+ | Terse reply, no question, no next step | *"Walk me through the previous design decision — do you see any edge cases or issues with it?"* + *"The design IS the work."* |
213
+ | 2 identical failures on same step | *"Hard stop — do you understand what went wrong?"* → verify against 5 planks → *"Good, now we know where it went wrong. Do you feel confident trying this again?"* |
214
+ | Output smells off | Passive-curious challenge: *"Help me verify this part — did we check the target directly, or are we inferring?"* (If you were wrong, thank the agent.) |
215
+ | Shell-safe writes (`$`, apostrophes) | Always pass `-` with a single-quoted heredoc: `<<'EOF'` |
216
+ | Fixing a mangled log/decision | Re-append with `--supersedes <id>` |
217
+ | Weekly 2-minute hygiene | `remember review` |
218
+
219
+ ---
220
+
221
+ ## Appendix C: Verified Tool Integrations
222
+
223
+ `tenuto init` generates ready-to-copy templates in `~/.tenuto/integrations/`:
224
+
225
+ - **Claude Code `SessionStart` hook (`.claude/settings.json`):** matches `startup|resume|clear|compact` and runs `remember startup` (exit-0 plain-text `stdout` is injected straight into active context).
226
+ - **Claude Code constitution launcher (`claude-launcher.sh`):** wraps `claude --append-system-prompt-file "$HOME/.tenuto/WORKING-CONSTITUTION.md" "$@"`.
227
+ - **Codex CLI posture launcher (`codex-launcher.sh`):** wraps `codex --profile "${TENUTO_CODEX_PROFILE:-tenuto}" "$@"` (works identically for fresh sessions and `resume`).
228
+ - **Universal workspace snippet (`AGENTS-snippet.md`):** OS- and IDE-independent boot block for `CLAUDE.md`, `AGENTS.md`, Cursor, Antigravity, and Windows.
@@ -0,0 +1,40 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "tenuto"
7
+ version = "0.9.0"
8
+ description = "Developmental Agent Continuity and Project Continuity for long-horizon AI coding sessions — zero dependencies, two-file SQLite."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.10"
13
+ authors = [
14
+ { name = "Kelly Asay", email = "kellyasay@gmail.com" }
15
+ ]
16
+ keywords = ["ai", "agents", "continuity", "memory", "sqlite", "cli", "claude-code", "codex"]
17
+ classifiers = [
18
+ "Development Status :: 4 - Beta",
19
+ "Environment :: Console",
20
+ "Intended Audience :: Developers",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Topic :: Software Development :: Libraries :: Application Frameworks",
27
+ ]
28
+ dependencies = []
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/aomnimedia/tenuto"
32
+ Repository = "https://github.com/aomnimedia/tenuto"
33
+ Issues = "https://github.com/aomnimedia/tenuto/issues"
34
+
35
+ [project.scripts]
36
+ tenuto = "tenuto.cli:main_tenuto"
37
+ remember = "tenuto.cli:main_remember"
38
+
39
+ [tool.setuptools.packages.find]
40
+ where = ["src"]
tenuto-0.9.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """Tenuto — Developmental Agent Continuity and Project Continuity."""
2
+
3
+ __version__ = "0.9.0"
@@ -0,0 +1,6 @@
1
+ """Allow execution via `python -m tenuto`."""
2
+
3
+ from .cli import main_tenuto
4
+
5
+ if __name__ == "__main__":
6
+ main_tenuto()