"architecture", "api", "database", "authentication", "deployment", "infrastructure", "configuration", "testing",

"convention", "pattern", "bug", "gotcha", "decision", "dependency", "security", "performance", "domain", "workflow",

"note", "discovery",

"SESSION_START", "SESSION_STOP", "PROMPT", "PLAN", "PLAN_UPDATE", "FILE_READ", "FILE_EDIT", "FILE_CREATE",

"FILE_DELETE", "COMMAND", "COMMAND_RESULT", "TEST", "TEST_RESULT", "ERROR", "DISCOVERY", "DECISION", "NOTE",

"AGENT_MESSAGE", "HANDOFF", "HANDOFF_RECEIVED", "TASK_START", "TASK_UPDATE", "TASK_COMPLETE",

re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(-----END [A-Z ]*PRIVATE KEY-----|$)"),

re.compile(r"\b(AKIA|ASIA)[0-9A-Z]{16}\b"),

re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),

re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"),

re.compile(r"\bsk-(ant-)?[A-Za-z0-9_-]{16,}\b"),

re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}\b"),

re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b"),

re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b"), # JWTs

re.compile(r"(?i)\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{12,}"),

re.compile(r"(?i)\b[a-z][a-z0-9+.-]*://[^\s:/@]+:[^\s@]+@"), # credentials in URLs

"""Remove secrets before anything is stored or indexed."""

for rx in _SECRETS:

text = rx.sub("[REDACTED]", text)

conn = sqlite3.connect(path(), timeout=5)

conn.row_factory = sqlite3.Row

conn.execute("PRAGMA foreign_keys = ON")

conn.execute("PRAGMA journal_mode = WAL")

"""Create the schema (idempotent, additive)."""

with _connect() as conn:

conn.executescript(

"""

)

try:

conn.execute("CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(kind UNINDEXED, ref_id UNINDEXED, project_id UNINDEXED, title, body)")

_fts[:] = [True]

except sqlite3.OperationalError: # ponytail: no FTS5 in this sqlite build; recall falls back to LIKE

if not _fts or not _fts[0]:

return

conn.execute("DELETE FROM search WHERE kind = ? AND ref_id = ?", (kind, ref_id))

try:

r = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True, timeout=3,

creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0)

return r.stdout.strip() if r.returncode == 0 else ""

except (OSError, subprocess.SubprocessError):

"""Branch, commit, dirty flag and changed files; empty when the folder isn't a git checkout."""

root = Path(root)

branch = _git(root, "rev-parse", "--abbrev-ref", "HEAD")

if not branch:

return {}

changed = [line[3:] for line in _git(root, "status", "--porcelain").splitlines() if len(line) > 3]

return {"branch": branch, "commit": _git(root, "rev-parse", "--short", "HEAD"), "dirty": bool(changed),

"""The context project for a folder (registered on first use) or an existing one by name."""

init()

with _connect() as conn:

if name:

row = conn.execute("SELECT * FROM projects WHERE name = ? COLLATE NOCASE ORDER BY updated_at DESC", (name,)).fetchone()

return dict(row) if row else None

if not cwd:

return None

here = Path(cwd).resolve()

# the deepest known project containing cwd: a shelldeck project, else one registered before

try:

known = [(Path(p["path"]), p["name"]) for p in db.list_projects()]

except sqlite3.Error: # no shelldeck database (CLI-only use): context still works by folder

known = []

known += [(Path(r["path"]), r["name"]) for r in conn.execute("SELECT path, name FROM projects")]

hits = [(p, n) for p, n in known if here == p.resolve() or p.resolve() in here.parents]

if hits:

root, label = max(hits, key=lambda h: len(str(h[0])))

else:

top = _git(here, "rev-parse", "--show-toplevel")

root = Path(top) if top else here

label = root.name or str(root)

key = str(root.resolve())

row = conn.execute("SELECT * FROM projects WHERE path = ?", (key,)).fetchone()

if row:

return dict(row)

now = _now()

row = {"id": _id("p"), "name": label, "path": key, "repository": _git(root, "remote", "get-url", "origin") or None,

"created_at": now, "updated_at": now}

conn.execute("INSERT INTO projects VALUES (:id, :name, :path, :repository, :created_at, :updated_at)", row)

init()

with _connect() as conn:

rows = [dict(r) for r in conn.execute("SELECT * FROM projects ORDER BY updated_at DESC")]

for r in rows:

r["knowledge"] = conn.execute("SELECT COUNT(*) FROM knowledge WHERE project_id = ? AND status != 'INVALIDATED'", (r["id"],)).fetchone()[0]

t = conn.execute("SELECT title, status FROM tasks WHERE project_id = ? ORDER BY updated_at DESC", (r["id"],)).fetchone()

r["task"] = dict(t) if t else None

session_id: str | None = None, importance: int = 1) -> None:

if type_ not in EVENT_TYPES:

raise ValueError("invalid_event_type")

with _connect() as conn:

conn.execute("INSERT INTO events (project_id, session_id, agent, type, timestamp, payload, importance) VALUES (?, ?, ?, ?, ?, ?, ?)",

(project["id"], session_id, agent, type_, _now(), _payload(payload), max(1, min(int(importance), 5))))

# compaction: keep the newest MAX_EVENTS; important ones (>= 3) survive longer

conn.execute("DELETE FROM events WHERE project_id = ? AND importance < 3 AND id NOT IN "

"(SELECT id FROM events WHERE project_id = ? ORDER BY id DESC LIMIT ?)", (project["id"], project["id"], MAX_EVENTS))

try:

return hashlib.sha256(file.read_bytes()).hexdigest()[:16]

except OSError:

files: list[str] | None = None, agent: str | None = None, session_id: str | None = None, scope: str = "PROJECT") -> dict:

