diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index d6573d96c..0a671947e 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -492,6 +492,12 @@ "section": "PRDs", "body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalisation only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalises trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalisation\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgement. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalisation, and prune is _reporting_\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalogue to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalogue through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval */ }\n\nfunc New(interval time.Duration) *Curator\n\nfunc (c *Curator) Manifest() curator.Manifest {\n return curator.Manifest{Interval: c.interval, Skills: true}\n}\n\nfunc (c *Curator) Check(ctx context.Context) (bool, error) // len(skills) \u003e 0\nfunc (c *Curator) Pass(ctx context.Context, in curator.PassInput) (curator.PassResult, error)\n```\n\n`Pass` walks every skill via `Bind`'s `Skills` (the filtered\n`SkillStore` the registry already narrows to declared curators, see\n`Registry.filter`), classifying each into exactly one of:\n\n- **parse failure** -- `Action{Type: \"skill.invalid\", Reason: \"frontmatter failed to parse\"}`\n- **missing required field** -- `Action{Type: \"skill.incomplete\", Reason: \"name\" | \"description\"}`\n- **normalised** -- content changed by whitespace cleanup, written back,\n `Action{Type: \"skill.normalized\", Detail: \"\u003cname\u003e: trimmed trailing whitespace\"}`\n- **clean** -- no action recorded (a pass with nothing to report is not\n an error, and not every skill needs an entry every time)\n\nOne pass reviews every skill on disk; there is no\nper-skill \"already reviewed, skip\" state; this errs toward re-checking\nover missing a regression, and the cost is cheap (no model calls, just\nfile reads).\n\n## What we deliberately do NOT do\n\n- **No LLM-authored rewrites of skill content.** Real \"improve\" in the\n sense of better prose is out of scope until there is a review/approval\n path for autonomous content changes to something a human wrote.\n- **No automatic deletion of a skill**, however broken. `Delete` exists\n on the store for a future consumer; this curator's `Pass` never calls\n it.\n- **No dangling-tool-reference checking** (a skill's\n `metadata.archie.tools` naming a tool that no longer exists). The\n mechanism to check \"does this tool exist\" belongs to a tool registry\n this curator has no access to and shouldn't be given for this --\n `curator.ToolBuilder.Build` resolves the curator's _own_ declared\n tools, not an arbitrary existence check against skill-referenced\n names. A real fix here is a separate, better-scoped issue.\n- **No multi-root awareness.** One configured root, matching\n `loadWorkflows`'s existing resolution, not the full layered catalogue a\n chat turn sees.\n- **No new curator-specific webui or chat surface.** Activity is visible\n through the existing curator observability surface\n (`archie-core-1786637489932`) -- `/api/curators` and\n the dashboard Curators page already show any registered curator's\n recent actions.\n\n## Acceptance criteria\n\nRestated from the issue against this shape:\n\n1. Registers and runs through `curator.Registry` with no curator-specific\n special-casing in the runtime -- proven by using the existing\n `Registry.Register`/`Runtime` path, no new registry method.\n2. Its changes to skills are observable and attributable -- every write\n is preceded by an `Action` recording what changed and why, surfaced\n through the existing curator activity tracker.\n3. It operates within its declared tool set and cannot reach tools it\n did not declare -- `Manifest.Tools` is empty; nothing about this\n curator ever touches `Registrar.Tools`.\n\n## Files this change adds\n\n- `internal/infrastructure/skillcurator/store.go` -- `curator.SkillStore` adapter\n- `internal/infrastructure/skillcurator/store_test.go`\n- `internal/infrastructure/skillcurator/skillcurator.go` -- the `CuratorEngine`\n- `internal/infrastructure/skillcurator/skillcurator_test.go`\n- `internal/app/archied/bootstrap.go` -- register it in `setupCurators`, root\n resolved the same way `loadWorkflows` resolves `skillsBase`\n" }, + { + "url": "/dev/prds/soul/", + "title": "SOUL: an agent's user-authored personality", + "section": "PRDs", + "body": "# SOUL: an agent's user-authored personality\n\n**Status:** Draft\n**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;\n`docs/prds/orgs-and-access.md` for identity and org ownership.\n\n## Decision\n\nSOUL supplies an agent's name, register and warmth. It belongs to the agent's\nimmutable `IdentityID`, not its session, model, installation or container\nprofile. Rename preserves it; changing a profile does not change who acts.\nSOUL never changes attribution, credentials, grants or identity lifecycle.\n`config.AgentProfile` remains an execution environment, not another identity.\n\nUse the existing three layers: invariants, user-authored SOUL, and curator-derived\nrepresentation. Curators may propose SOUL changes but never apply them.\n\n## Files and ownership\n\nThe config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory\nof an explicitly selected config file. The default/root agent uses `SOUL.md`\ndirectly there; additional agents use `agents/\u003cidentity-id\u003e/SOUL.md`. The root is\nthe identity selected by application composition, never the initiating user or\na session's personality selection. No file creates or selects an identity.\n\nThe common case keeps a human-friendly filename; additional agents get separate\nasset directories, following `.agents/skills/\u003cname\u003e/SKILL.md` without confusing\nthese directories with `[containers.profiles.\u003cname\u003e]`. Reject display-name or\nslug directories: rename and same-name agents across orgs would require another\nname-resolution rule. Immutable IDs avoid both problems without an org directory.\n\nWhen a file-owned agent's file is absent, create the shipped default with\nexclusive creation. Never overwrite an existing file, including an empty one.\nA creation failure still permits the turn using the embedded shipped default.\nShip that document independently of `agent.ShippedPersonas`, so deleting personas\ncannot delete the fallback.\n\nResolve once at the start of every new generation:\n\n1. A stored SOUL entry for the acting identity is authoritative.\n2. Without an entry, read that identity's file again.\n3. An absent, empty, unreadable or invalid selected source uses the shipped default.\n\nThe first explicit dashboard/API save takes ownership permanently. Thereafter\nfile edits are ignored: emit one ownership notice and show the owning stored\nversion in the dashboard. Restoring the shipped default writes a stored value;\nit does not remove ownership. Refuse writes that remove an owned entry.\n\nThis ownership boundary is the design's one stateful rule. Files seed the\neditable value, not an automatic durable import. Reject seed-once import because\nit breaks next-message file editing; reject file-always-wins because it makes\ndashboard saves ineffective. Neither a restart nor an upgrade overwrites an\nowned value, following the precedence of `controlplane.AgentProfileKind` without\ncopying its startup import timing.\n\n## Prompt and failure contract\n\nKeep `archie.md.tpl`'s XML-escaped\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block before\n`\u003cinstruction_precedence\u003e`. SOUL is style reference data; the invariant sections,\ntool inventory and runtime metadata remain authoritative and uneditable.\nPreserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.\n\nAccept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds\npersonality to a small prompt contribution; count the complete rendered prompt\nin the turn's context budget and never truncate invariant sections. Bound file\nreads before decoding; reject oversize input rather than truncating instructions.\nFile and stored writes use the same validator; an invalid save leaves the stored\nversion unchanged. The shipped default must pass that validator.\n\nRead and creation errors never fail a turn. Log once per identity/source failure\nepisode, retry on the next turn, and allow a new warning after recovery. If the\nstore cannot establish whether an owned entry exists, use the shipped default,\nnot a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved\nsnapshot; edits affect the next generation without restart or SIGHUP.\n\n## Cross-layer delivery\n\n- `internal/domain/agent` owns SOUL content validation and the identity-keyed read\n contract; `internal/domain/identity` remains the actor/lifecycle authority.\n- The configuration infrastructure resolves the config directory and handles\n file discovery, exclusive default creation and bounded per-turn reads.\n Application composition resolves the acting `IdentityID` through the existing\n identity repository/bindings and supplies it to the gateway.\n- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor\n and an org-scoped document mapping identity IDs to `{text}`. Persist it through\n the State Store's existing resource/history contracts, not a new table,\n process or SOUL RPC. An empty map owns no identity; saves preserve other entries\n and use expected-version checks. Validate that each key is an agent identity\n in the resource's org; begin with the default org without inventing org setup.\n Every save records the authenticated editor's identity, source, request ID and\n timestamp; file installation records the system identity, not a fictitious user.\n- Replace `TurnRunnerConfig.Personas` / `PersonaPromptSource` with the per-identity\n source in `prepareTurn`; name the `SystemPromptConfig` input SOUL. Both normal\n and streaming turns use this assembly path. Do not add personality to the\n worker environment, `AgentProfile` or workflow-stage prompts.\n- On an agent identity's dashboard page, expose its effective SOUL, file/default\n or stored source, shadowed file path, owning version, and Markdown editing.\n Save to the control plane, never the host file; show validation/version\n conflicts and offer restoring shipped content or a history revision as a save.\n Read effective file/default content and ownership metadata through a gateway\n query using the turn resolver; the separate UI process never reads the\n gateway host's files. Apply identity-management access rules and the existing\n shared live-update hub.\n- Update `docs/development/agent.md` and `control-plane.md` with this reach and\n precedence, `frontend-ui.md` with the gateway query, and the config wiring\n guidance with a copyable file example.\n\n## Persona removal gate\n\nSOUL supersedes `PersonaRegistry` and the persona-reconciliation proposal;\nidentity-per-action supersedes personas as an identity mechanism.\n`PersonaRegistry.GetActive` composes the baseline with one of five styles from\n`agent.ShippedPersonas`; SOUL replaces the baseline, not that style catalogue.\nPer-session switching disappears: remove `/personality`, Telegram personality\ncallbacks, the dashboard persona page, and chat wire fields `personas`,\n`active_personas` and `personas_available` without reusing their field numbers.\nDo not merge session selections into SOUL or retain a separate style axis.\nCustom persona text must remain available to copy before deleting its stored\nresource; no migration guesses one agent's SOUL from several sessions.\n\nRemove persona loading, selectors and commands only after every chat composition\nsupplies the identity-aware SOUL source, the fallback renders without personas,\nand the dashboard can edit it. SOUL delivery does not wait for org creation or a\nnew container-profile model.\n\n## Acceptance\n\n- Two agents use distinct files and stored entries; renaming one or sharing a\n container profile does not change or mix their SOULs.\n- Before ownership, a file edit changes the next normal or streaming prompt;\n creating defaults never clobbers an existing file.\n- After a save, conflicting file edits and restarts cannot override the stored\n value; the ignored file and owning version are visible. Updating one agent\n preserves the other; stale saves fail and history restores are audited saves.\n- Missing, empty, unreadable, malformed and oversize selected inputs render the\n shipped default. Repeated read failures log once, recover on a later turn,\n and never abort generation.\n- Hostile markup stays escaped before singular, unchanged invariant blocks;\n prompt budgeting includes SOUL and cannot drop the rules.\n- Dashboard edits reach the next generation without restart; persona removal\n leaves every channel with a nonempty identity slot and preserved custom text.\n" + }, { "url": "/dev/prds/state-store-contract/", "title": "State Store — contract boundary \u0026 transport (ratification)", @@ -901,6 +907,10 @@ "title": "Skill curator (reference implementation) -- decision", "url": "/dev/prds/skill-curator/" }, + { + "title": "SOUL: an agent's user-authored personality", + "url": "/dev/prds/soul/" + }, { "title": "State Store — contract boundary \u0026 transport (ratification)", "url": "/dev/prds/state-store-contract/"