artshelf 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/README.md +58 -27
- package/SPEC.md +28 -0
- package/docs/agent-clean.html +126 -0
- package/docs/agent-create.html +98 -0
- package/docs/agent-monitor.html +150 -0
- package/docs/agent-review.html +120 -0
- package/docs/agent-usage.html +104 -313
- package/docs/agent-usage.md +36 -379
- package/docs/examples/artshelf-review-report.json +116 -0
- package/docs/index.html +160 -152
- package/docs/install.html +187 -109
- package/docs/quickstart.html +105 -106
- package/docs/reference.html +214 -164
- package/docs/schemas/artshelf-review-report.schema.json +315 -0
- package/docs/site.css +675 -490
- package/docs/site.js +397 -0
- package/examples/artshelf-review-report.json +116 -0
- package/package.json +3 -1
- package/schemas/artshelf-review-report.schema.json +315 -0
- package/skills/artshelf/SKILL.md +140 -256
- package/skills/artshelf/examples/artshelf-review-report.json +116 -0
- package/skills/artshelf/schemas/artshelf-review-report.schema.json +315 -0
- package/skills/artshelf/scripts/render-review-report.mjs +160 -0
- package/docs/theme.js +0 -42
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>Review · Agent usage · Artshelf</title>
|
|
7
|
+
<meta name="description" content="How agents turn Artshelf monitor output into decision packets.">
|
|
8
|
+
<script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
12
|
+
<link rel="stylesheet" href="site.css">
|
|
13
|
+
<script src="site.js" defer></script>
|
|
14
|
+
</head>
|
|
15
|
+
<body data-page="agent-review.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
|
26
|
+
<svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
|
27
|
+
</button>
|
|
28
|
+
</div>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
34
|
+
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">4.3</span>Agents · Review</p>
|
|
38
|
+
<h1>Turn raw counts into a decision packet.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Review is where a human enters the loop. Show what is ready for approval,
|
|
41
|
+
what needs a closer look, what is blocked, and the safety line.
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
<section>
|
|
45
|
+
<h2>Daily review workflow</h2>
|
|
46
|
+
<ol>
|
|
47
|
+
<li>Read <code>ledgers list</code>, <code>review --all</code>, and <code>trash list --all</code>.</li>
|
|
48
|
+
<li>Run explicit-ledger purge dry-runs only when old trash needs review.</li>
|
|
49
|
+
<li>Classify each candidate: <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
|
|
50
|
+
<li>Ask only with exact ledger path, reviewed plan id, or ids.</li>
|
|
51
|
+
</ol>
|
|
52
|
+
</section>
|
|
53
|
+
|
|
54
|
+
<section>
|
|
55
|
+
<h2>Review plan report schema</h2>
|
|
56
|
+
<p>Construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
|
|
57
|
+
<p>
|
|
58
|
+
Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
|
|
59
|
+
and <a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>.
|
|
60
|
+
The portable skill also ships <code>scripts/render-review-report.mjs</code>;
|
|
61
|
+
keep <code>decisionSummary</code> in the audit packet while
|
|
62
|
+
<code>decisionGroups</code> drive its visible counts and sections.
|
|
63
|
+
Emojis are encouraged only in host-specific wrappers, not the renderer.
|
|
64
|
+
</p>
|
|
65
|
+
<pre><code>Artshelf daily review
|
|
66
|
+
Status: <ok|attention needed>; registry <ok|attention>
|
|
67
|
+
|
|
68
|
+
Ready for approval: <n>
|
|
69
|
+
Needs review first: <n>
|
|
70
|
+
Blocked: <n>
|
|
71
|
+
|
|
72
|
+
Recommended action
|
|
73
|
+
<one short sentence>.
|
|
74
|
+
|
|
75
|
+
Ready for approval
|
|
76
|
+
1. <label>
|
|
77
|
+
Why: <reason>
|
|
78
|
+
Action: <next step>
|
|
79
|
+
approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
80
|
+
|
|
81
|
+
Needs review first
|
|
82
|
+
1. <label>
|
|
83
|
+
Why: <reason>
|
|
84
|
+
Suggested next step: <next step>
|
|
85
|
+
|
|
86
|
+
Blocked
|
|
87
|
+
<none, or blocker and repair step>
|
|
88
|
+
|
|
89
|
+
Safety
|
|
90
|
+
Dry-run only. No execute, resolve, or delete ran.</code></pre>
|
|
91
|
+
</section>
|
|
92
|
+
|
|
93
|
+
<section>
|
|
94
|
+
<h2>Approval wording</h2>
|
|
95
|
+
<p>
|
|
96
|
+
Keep the full JSON as the audit packet. Do not paste the whole packet into chat unless the user
|
|
97
|
+
asks for it. Always include the exact approval target in the message body as a fallback.
|
|
98
|
+
</p>
|
|
99
|
+
<pre><code>approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
100
|
+
approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
|
|
101
|
+
approve artshelf resolve missing ledger <ledger-path> ids <id...></code></pre>
|
|
102
|
+
<div class="callout" data-kind="boundary">
|
|
103
|
+
<span class="callout-label">Hard boundary</span>
|
|
104
|
+
<p>
|
|
105
|
+
Never execute from a read-only preview id. Never generate a fresh plan and
|
|
106
|
+
execute it in the same step. After any approved action, verify quiet with
|
|
107
|
+
<code>artshelf review --all --json</code>.
|
|
108
|
+
</p>
|
|
109
|
+
</div>
|
|
110
|
+
</section>
|
|
111
|
+
</article>
|
|
112
|
+
<footer class="pager" id="pager"></footer>
|
|
113
|
+
</main>
|
|
114
|
+
|
|
115
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
116
|
+
</div>
|
|
117
|
+
|
|
118
|
+
<footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
|
|
119
|
+
</body>
|
|
120
|
+
</html>
|
package/docs/agent-usage.html
CHANGED
|
@@ -3,329 +3,120 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
-
<title>
|
|
7
|
-
<meta name="description" content="How agents
|
|
6
|
+
<title>Agent usage · Artshelf</title>
|
|
7
|
+
<meta name="description" content="How agents use Artshelf safely: Create, Monitor, Review, Clean.">
|
|
8
|
+
<script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
8
12
|
<link rel="stylesheet" href="site.css">
|
|
9
|
-
<script src="
|
|
13
|
+
<script src="site.js" defer></script>
|
|
10
14
|
</head>
|
|
11
|
-
<body>
|
|
12
|
-
<
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
<button class="
|
|
16
|
-
<
|
|
17
|
-
<
|
|
18
|
-
|
|
19
|
-
<a href="
|
|
20
|
-
<
|
|
21
|
-
|
|
15
|
+
<body data-page="agent-usage.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
|
26
|
+
<svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
|
27
|
+
</button>
|
|
22
28
|
</div>
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
<a href="agent-usage.html" aria-current="page">Agent usage</a>
|
|
26
|
-
<a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">Agent skill</a>
|
|
27
|
-
</div>
|
|
28
|
-
<div class="nav-section">
|
|
29
|
-
<p class="nav-section-title">Reference</p>
|
|
30
|
-
<a href="reference.html">CLI reference</a>
|
|
31
|
-
<a href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
32
|
-
</div>
|
|
33
|
-
</div>
|
|
34
|
-
</nav>
|
|
35
|
-
|
|
36
|
-
<div class="docs-content">
|
|
37
|
-
<header class="page-top">
|
|
38
|
-
<div class="wrap">
|
|
39
|
-
<nav class="breadcrumbs" aria-label="Breadcrumbs"><a href="index.html">Docs</a><span>/</span><span>Agent usage</span></nav>
|
|
40
|
-
<div class="hero">
|
|
41
|
-
<div>
|
|
42
|
-
<p class="eyebrow">For local agents and automation</p>
|
|
43
|
-
<h1>Register artifacts while intent is fresh.</h1>
|
|
44
|
-
<p class="lede">
|
|
45
|
-
Agents should use Artshelf when temporary files need accountability, restart
|
|
46
|
-
context, or later human review. Source files and cheap build outputs stay out.
|
|
47
|
-
</p>
|
|
48
|
-
</div>
|
|
49
|
-
<div class="terminal">
|
|
50
|
-
<div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>agent contract</span></div>
|
|
51
|
-
<pre><code>$ artshelf put <path> \
|
|
52
|
-
--reason "<why this exists>" \
|
|
53
|
-
--ttl 3d \
|
|
54
|
-
--kind run-artifact \
|
|
55
|
-
--cleanup review \
|
|
56
|
-
--owner agent \
|
|
57
|
-
--label <project> \
|
|
58
|
-
--json</code></pre>
|
|
59
|
-
</div>
|
|
60
|
-
</div>
|
|
61
|
-
</div>
|
|
62
|
-
</header>
|
|
63
|
-
|
|
64
|
-
<main class="wrap">
|
|
65
|
-
<article>
|
|
66
|
-
<section>
|
|
67
|
-
<h2>Registration Trigger</h2>
|
|
68
|
-
<p>
|
|
69
|
-
Treat Artshelf as a finalization check, not an optional cleanup habit. Before an agent reports a task as done,
|
|
70
|
-
it should check whether the task created, copied,
|
|
71
|
-
exported, quarantined, backed up, or preserved any non-source file or directory
|
|
72
|
-
that may outlive the current command.
|
|
73
|
-
</p>
|
|
74
|
-
<p>
|
|
75
|
-
Register eligible artifacts immediately. If an eligible artifact is skipped,
|
|
76
|
-
state the reason: source-controlled, regeneratable, secret-bearing, already
|
|
77
|
-
tracked by another durable ledger, or explicitly not retained by request.
|
|
78
|
-
</p>
|
|
79
|
-
</section>
|
|
80
|
-
|
|
81
|
-
<section>
|
|
82
|
-
<h2>Install Behavior</h2>
|
|
83
|
-
<p>
|
|
84
|
-
If <code>artshelf</code> is not installed, prefer the package-manager install
|
|
85
|
-
when available and verify the CLI before registering artifacts.
|
|
86
|
-
</p>
|
|
87
|
-
<pre><code>npm install -g artshelf
|
|
88
|
-
artshelf --version
|
|
89
|
-
artshelf doctor</code></pre>
|
|
90
|
-
<pre><code>pnpm add -g artshelf
|
|
91
|
-
artshelf --version
|
|
92
|
-
artshelf doctor</code></pre>
|
|
93
|
-
<p>
|
|
94
|
-
For source installs, ask where the user wants the repo cloned before setup.
|
|
95
|
-
Use the local clone, build, and <code>npm link</code> path. Do not create a
|
|
96
|
-
custom shim.
|
|
97
|
-
</p>
|
|
98
|
-
<pre><code>git clone https://github.com/calvinnwq/artshelf.git "$ARTSHELF_REPO"
|
|
99
|
-
cd "$ARTSHELF_REPO"
|
|
100
|
-
corepack enable
|
|
101
|
-
pnpm install --frozen-lockfile
|
|
102
|
-
pnpm run build
|
|
103
|
-
npm link
|
|
104
|
-
artshelf --version
|
|
105
|
-
artshelf doctor</code></pre>
|
|
106
|
-
</section>
|
|
107
|
-
|
|
108
|
-
<section>
|
|
109
|
-
<h2>Use Artshelf For</h2>
|
|
110
|
-
<div class="grid">
|
|
111
|
-
<div class="card"><h3>Backups</h3><p>Rollback copies, pre-edit snapshots, migration backups, and quarantine folders.</p></div>
|
|
112
|
-
<div class="card"><h3>Evidence</h3><p>Debug output directories, generated reports, logs, and live-smoke artifacts.</p></div>
|
|
113
|
-
<div class="card"><h3>Long runs</h3><p>Workflow artifacts a future agent might need to resume, review, or clean up.</p></div>
|
|
114
|
-
</div>
|
|
115
|
-
</section>
|
|
116
|
-
|
|
117
|
-
<section>
|
|
118
|
-
<h2>Skip Artshelf For</h2>
|
|
119
|
-
<ul>
|
|
120
|
-
<li>Source files that belong in git.</li>
|
|
121
|
-
<li>Build outputs and dependency caches that can be regenerated cheaply.</li>
|
|
122
|
-
<li>Secrets, credential dumps, or private tokens.</li>
|
|
123
|
-
<li>Artifacts already owned by a more specific durable workflow ledger.</li>
|
|
124
|
-
</ul>
|
|
125
|
-
</section>
|
|
126
|
-
|
|
127
|
-
<section>
|
|
128
|
-
<h2>Idempotent Lookup</h2>
|
|
129
|
-
<p>
|
|
130
|
-
Integrations should query the ledger before creating another record for the same
|
|
131
|
-
artifact. <code>find</code> and <code>get</code> are read-only; they never move,
|
|
132
|
-
resolve, or delete files.
|
|
133
|
-
</p>
|
|
134
|
-
<pre><code>artshelf find --path <path> --owner <agent-or-runtime> --label <task-or-run-id> --json
|
|
135
|
-
artshelf get <id> --json</code></pre>
|
|
136
|
-
<p>
|
|
137
|
-
<code>find</code> requires at least one selector. Multiple labels are an all-label
|
|
138
|
-
match. If it returns a record, reuse that Artshelf id; otherwise call
|
|
139
|
-
<code>artshelf put</code> and record the new id.
|
|
140
|
-
</p>
|
|
141
|
-
</section>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
142
31
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
<p>
|
|
146
|
-
Artshelf keeps a user-level registry at `~/.artshelf/ledgers.json` so one CLI can
|
|
147
|
-
review all known ledgers without moving project records into one global file.
|
|
148
|
-
<code>put</code> registers the ledger it writes to.
|
|
149
|
-
</p>
|
|
150
|
-
<pre><code>artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo
|
|
151
|
-
artshelf ledgers list --json
|
|
152
|
-
artshelf review --all --json
|
|
153
|
-
artshelf status --all --json
|
|
154
|
-
artshelf find --all --owner <agent-or-runtime> --json
|
|
155
|
-
artshelf trash list --all --json</code></pre>
|
|
156
|
-
<p>
|
|
157
|
-
Renamed installs before <code>0.5.0</code> used <code>.shelf</code> paths. For migration,
|
|
158
|
-
copy the old ledger directories into <code>.artshelf</code>, rewrite registry entries,
|
|
159
|
-
validate the new registry, and keep the <code>.shelf</code> copies until rollback is no
|
|
160
|
-
longer needed.
|
|
161
|
-
</p>
|
|
162
|
-
<p>
|
|
163
|
-
<code>artshelf ledgers list --json</code> validates each registered ledger and reports
|
|
164
|
-
ok/missing/invalid status with entry and warning/error counts, so agents can detect
|
|
165
|
-
stale registry entries without a separate validate pass; add <code>--plain</code> for a
|
|
166
|
-
fast listing that skips validation. <code>artshelf review --all --json</code> returns an
|
|
167
|
-
aggregate triage summary and the next safe action next to the per-ledger detail.
|
|
168
|
-
</p>
|
|
169
|
-
<p>Use global cleanup dry-run when you want Artshelf to write cleanup plans for registered ledgers with cleanup entries, without moving files.</p>
|
|
170
|
-
<pre><code>artshelf cleanup --dry-run --all --json</code></pre>
|
|
171
|
-
<div class="note">
|
|
172
|
-
<code>--all</code> is for discovery and review. Cleanup execution remains
|
|
173
|
-
ledger-specific and requires a reviewed plan id for that ledger.
|
|
174
|
-
</div>
|
|
175
|
-
<p>If the executable cleanup entries have not changed, dry-run reuses the existing plan id and refreshes the same plan file instead of creating duplicate plans.</p>
|
|
176
|
-
</section>
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
177
34
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
<li>Present a decision packet instead of raw counts. Include registry health, affected ledgers, due/manual-review/missing-path counts, executable entries, skipped entries, refused entries, trashed record counts and ages, purge dry-run plan ids/skipped entries, and the next safe action.</li>
|
|
188
|
-
<li>Classify each candidate as <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
|
|
189
|
-
<li>If cleanup execution is appropriate, generate or reuse a dry-run plan, then ask for explicit approval naming the ledger path and reviewed plan id.</li>
|
|
190
|
-
<li>For trashed records, require a separate reviewed purge plan before physical deletion.</li>
|
|
191
|
-
<li>After approved cleanup execute, trash purge, or resolve, verify quiet with <code>artshelf review --all --json</code>, plus <code>artshelf trash list --ledger <ledger-path> --json</code> and purge receipt evidence after purge, or explain what remains.</li>
|
|
192
|
-
</ol>
|
|
193
|
-
<pre><code>artshelf trash list --ledger <ledger-path>
|
|
194
|
-
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
|
|
195
|
-
artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json</code></pre>
|
|
196
|
-
<pre><code>approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
197
|
-
approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id></code></pre>
|
|
198
|
-
<div class="note">
|
|
199
|
-
Never execute from a read-only preview id. Never generate a fresh plan and execute
|
|
200
|
-
it in the same step. <code>trash</code> moves artifacts into Artshelf trash; physical
|
|
201
|
-
delete requires a separate reviewed trash purge plan.
|
|
202
|
-
</div>
|
|
203
|
-
</section>
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">04</span>Agents · Overview</p>
|
|
38
|
+
<h1>Create, monitor, review, clean.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
An agent's whole relationship with Artshelf fits in four stages. Each stage
|
|
41
|
+
has its own page with the exact commands; this page is the contract that
|
|
42
|
+
ties them together.
|
|
43
|
+
</p>
|
|
204
44
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
45
|
+
<section>
|
|
46
|
+
<h2>Workflow summary</h2>
|
|
47
|
+
<div class="ledger">
|
|
48
|
+
<a class="ledger-row" href="agent-create.html">
|
|
49
|
+
<span class="n">4.1</span>
|
|
50
|
+
<span class="stage">Create</span>
|
|
51
|
+
<span class="what"><span class="cmdline">artshelf put <path> --reason <why> --ttl <ttl></span>Register a temporary file while you still remember why it exists, or state the reason for skipping it.</span>
|
|
52
|
+
</a>
|
|
53
|
+
<a class="ledger-row" href="agent-monitor.html">
|
|
54
|
+
<span class="n">4.2</span>
|
|
55
|
+
<span class="stage">Monitor</span>
|
|
56
|
+
<span class="what"><span class="cmdline">artshelf review --all --json</span>Check the shelf on a schedule with read-only commands, and stay quiet when everything is clear.</span>
|
|
57
|
+
</a>
|
|
58
|
+
<a class="ledger-row" href="agent-review.html">
|
|
59
|
+
<span class="n">4.3</span>
|
|
60
|
+
<span class="stage">Review</span>
|
|
61
|
+
<span class="what"><span class="cmdline">artshelf cleanup --dry-run --json</span>Preview cleanup, then turn the output into an <code>ArtshelfReviewReport</code> decision packet a human can approve.</span>
|
|
62
|
+
</a>
|
|
63
|
+
<a class="ledger-row" href="agent-clean.html">
|
|
64
|
+
<span class="n">4.4</span>
|
|
65
|
+
<span class="stage">Clean</span>
|
|
66
|
+
<span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id <id></span>Run the one plan the human approved, clear old trash with its own reviewed purge plan, resolve confirmed ids, and verify the next review is quiet.</span>
|
|
67
|
+
</a>
|
|
68
|
+
</div>
|
|
69
|
+
<p>
|
|
70
|
+
Trash rides the same loop. Monitor lists what sits in Artshelf trash,
|
|
71
|
+
Review previews an age-based purge plan, and Clean executes only the
|
|
72
|
+
reviewed purge plan id. Clearing trash never piggybacks on the cleanup
|
|
73
|
+
plan that trashed the file.
|
|
74
|
+
</p>
|
|
75
|
+
</section>
|
|
220
76
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
<pre><code>artshelf cleanup --dry-run --json
|
|
230
|
-
artshelf cleanup --dry-run --all --json</code></pre>
|
|
231
|
-
<pre><code>artshelf cleanup --execute --plan-id <id></code></pre>
|
|
232
|
-
<pre><code>artshelf trash list --ledger <ledger-path> --json
|
|
233
|
-
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
|
|
234
|
-
artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json</code></pre>
|
|
235
|
-
<div class="note">
|
|
236
|
-
Execution is approval-only: no daemon, no auto-execute, no global execute, and no
|
|
237
|
-
fresh-plan-then-execute shortcut. Cleanup execution needs explicit human approval
|
|
238
|
-
for the reviewed plan id. Trash list and purge dry-run are review steps; trash
|
|
239
|
-
purge execution needs separate approval naming the ledger and reviewed purge plan
|
|
240
|
-
id. Execution writes a receipt and updates touched ledger records to `trashed`,
|
|
241
|
-
`review-required`, or `cleanup-refused`. <code>cleanup=delete</code> stays refused
|
|
242
|
-
instead of silently deleting files; physical deletion requires a separate reviewed
|
|
243
|
-
trash purge plan. Artshelf records generated plans and receipts as `owner=artshelf`
|
|
244
|
-
artifacts.
|
|
245
|
-
</div>
|
|
246
|
-
<p>
|
|
247
|
-
Agents may mark a ledger record manually resolved when the user confirms the
|
|
248
|
-
artifact was inspected, is already missing, or is no longer needed.
|
|
249
|
-
</p>
|
|
250
|
-
<pre><code>artshelf resolve <id> --status resolved --reason <text></code></pre>
|
|
251
|
-
<p>
|
|
252
|
-
Use a specific reason. <code>resolve</code> only updates the ledger; it does not
|
|
253
|
-
move or delete files. Resolved records stop reappearing in future due and
|
|
254
|
-
dry-run cleanup output while remaining visible through
|
|
255
|
-
<code>artshelf list --status resolved</code>.
|
|
256
|
-
</p>
|
|
257
|
-
</section>
|
|
77
|
+
<section>
|
|
78
|
+
<h2>Operating principles</h2>
|
|
79
|
+
<dl class="def-rows">
|
|
80
|
+
<div><dt>agents remember</dt><dd>use the portable skill so final, status, and handoff turns check artifacts</dd></div>
|
|
81
|
+
<div><dt>crons only read</dt><dd>scheduled jobs may validate, review, dry-run, and report, but never execute</dd></div>
|
|
82
|
+
<div><dt>humans approve</dt><dd>mutation needs exact approval targets: ledger path, reviewed plan id, or record id list</dd></div>
|
|
83
|
+
</dl>
|
|
84
|
+
</section>
|
|
258
85
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
</
|
|
266
|
-
<
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
<code>artshelf status --all --json</code> for a compact cron summary.
|
|
277
|
-
</p>
|
|
278
|
-
<pre><code>artshelf doctor --json
|
|
279
|
-
artshelf status --all --json</code></pre>
|
|
280
|
-
<p>
|
|
281
|
-
Scheduled cleanup and trash purge dry-runs may write plan files for later review
|
|
282
|
-
when entries exist, but must not move or delete files. Matching cleanup dry-runs
|
|
283
|
-
reuse the existing plan id and refresh the plan timestamp.
|
|
284
|
-
</p>
|
|
285
|
-
<pre><code>artshelf cleanup --dry-run --json
|
|
286
|
-
artshelf cleanup --dry-run --all --json
|
|
287
|
-
artshelf trash list --ledger <ledger-path> --json
|
|
288
|
-
artshelf trash list --all --json
|
|
289
|
-
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json</code></pre>
|
|
290
|
-
<p>
|
|
291
|
-
Reports should include the ledger path, due/manual-review/missing-path counts,
|
|
292
|
-
cleanup dry-run plan id, executable entries, skipped entries, and refused entries.
|
|
293
|
-
Trash reports may use <code>artshelf trash list --all --json</code> to discover
|
|
294
|
-
trashed records across registered ledgers, then include trashed record counts
|
|
295
|
-
and target ages. Run purge dry-runs only for an explicit ledger and report
|
|
296
|
-
any plan id, matching entries, and skipped entries.
|
|
297
|
-
Stay quiet when nothing needs attention unless a regular summary was requested.
|
|
298
|
-
</p>
|
|
299
|
-
<div class="note">
|
|
300
|
-
Use explicit ledger paths for scheduled checks. Do not scan arbitrary filesystem
|
|
301
|
-
locations for ledgers unless the user opted into that discovery scope. Never
|
|
302
|
-
schedule cleanup execution or trash purge execution; scheduled jobs may only
|
|
303
|
-
dry-run and report plans for later human review.
|
|
304
|
-
</div>
|
|
305
|
-
</section>
|
|
86
|
+
<section>
|
|
87
|
+
<h2>The mental model</h2>
|
|
88
|
+
<ul class="boundary-list">
|
|
89
|
+
<li>
|
|
90
|
+
<span class="stamp readonly">Green path</span>
|
|
91
|
+
<span>Artifact is due, the dry-run plan is reviewed, and the approval target is exact.</span>
|
|
92
|
+
</li>
|
|
93
|
+
<li>
|
|
94
|
+
<span class="stamp approval">Review first</span>
|
|
95
|
+
<span>Artifact needs a human look, a retention change, or a keep/snooze decision.</span>
|
|
96
|
+
</li>
|
|
97
|
+
<li>
|
|
98
|
+
<span class="stamp refused">Blocked</span>
|
|
99
|
+
<span>Registry is stale, a path is suspicious, or the action would delete without a purge plan.</span>
|
|
100
|
+
</li>
|
|
101
|
+
</ul>
|
|
102
|
+
</section>
|
|
306
103
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
104
|
+
<section>
|
|
105
|
+
<h2>Portable skill</h2>
|
|
106
|
+
<p>
|
|
107
|
+
The repo ships a portable skill at
|
|
108
|
+
<a href="https://github.com/calvinnwq/artshelf/tree/main/skills/artshelf">skills/artshelf</a>.
|
|
109
|
+
Agents that support local skills can copy or reference the whole directory directly,
|
|
110
|
+
including the bundled report renderer, schema, and example copies.
|
|
111
|
+
</p>
|
|
112
|
+
</section>
|
|
113
|
+
</article>
|
|
114
|
+
<footer class="pager" id="pager"></footer>
|
|
115
|
+
</main>
|
|
316
116
|
|
|
317
|
-
|
|
318
|
-
<h2>Portable Skill</h2>
|
|
319
|
-
<p>
|
|
320
|
-
The repo ships a portable skill at
|
|
321
|
-
<a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">skills/artshelf/SKILL.md</a>.
|
|
322
|
-
Agents that support local skills can copy or reference it directly.
|
|
323
|
-
</p>
|
|
324
|
-
</section>
|
|
325
|
-
</article>
|
|
326
|
-
</main>
|
|
327
|
-
<footer class="site-footer"><div class="wrap">Artshelf docs · <a href="reference.html">Next: CLI reference</a></div></footer>
|
|
328
|
-
</div>
|
|
117
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
329
118
|
</div>
|
|
119
|
+
|
|
120
|
+
<footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
|
|
330
121
|
</body>
|
|
331
122
|
</html>
|