The agent logs as their own skill: @gemstack/skill-logs, command logs; agents-logs folded onto agent-data

.the-framework/LAYOUT

@@ -1,8 +1,7 @@
 framework-dir: .the-framework
 data-branch: agent-data
-logs-branch: agents-logs
-archive-dir: agents
 events-file: events.jsonl
 meta-file: agent.json
 tickets-dir: tickets
 queue-file: TODO_AGENTS.md
+runs-dir: agents

FEATURES-SPEC.md

@@ -89,7 +89,7 @@ happens while nobody is at the keyboard.
 - Hottest tickets
 - Projects sidebar
 - A project whose directory was renamed or deleted leaves the sidebar on the next refresh, and comes back when the directory does; the registration is kept
-- Project errors: a project whose bookkeeping branches cannot reach origin (push rejected, or no remote) — the `agent-data` branch or the `agents-logs` branch — is flagged with a red dot in the sidebar and a banner on its page, until a sync converges
+- Project errors: a project whose bookkeeping branch cannot reach origin (push rejected, or no remote) — the `agent-data` branch — is flagged with a red dot in the sidebar and a banner on its page, until a sync converges
 
 ## Tickets
 
@@ -119,6 +119,8 @@ happens while nobody is at the keyboard.
 - `tickets` on every agent's PATH — the skill's command line: `list` and `show <file>` read the tickets with their plans and their holders, `put <file>` writes a ticket, a plan or the import stamp, `close <file>` removes a ticket with its plan and claim, `claim <file>` and `release <file>` are the claim; every one of them is one commit pushed to the `agent-data` branch
 - The `queue` skill: every checkout The Framework creates carries the `@gemstack/skill-queue` package's `SKILL.md` beside the other two (`.claude/skills/queue`, `.agents/skills/queue`), and the presets tell the agent to use it — the agent queue is on the `agent-data` branch, read and changed with the command; an agent anywhere else gets the same git bridge as for the tickets (#1750)
 - `queue` on every agent's PATH — the skill's command line: `queue` reads the queue in the order it is worked, `queue add <text> [--priority N]` puts an entry on it in its priority section, `queue done <text>` takes an entry off; every one of them is one commit pushed to the `agent-data` branch
+- The `logs` skill: every checkout The Framework creates carries the `@gemstack/skill-logs` package's `SKILL.md` beside the other three (`.claude/skills/logs`, `.agents/skills/logs`); it tells the agent to read a ticket's past runs before planning or working it — a stopped or failed run says what to avoid, a done run with a PR says the work may be there; an agent anywhere else gets the skill's text through the same bridge as for the tickets (#1769)
+- `logs` on every agent's PATH — the skill's command line, read-only: `logs` lists the runs newest first (the newest 20 unless `--limit N`), `--ticket <file>` the runs that worked one ticket, `--branch <name>` the runs on one branch, `logs show <id>` one run's card with what the agent said, its result, its ending and its cost; the daemon's own bookkeeping on the card is never printed
 - The session name is the branch: an agent is labelled by its `agent-<name>` branch, read from git after every turn — nothing to signal, nothing to record twice
 - Dependency directories shared from the parent checkout instead of reinstalled — as directories of links, so an agent's own install stays in its checkout and never rewrites or purges the parent's
 - A checkout whose work is not on the remote is kept — and a publish-nothing (`handoff: local`) agent's is kept until you publish or delete it
@@ -130,7 +132,7 @@ happens while nobody is at the keyboard.
 - Empty agents publish nothing
 - Handoff panel: push / open PR / merge, as buttons
 - A withheld merge is reported with its reason
-- Agent history archived on the `agents-logs` branch under per-user directories — pushed the moment a session settles
+- Agent history recorded on the `agent-data` branch as the `logs` skill's runs, under per-person directories — pushed the moment a session settles; the framework's own fields ride inside the skill's card under one key, and its other events inside the diary beside the four kinds the skill knows
 - Post-merge quality follow-ups queued (maintainability / security)
 - Knowledge folded back into `DECISIONS.md` / `FACTS.md` / `INSIGHTS.md` at merge
 
@@ -148,7 +150,7 @@ happens while nobody is at the keyboard.
 - Reclaim the checkout of an agent whose work is on the remote — never by publishing what a `handoff: local` agent refused to
 - An agent that committed nothing leaves no branch behind: its empty branch goes with its checkout, never pushed — and the run-id branch it started on goes too, once the branch it moved to holds everything the run-id branch did
 - A directory under `.branches/` that git does not know as a worktree is never committed, pushed, linked or deleted through — it is reported and left alone, so a leftover can never stand in for your own checkout