"""Store a fact/discovery. The same fact (by normalized wording) in the same project is updated, not duplicated;

content = _clean(text)

if not content:

raise ValueError("text_required")

if type_ not in KNOWLEDGE_TYPES:

raise ValueError("invalid_type")

scope = scope.upper() if scope.upper() in ("GLOBAL", "PROJECT") else "PROJECT"

title = _clean(title, 120) or content.splitlines()[0][:80]

norm, now = _norm(content), _now()

with _connect() as conn:

row = conn.execute("SELECT * FROM knowledge WHERE project_id = ? AND norm = ?", (project["id"], norm)).fetchone()

if row:

kid = row["id"]

conn.execute("UPDATE knowledge SET updated_at = ?, confidence = MAX(confidence, ?), status = CASE WHEN status IN ('STALE', 'INVALIDATED') THEN 'NEW' ELSE status END WHERE id = ?",

(now, CONFIDENCE.get(kind, 0.8), kid))

else:

kid = _id("k")

conn.execute("INSERT INTO knowledge (id, scope, project_id, type, topic, title, content, norm, confidence, status, created_by, session_id, created_at, updated_at)"

" VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'NEW', ?, ?, ?, ?)",

(kid, scope, project["id"], type_, _clean(topic, 60) or None, title, content, norm, CONFIDENCE.get(kind, 0.8), agent, session_id, now, now))

root = Path(project["path"])

for f in files or []:

rel = str(f).strip()

if not rel or SENSITIVE_FILE.search(rel):

continue # never reference secrets files

full = (root / rel).resolve()

if root.resolve() not in full.parents:

continue

conn.execute("DELETE FROM source_references WHERE knowledge_id = ? AND file_path = ?", (kid, rel))

conn.execute("INSERT INTO source_references (id, knowledge_id, project_id, file_path, file_hash) VALUES (?, ?, ?, ?, ?)",

(_id("s"), kid, project["id"], rel, _hash(full)))

_index(conn, "knowledge", kid, project["id"], title, f"{topic} {type_} {content}")

_touch(conn, project["id"])

record_event(project, "DISCOVERY" if kind == "discover" else "NOTE", {"knowledge": kid}, agent=agent, session_id=session_id, importance=3)

agent: str | None = None) -> dict:

title = _clean(title, 200)

if not title:

raise ValueError("title_required")

row = {"id": _id("d"), "project_id": project["id"], "title": title, "decision": _clean(decision) or title, "reason": _clean(reason) or None,

"alternatives": _clean(alternatives) or None, "consequence": _clean(consequence) or None, "created_by": agent, "created_at": _now()}

with _connect() as conn:

conn.execute(f"INSERT INTO decisions ({', '.join(row)}) VALUES ({', '.join(':' + k for k in row)})", row)

_index(conn, "decision", row["id"], project["id"], title, f"{row['decision']} {row['reason'] or ''} {row['alternatives'] or ''}")

_touch(conn, project["id"])

record_event(project, "DECISION", {"decision": row["id"]}, agent=agent, importance=4)

step: str | None = None, next_action: str | None = None, last_error: str | None = None, tests: str | None = None,

agent: str | None = None, session_id: str | None = None, git: bool = True, event: bool = True) -> dict:

"""Update the active task and the current state; a checkpoint. Only the fields given change."""

if status and status.upper() not in TASK_STATUSES:

raise ValueError("invalid_status")

now = _now()

with _connect() as conn:

t = conn.execute("SELECT * FROM tasks WHERE project_id = ? AND status NOT IN ('DONE', 'CANCELLED') ORDER BY updated_at DESC", (project["id"],)).fetchone()

if task and (not t or (t["title"] != _clean(task, 200))):

if not t:

tid = _id("t")

conn.execute("INSERT INTO tasks (id, project_id, session_id, title, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'IN_PROGRESS', ?, ?)",

(tid, project["id"], session_id, _clean(task, 200), now, now))

t = conn.execute("SELECT * FROM tasks WHERE id = ?", (tid,)).fetchone()

record_type = "TASK_START"

else:

conn.execute("UPDATE tasks SET title = ? WHERE id = ?", (_clean(task, 200), t["id"]))

record_type = "TASK_UPDATE"

else:

record_type = "TASK_UPDATE"

if t:

sets = {k: _clean(v) for k, v in (("objective", objective), ("plan", plan)) if v is not None}

if status:

sets["status"] = status.upper()

if status.upper() == "DONE":

record_type = "TASK_COMPLETE"

sets["updated_at"] = now

conn.execute(f"UPDATE tasks SET {', '.join(k + ' = ?' for k in sets)} WHERE id = ?", (*sets.values(), t["id"]))

_index(conn, "task", t["id"], project["id"], _clean(task, 200) or t["title"], f"{objective or t['objective'] or ''} {plan or t['plan'] or ''}")

cur = conn.execute("SELECT * FROM state WHERE project_id = ?", (project["id"],)).fetchone()

st = dict(cur) if cur else {"project_id": project["id"]}

for k, v in (("step", step), ("next_action", next_action), ("last_error", last_error), ("tests", tests), ("agent", agent), ("session_id", session_id)):

if v is not None:

st[k] = _clean(v, 2000) or None

if git:

st["git_json"] = json.dumps(git_state(project["path"]))

st["updated_at"] = now

cols = ["project_id", "step", "next_action", "last_error", "tests", "agent", "session_id", "git_json", "updated_at"]

conn.execute(f"INSERT OR REPLACE INTO state ({', '.join(cols)}) VALUES ({', '.join('?' for _ in cols)})", [st.get(c) for c in cols])

_touch(conn, project["id"])

if not event: # a capture-driven update (tests line, last error): the caller records its own event

return {}

record_event(project, record_type, {"step": step, "status": status}, agent=agent, session_id=session_id, importance=2)

"""Knowledge lifecycle: NEW -> VERIFIED -> STALE -> REVIEWED (or INVALIDATED). Verifying re-hashes sources."""

status = status.upper()

if status not in STATUSES:

raise ValueError("invalid_status")

k = get_knowledge(knowledge_id)

if not k:

raise LookupError("knowledge_not_found")

with _connect() as conn:

conn.execute("UPDATE knowledge SET status = ?, updated_at = ?, verified_at = CASE WHEN ? IN ('VERIFIED', 'REVIEWED') THEN ? ELSE verified_at END,"

" confidence = CASE WHEN ? = 'VERIFIED' THEN MAX(confidence, 0.95) ELSE confidence END WHERE id = ?",

(status, _now(), status, _now(), status, knowledge_id))

if status in ("VERIFIED", "REVIEWED"):

proj = conn.execute("SELECT path FROM projects WHERE id = ?", (k["project_id"],)).fetchone()

for ref in k["sources"]:

h = _hash(Path(proj["path"]) / ref["file_path"]) if proj else None

conn.execute("UPDATE source_references SET file_hash = ? WHERE knowledge_id = ? AND file_path = ?", (h, knowledge_id, ref["file_path"]))

"""Mark knowledge STALE whose source files changed or disappeared; returns the ids marked."""

init()

marked = []

with _connect() as conn:

sql = ("SELECT k.id, r.file_path, r.file_hash, p.path FROM knowledge k JOIN source_references r ON r.knowledge_id = k.id"

" JOIN projects p ON p.id = k.project_id WHERE k.status IN ('NEW', 'VERIFIED', 'REVIEWED')")

args: tuple = ()

if project:

sql += " AND k.project_id = ?"

args = (project["id"],)

for r in conn.execute(sql, args).fetchall():

if r["id"] not in marked and _hash(Path(r["path"]) / r["file_path"]) != r["file_hash"]:

marked.append(r["id"])

for kid in marked:

conn.execute("UPDATE knowledge SET status = 'STALE', updated_at = ? WHERE id = ?", (_now(), kid))

if relation not in RELATIONS:

raise ValueError("invalid_relation")

if target["id"] == project["id"]:

raise ValueError("self_relation")

with _connect() as conn:

conn.execute("INSERT OR IGNORE INTO relationships VALUES (?, 'project', ?, ?, 'project', ?)", (_id("r"), project["id"], relation, target["id"]))

with _connect() as conn:

row = conn.execute("SELECT k.*, p.name AS project FROM knowledge k LEFT JOIN projects p ON p.id = k.project_id WHERE k.id = ?", (knowledge_id,)).fetchone()

if not row:

return None

out = dict(row)

out.pop("norm", None)

out["sources"] = [dict(r) for r in conn.execute("SELECT file_path, file_hash FROM source_references WHERE knowledge_id = ?", (knowledge_id,))]

with _connect() as conn:

ids = [r[0] for r in conn.execute("SELECT id FROM knowledge WHERE project_id = ? AND status != 'INVALIDATED' ORDER BY confidence DESC, updated_at DESC LIMIT ?",

(project["id"], limit))]

with _connect() as conn:

rows = conn.execute(

"SELECT r.relation, p.name, p.id FROM relationships r JOIN projects p ON p.id = r.target_id WHERE r.source_type = 'project' AND r.source_id = ?"

" UNION SELECT r.relation || ' (reverse)', p.name, p.id FROM relationships r JOIN projects p ON p.id = r.source_id WHERE r.target_type = 'project' AND r.target_id = ?",

(project["id"], project["id"]))

"""Ranked knowledge and decisions across every project; the current project and its related projects rank first.