-- One triage at a time, across machines: a routine lock (`routines/<name>.lock.md` on the `agents-logs` branch) taken by the daemon before the run starts and released when it ends, whatever the ending; a held lock stands the routine down naming the machine holding it, with no agent spent; a lock left by a dead machine expires after four hours, and a daemon frees its own on boot
+- One triage at a time, across machines: a routine lock (`routines/<name>.lock.md` on the `agent-data` branch) taken by the daemon before the run starts and released when it ends, whatever the ending; a held lock stands the routine down naming the machine holding it, with no agent spent; a lock left by a dead machine expires after four hours, and a daemon frees its own on boot
 - The agent drains its own TODO backlog, one entry per turn
 
 ## Spending
@@ -190,7 +192,7 @@ happens while nobody is at the keyboard.
 - Answer a cloud agent's question from the dashboard (typed back into claude.ai) — the same gate panel a local agent gets, multi-select and stop options included, listed with every other open question
 - Browser-bridge token setting
 - A cloud run's row follows the session's real branch and PR, with its armed draft PR opened when the session opens none
-- Another machine's runs on the shared `agents-logs` branch are told apart: their rows carry a glyph naming the machine that started them (the Overview's working-now card spells it out), and a run is listed once even when two checkouts share its archive
+- Another machine's runs on the shared `agent-data` branch are told apart: their rows carry a glyph naming the machine that started them (the Overview's working-now card spells it out), and a run is listed once even when two checkouts share its archive
 
 ## Notifications
 

SPEC.md

@@ -25,7 +25,7 @@ Every user-facing feature is enumerated in `FEATURES-SPEC.md`.
 - **The agent is the unit of work** - one task, in its own git worktree on its own branch, streaming everything it does as events; finished work is pushed and leaves as a pull request.
 - **Black-box driving** - the framework prompts the wrapped coding-agent CLI, lets the CLI's own loop run a full turn, and learns everything from the turn's final message: the session name the agent invented, the questions it stops to ask, and the ready-for-merge signal.
 - **Autonomy bounded by the account's own quota** - unattended work runs only while the account is under its pro-rated quota boundary; work a human asks for is never blocked, and a running agent is never interrupted over quota.
-- **Nothing bookkeeping-shaped on a code branch** - the tickets and the agent queue live on the `agent-data` branch, the `tickets` skill's and the `queue` skill's; The Framework's own records of its runs — the agent archives, the routine locks — live on the `agents-logs` branch. The default branch stays 100% code.
+- **Nothing bookkeeping-shaped on a code branch** - the tickets, the agent queue and the record of every run live on the `agent-data` branch, the `tickets`, `queue` and `logs` skills'; The Framework's routine locks sit beside them. The default branch stays 100% code.
 
 ## Business logic
 
@@ -47,7 +47,7 @@ See `## User story`: the daemon keeps working while nobody is around, within the
 
 #### Business logic
 
-On a shared clock the daemon runs its background jobs: Auto PM works the agent queue down and refills it by triaging tickets and planning the ones without plans; the CI watch merges the framework's pull requests once their checks pass and starts a fix agent when checks go red; sweeps reclaim finished agents' checkouts (only what is already on the remote) and keep bookkeeping healthy, and a routine that must not run twice is guarded by a routine lock on the `agents-logs` branch. Each unattended start checks the quota boundary first.
+On a shared clock the daemon runs its background jobs: Auto PM works the agent queue down and refills it by triaging tickets and planning the ones without plans; the CI watch merges the framework's pull requests once their checks pass and starts a fix agent when checks go red; sweeps reclaim finished agents' checkouts (only what is already on the remote) and keep bookkeeping healthy, and a routine that must not run twice is guarded by a routine lock on the `agent-data` branch. Each unattended start checks the quota boundary first.
 
 ## Before modifying/creating SPEC.md files
 

package.json

@@ -11,8 +11,8 @@
     "preview": "pnpm -C packages/framework preview",
     "dev": "pnpm -C packages/framework dev",
     "typecheck": "pnpm -C packages/framework typecheck && pnpm -C packages/the-framework.ai typecheck",