init()

q = _fts_query(" ".join([query, *extra]), 30 if extra else 12)

if not q:

return []

related = {r["id"] for r in related_projects(project)} if project else set()

with _connect() as conn:

if _fts[0]:

rows = conn.execute("SELECT kind, ref_id, project_id, bm25(search) AS score FROM search WHERE search MATCH ? ORDER BY score LIMIT ?",

(q, limit * 4)).fetchall()

hits = [(r["kind"], r["ref_id"], r["project_id"], -r["score"]) for r in rows]

else:

like = f"%{query.lower()}%"

hits = [("knowledge", r["id"], r["project_id"], 1.0) for r in conn.execute(

"SELECT id, project_id FROM knowledge WHERE lower(content) LIKE ? OR lower(title) LIKE ? LIMIT ?", (like, like, limit * 4))]

names = {r["id"]: r["name"] for r in conn.execute("SELECT id, name FROM projects")}

out = []

for kind, ref, pid, score in hits:

boost = 1.5 if project and pid == project["id"] else 1.25 if pid in related else 1.0

if kind == "knowledge":

k = get_knowledge(ref)

if not k or k["status"] == "INVALIDATED" or (k["status"] == "STALE" and not include_stale):

continue

out.append({"kind": "knowledge", "id": ref, "project": names.get(pid), "type": k["type"], "title": k["title"], "snippet": k["content"][:400],

"status": k["status"], "confidence": k["confidence"], "sources": [s["file_path"] for s in k["sources"]],

"created_by": k["created_by"], "updated_at": k["updated_at"], "_score": score * boost * k["confidence"]})