-    "clean": "pnpm -C packages/agent-data clean && pnpm -C packages/skill-branches clean && pnpm -C packages/skill-tickets clean && pnpm -C packages/skill-queue clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
-    "test": "pnpm -C packages/agent-data test && pnpm -C packages/skill-branches test && pnpm -C packages/skill-tickets test && pnpm -C packages/skill-queue test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
+    "clean": "pnpm -C packages/agent-data clean && pnpm -C packages/skill-branches clean && pnpm -C packages/skill-tickets clean && pnpm -C packages/skill-queue clean && pnpm -C packages/skill-logs clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
+    "test": "pnpm -C packages/agent-data test && pnpm -C packages/skill-branches test && pnpm -C packages/skill-tickets test && pnpm -C packages/skill-queue test && pnpm -C packages/skill-logs test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
     "========= Website": "",
     "// Develop website https://the-framework.ai locally": "",
     "website": "cd packages/the-framework.ai/ && pnpm run dev",
@@ -25,6 +25,7 @@
     "@gemstack/skill-branches": "workspace:*",
     "@gemstack/skill-tickets": "workspace:*",
     "@gemstack/skill-queue": "workspace:*",
+    "@gemstack/skill-logs": "workspace:*",
     "typescript": "^7.0.2"
   }
 }

packages/SPEC.md