elif kind == "decision":

with _connect() as conn:

d = conn.execute("SELECT * FROM decisions WHERE id = ?", (ref,)).fetchone()

if d:

out.append({"kind": "decision", "id": ref, "project": names.get(pid), "type": "decision", "title": d["title"], "snippet": (d["decision"] or "")[:400],

"status": "DECIDED", "confidence": 0.9, "sources": [], "created_by": d["created_by"], "updated_at": d["created_at"], "_score": score * boost * 0.9})

elif kind == "task":

with _connect() as conn:

t = conn.execute("SELECT * FROM tasks WHERE id = ?", (ref,)).fetchone()

if t:

out.append({"kind": "task", "id": ref, "project": names.get(pid), "type": "task", "title": t["title"], "snippet": (t["objective"] or "")[:400],

"status": t["status"], "confidence": 0.7, "sources": [], "created_by": None, "updated_at": t["updated_at"], "_score": score * boost * 0.7})

out.sort(key=lambda r: r["_score"], reverse=True)

out = out[:limit]

top = out[0]["_score"] if out and out[0]["_score"] > 0 else 1

for i, r in enumerate(out):

score = r.pop("_score")

# bm25 is near zero on a tiny index; fall back to rank order so a match never reads as 0

r["relevance"] = round(score / top, 2) if score > 0 and score / top >= 0.05 else round(1 / (i + 2), 2)