@@ -5,11 +5,12 @@ The deliverables The Framework ships, one directory each:
 - `skill-branches/` — the `@gemstack/skill-branches` npm package: the git conventions and operations behind an agent's own checkout, with the skill's instructions (`SKILL.md`) and the `branches` command an agent follows them with: the first skill of the skills-plus architecture (#1725). The product depends on it, and so does the skill-tickets package; it depends on agent-data.
 - `skill-tickets/` — the `@gemstack/skill-tickets` npm package: the project's tickets on the `agent-data` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `tickets` command an agent reads, writes and claims them with: the second skill of the skills-plus architecture (#1748). The product depends on it; it depends on agent-data for the branch it keeps everything on.
 - `skill-queue/` — the `@gemstack/skill-queue` npm package: the project's agent queue on the `agent-data` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `queue` command an agent reads and changes it with: the third skill, split out of skill-tickets (#1750). The product depends on it; it depends on agent-data only.
+- `skill-logs/` — the `@gemstack/skill-logs` npm package: the record of every run agents made on a project, on the `agent-data` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `logs` command an agent reads it with: the fourth skill (#1769). The product writes every run through it and reads its history back the same way; it depends on agent-data only.
 - `agent-driver/` — the `agent-driver` npm package: the driver seam — start a coding-agent CLI in a directory, prompt it for one full turn, stream what it does, resume it later — with the Claude Code, Codex, GitHub Actions and fake implementations. The product depends on it and adds its own cloud-session implementation behind the same contract.
 - `chrome-extension/` — the Claude web bridge, a companion Chrome extension that connects Claude Code cloud sessions on claude.ai back to the local dashboard.
 - `the-framework.ai/` — the marketing website.
 
-The product depends on the agent-data, skill-branches, skill-tickets, skill-queue and agent-driver packages in code; the extension and the website depend on the product only in what they present. See the root `SPEC.md` for how they relate as a product.
+The product depends on the agent-data, skill-branches, skill-tickets, skill-queue, skill-logs and agent-driver packages in code; the extension and the website depend on the product only in what they present. See the root `SPEC.md` for how they relate as a product.
 
 ## Before modifying/creating SPEC.md files
 

packages/framework/SPEC.md

@@ -2,7 +2,7 @@ The product: the `framework` npm package. One CLI, `the-framework`, runs a foreg
 
 How the package's pieces relate:
 
-- `src/` — everything that runs in Node: the CLI, the daemon, the agent lifecycle (checkouts through the `skill-branches` package, gates, handoff), the drivers (the agent-driver package's, plus the product's own hand-off to a Claude Code cloud session), the `agents-logs` branch its own records live on (a branch used as a file store through the `@gemstack/agent-data` package; the tickets are the `skill-tickets` package's and the queue the `skill-queue` package's), autonomy (Auto PM, sweeps, CI watch), and the server side of the dashboard.
+- `src/` — everything that runs in Node: the CLI, the daemon, the agent lifecycle (checkouts through the `skill-branches` package, gates, handoff), the drivers (the agent-driver package's, plus the product's own hand-off to a Claude Code cloud session), its own records — the runs are the `skill-logs` package's, the tickets the `skill-tickets` package's and the queue the `skill-queue` package's, all on the `agent-data` branch, a branch used as a file store through the `@gemstack/agent-data` package, autonomy (Auto PM, sweeps, CI watch), and the server side of the dashboard.
 - `dashboard/` — the browser app the daemon serves: a single-page app that is a pure projection of the files the daemon writes, reading over `POST /_rpc/<name>` and a live event stream, and steering agents back through the same daemon.
 - `prompts/` — every prompt The Framework sends an agent, as markdown: the built-in system prompt, the protocols agents answer through, and the presets. The markdown is the only source of truth for agent-facing text.
 - `scripts/` — the build steps that compile the prompts into importable strings and run the package's test suites.

packages/framework/dashboard/components/AgentHistory.SPEC.md

@@ -52,7 +52,7 @@ Scanning the list, the user needs to tell at a glance which agents need them, wh
 
 Each row shows a status word with a matching dot: a working agent pulses and reads its running status; an agent parked on the user reads "waiting" with a still dot, because it used to pulse identically whether it was mid-edit or had been idle for an hour; an agent that ended clean but has not yet reported its handoff reads "publishing…" with a pulsing dot, matching the wording on its own page; an agent that handed its task to a cloud session reads, once its local half is done, what the cloud side is doing per the cloud state rule (`cloud-run-state`): "waiting" with a still dot when the browser bridge holds a question its session is parked on, "in cloud" while the session is assumed to still be working, "merged" once the framework merged its pull request, and "done" once it has a pull request or the session can no longer be working — never "in cloud" forever. Otherwise the row shows the agent's final status.
 
-Beside that: how long ago it started (preceded by its project name on the Overview), and, at the end of the line, a glyph naming the machine when another machine's daemon started the agent — the `agents-logs` branch the archives live on is shared, so other machines' agents are listed here, and one that looked like this daemon's own was a mystery; a glyph rather than a word, since the rail's fixed width would cut a machine name short — a device glyph naming the device when the agent runs on another machine, a cloud glyph when it is a cloud session, and the logo of the driver that ran it. Underneath sits the agent's task; a task too long for the rail's fixed width is faded at its end and shows in full on hover, while one that fits is shown plainly with no hover at all.
+Beside that: how long ago it started (preceded by its project name on the Overview), and, at the end of the line, a glyph naming the machine when another machine's daemon started the agent — the `agent-data` branch the runs live on is shared, so other machines' agents are listed here, and one that looked like this daemon's own was a mystery; a glyph rather than a word, since the rail's fixed width would cut a machine name short — a device glyph naming the device when the agent runs on another machine, a cloud glyph when it is a cloud session, and the logo of the driver that ran it. Underneath sits the agent's task; a task too long for the rail's fixed width is faded at its end and shows in full on hover, while one that fits is shown plainly with no hover at all.
 
 ### Destinations and what is highlighted
 

packages/framework/dashboard/components/AgentHistory.tsx

@@ -626,7 +626,7 @@ function AgentHistoryRow({
             being decorative. */}
         {(remote || cloud || picked || startedOn) && (
           <span className="ml-auto flex shrink-0 items-center gap-1.5">
-            {/* Another machine's daemon started this run (#1648): the shared agents-logs branch lists every
+            {/* Another machine's daemon started this run (#1648): the shared agent-data branch lists every
                 machine's runs here, and one that looked exactly like this daemon's own was a mystery
                 solved only by reading the archive. A glyph, not a word in the meta line: the rail's
                 fixed width truncated a hostname to "from…". */}

packages/framework/dashboard/components/ProjectErrorBanner.SPEC.md

@@ -2,7 +2,7 @@ The warning banner at the top of a project's page, listing every project error t
 
 ## Glossary
 
-- **project error** - a condition the daemon has found broken about a project and keeps recorded until the condition is gone. Today the only kind is one of the project's two bookkeeping branches failing to converge with origin — the `agent-data` branch, holding the tickets and the agent queue, or the `agents-logs` branch, holding the agent archives and the routine locks — headlined "Not syncing with the remote".
+- **project error** - a condition the daemon has found broken about a project and keeps recorded until the condition is gone. Today the only kind is the project's bookkeeping branch failing to converge with origin — the `agent-data` branch, holding the tickets, the agent queue, the runs and the routine locks — headlined "Not syncing with the remote".
 
 ## Business logic — TL;DR
 

packages/framework/dashboard/components/ProjectErrorBanner.tsx

@@ -3,7 +3,7 @@ import type { ProjectError, ProjectErrorCode } from '../../src/index.js'
 import { formatAge } from '../lib/format-date.js'
 
 // What the daemon currently finds wrong with the project (#1500), at the top of its page. The
-// daemon records the state and clears it when the condition is gone (#1599: a tickets or agents-logs branch that
+// daemon records the state and clears it when the condition is gone (#1599: an agent-data branch that
 // cannot reach origin), so this renders exactly what the project list carries — no state of its
 // own, and nothing to dismiss: the way to make it go away is to fix the thing it names.