project: dict

task: dict | None = None

state: dict | None = None

memory: list[dict] = field(default_factory=list)

decisions: list[dict] = field(default_factory=list)

handoff: dict | None = None

related_projects: list[dict] = field(default_factory=list)

relevant_knowledge: list[dict] = field(default_factory=list)

git_state: dict = field(default_factory=dict)

recent_events: list[dict] = field(default_factory=list)

stale: list[str] = field(default_factory=list)

def to_dict(self) -> dict:

"""Everything an agent needs to continue, as a ContextPackage dict (plus `text`, the budgeted rendering)."""

with _connect() as conn:

t = conn.execute("SELECT * FROM tasks WHERE project_id = ? ORDER BY CASE WHEN status IN ('DONE', 'CANCELLED') THEN 1 ELSE 0 END, updated_at DESC",

(project["id"],)).fetchone()

st = conn.execute("SELECT * FROM state WHERE project_id = ?", (project["id"],)).fetchone()

state = dict(st) if st else None

git = json.loads(state.pop("git_json") or "{}") if state else {}

stale = check_stale(project)

mem = memory(project, 30)

pkg = ContextPackage(project={k: project[k] for k in ("id", "name", "path")}, task=dict(t) if t else None, state=state, memory=mem,

decisions=decisions(project, 10), handoff=handoff, related_projects=related_projects(project),

relevant_knowledge=[r for r in recall(query, project, 6) if r["project"] != project["name"]] if query else [],

git_state=git, recent_events=recent_events(project, 10), stale=[k["title"] for k in mem if k["status"] == "STALE"] or stale)

out = pkg.to_dict()

out["text"] = render(pkg)

out, used = [], 0

for line in lines:

if used + len(line) > budget:

out.append(" ... (more: sd memory / sd recall)")

break

out.append(line)

used += len(line) + 1

"""Compact text for an agent, each section held to its share of the budget (relevance order already applied)."""

share = {k: int(budget * v) for k, v in (shares or BUDGET).items()}

out = ["SHELLDECK CONTEXT", f"Project: {pkg.project['name']} ({pkg.project['path']})"]

if pkg.task:

t = pkg.task

out += _cut([f"Task [{t['status']}]: {t['title']}"] + ([f" Objective: {t['objective']}"] if t.get("objective") else [])

+ ([f" Plan: {t['plan']}"] if t.get("plan") else []), share["task"])

s = pkg.state or {}

lines = [f" {label}: {s[k]}" for k, label in (("step", "Current step"), ("next_action", "Next action"), ("last_error", "Last error"),

("tests", "Tests"), ("agent", "Last agent"), ("updated_at", "Updated")) if s.get(k)]

if pkg.git_state:

g = pkg.git_state

lines.append(f" Git: {g.get('branch')} @ {g.get('commit')}{' (dirty: ' + ', '.join(g.get('changed', [])[:8]) + ')' if g.get('dirty') else ''}")

if lines:

out += ["State:"] + _cut(lines, share["state"])

if pkg.handoff:

h = pkg.handoff

out += ["Hand-off:"] + _cut([f" {h.get('id')} from {h.get('from_nick') or 'user'} [{h.get('status')}]: {' '.join(str(h.get('task', '')).split())}"], share["handoff"])

if pkg.memory or pkg.decisions:

lines = [f" - [{k['id']}{' STALE' if k['status'] == 'STALE' else ''}] {' '.join(k['content'].split())}" for k in pkg.memory]

lines += [f" - decision: {d['title']}" + (f" (because {d['reason']})" if d.get("reason") else "") for d in pkg.decisions]

out += ["Memory and decisions:"] + _cut(lines, share["memory"])

if pkg.related_projects or pkg.relevant_knowledge:

lines = [f" - {r['relation']}: {r['name']}" for r in pkg.related_projects]

lines += [f" - [{r['project']}] {r['title']}: {' '.join(r['snippet'].split())[:200]}" for r in pkg.relevant_knowledge]

out += ["Related (reference only; adapt, don't copy):"] + _cut(lines, share["knowledge"])

if pkg.recent_events:

out += ["Recent events:"] + _cut([f" {e['timestamp']} {e['type']}{' by ' + e['agent'] if e.get('agent') else ''}" for e in pkg.recent_events], share["events"])

if pkg.stale:

out.append("Warning: may be stale (source changed): " + ", ".join(pkg.stale[:5]))

"""Write STATE.md, TASK.md, MEMORY.md and DECISIONS.md under <project>/.shelldeck/ from SQLite."""

folder = Path(project["path"]) / ".shelldeck"

if not Path(project["path"]).is_dir():

return

folder.mkdir(exist_ok=True)

ignore = folder / ".gitignore"

if not ignore.exists():

ignore.write_text("*\n", encoding="utf-8")

ctx = project_context(project)

t, s, g = ctx["task"] or {}, ctx["state"] or {}, ctx["git_state"]

head = "<!-- generated by shelldeck from its context database; edit with sd remember/decide/task -->\n"

state = [head, "# Current State\n"]

for k, label in (("step", "Current Step"), ("next_action", "Next Action"), ("last_error", "Last Error"), ("tests", "Tests"),

("agent", "Active Agent"), ("session_id", "Session"), ("updated_at", "Last Updated")):

if s.get(k):

state.append(f"## {label}\n\n{s[k]}\n")

if g:

state.append(f"## Git\n\nBranch: {g.get('branch')}\nCommit: {g.get('commit')}\nDirty: {str(g.get('dirty')).lower()}\n"

+ "".join(f"- {c}\n" for c in g.get("changed", [])))

task = [head, "# Task\n"] + ([f"## Objective\n\n{t.get('objective') or t['title']}\n", f"## Plan\n\n{t.get('plan') or '(none yet)'}\n",

f"## Status\n\n{t['status']}\n"] if t else ["No active task.\n"])

mem = [head, "# Project Memory\n"]

for k in ctx["memory"]:

src = f"\n Sources: {', '.join(x['file_path'] for x in k['sources'])}" if k["sources"] else ""

mem.append(f"- **{k['title']}** ({k['type']}, {k['status']}, {k['id']}): {k['content']}{src}\n")

dec = [head, "# Decisions\n"]

for d in decisions(project, 200):

dec.append(f"## {d['created_at'][:10]} — {d['title']}\n\n### Decision\n\n{d['decision']}\n"

+ (f"\n### Reason\n\n{d['reason']}\n" if d.get("reason") else "")

+ (f"\n### Alternatives Considered\n\n{d['alternatives']}\n" if d.get("alternatives") else "")

+ (f"\n### Consequence\n\n{d['consequence']}\n" if d.get("consequence") else ""))

for name, body in (("STATE.md", state), ("TASK.md", task), ("MEMORY.md", mem), ("DECISIONS.md", dec)):

"""One finished command or edit: an event; a test run also sets the project's Tests line; a failed command (not a

if "file" in act:

path = act["file"]

if SENSITIVE_FILE.search(path):

return

record_event(project, "FILE_CREATE" if act.get("change") == "write" else "FILE_EDIT", {"file": path}, agent=agent, session_id=session_id)

return

cmd, ok = _clean(act.get("command"), 500), bool(act.get("ok", True))

if not cmd:

return

if TEST_CMD.search(cmd):

record_event(project, "TEST_RESULT", {"command": cmd, "ok": ok}, agent=agent, session_id=session_id, importance=3)

save_state(project, tests=f"{'passed' if ok else 'FAILED'}: {cmd} ({_now()[:16].replace('T', ' ')} UTC)",

agent=agent, session_id=session_id, git=False, event=False)

elif not ok and not LOOKUP_CMD.search(cmd):

record_event(project, "ERROR", {"command": cmd}, agent=agent, session_id=session_id, importance=3)

save_state(project, last_error=f"failed: {cmd}", agent=agent, session_id=session_id, git=False, event=False)

else:

"""Close an agent run and write `.shelldeck/sessions/<id>.md` from its events (commands, tests, files, errors)."""

with _connect() as conn:

row = conn.execute("SELECT * FROM sessions WHERE id = ?", (session_id,)).fetchone()

if not row:

return None

conn.execute("UPDATE sessions SET ended_at = ?, status = 'ended' WHERE id = ?", (_now(), session_id))

events = [dict(r) for r in conn.execute("SELECT type, timestamp, payload FROM events WHERE session_id = ? ORDER BY id", (session_id,))]

record_event(project, "SESSION_STOP", {}, agent=row["agent"], session_id=session_id, importance=2)

load = [(e["type"], e["timestamp"], json.loads(e["payload"] or "{}")) for e in events]

files = sorted({p["file"] for t, _, p in load if t in ("FILE_EDIT", "FILE_CREATE") and "file" in p})

cmds = [p["command"] for t, _, p in load if t in ("COMMAND", "TEST_RESULT", "ERROR") and "command" in p]

tests = [f"{'passed' if p.get('ok') else 'FAILED'}: {p['command']}" for t, _, p in load if t == "TEST_RESULT"]

errors = [p["command"] for t, _, p in load if t == "ERROR"]

g = git_state(project["path"])

lines = [f"# Session {session_id}", "", f"Agent: {row['agent']}", f"Project: {project['name']}", f"Started: {row['started_at']}",

f"Ended: {_now()}", ""]

for title, items in (("Files changed", files), ("Commands", cmds[-40:]), ("Tests", tests[-10:]), ("Errors", errors[-10:])):

if items:

lines += [f"## {title}", "", *[f"- {i}" for i in items], ""]

if g:

lines += ["## Git", "", f"Branch: {g.get('branch')}", f"Commit: {g.get('commit')}", f"Dirty: {str(g.get('dirty')).lower()}", ""]

folder = Path(project["path"]) / ".shelldeck" / "sessions"

if not Path(project["path"]).is_dir():

return None

folder.mkdir(parents=True, exist_ok=True)

ignore = folder.parent / ".gitignore"

if not ignore.exists():

ignore.write_text("*\n", encoding="utf-8")

out = folder / f"{re.sub(r'[^A-Za-z0-9_.-]', '_', session_id)}.md"

out.write_text("\n".join(lines), encoding="utf-8")

"""`sd init`: register the folder and write `.shelldeck/` now (STATE/TASK/MEMORY/DECISIONS.md, AGENTS.md,

project = project_for(path)

if task:

save_state(project, task=task, event=True)

project_files(project)

agents_md = Path(project["path"]) / ".shelldeck" / "AGENTS.md"

if not agents_md.exists() or agents_md.read_text(encoding="utf-8", errors="replace").startswith(AGENTS_MARKER):

agents_md.write_text(AGENTS_MD, encoding="utf-8")

return {"project": project, "folder": str(Path(project["path"]) / ".shelldeck"),