From 139338cf34559831750d7b1cd74c20e2f7ace50b Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 17 Oct 2026 02:25:32 +1100 Subject: [PATCH] docs(prompts): define organisation automation handoff --- .../organisation-automation/00-start-here.md | 69 +++++++++++++++++++ .../01-execution-identities.md | 66 ++++++++++++++++++ .../02-connections-and-repositories.md | 68 ++++++++++++++++++ .../03-organisation-ownership.md | 54 +++++++++++++++ .../04-navigation-and-setup.md | 54 +++++++++++++++ prompts/organisation-automation/GUIDELINES.md | 67 ++++++++++++++++++ 6 files changed, 378 insertions(+) create mode 100644 prompts/organisation-automation/00-start-here.md create mode 100644 prompts/organisation-automation/01-execution-identities.md create mode 100644 prompts/organisation-automation/02-connections-and-repositories.md create mode 100644 prompts/organisation-automation/03-organisation-ownership.md create mode 100644 prompts/organisation-automation/04-navigation-and-setup.md create mode 100644 prompts/organisation-automation/GUIDELINES.md diff --git a/prompts/organisation-automation/00-start-here.md b/prompts/organisation-automation/00-start-here.md new file mode 100644 index 000000000..6d7808216 --- /dev/null +++ b/prompts/organisation-automation/00-start-here.md @@ -0,0 +1,69 @@ +# Handoff: organisation-owned automation + +Read this file and `GUIDELINES.md` before running a numbered implementation prompt. +The maintainer approved the architecture below. Implement it; do not restart a +navigation brainstorming exercise. The initial Antigravity navigation proposal +was rejected. A later externally authored design or Bead design field is not +additional approval. + +## Approved product model + +| Scope | Ownership | +| --- | --- | +| Account | Login methods, personal API tokens, preferences | +| Instance | Authentication providers, execution infrastructure, installed extensions, secret-engine infrastructure, organisation limits | +| Organisation | Members, execution identities, external connections, model configuration, workflows, schedules, channels | +| Workspace | Groups organisation work and resources; initially inherits organisation permissions | +| Task/run | Requesting actor, execution identity, resolved workflow and resource references | + +External connections are explicit organisation resources. A forge connection +identifies its host, authentication reference and verified external account. +Repositories reference connections. Execution identities receive permission for +specified operations on those resources. Git commit authorship is separate from +authentication. Database-backed execution identities are authoritative. + +Preserve existing service boundaries: State Store/control plane persists resources +and authority; archied resolves execution resources, performs Git operations and +verifies repository access; Gateway owns conversations and organisation-scoped +model use; UI presents contracts and diagnostics. Use existing gRPC contracts for +service communication. Do not add a service or access another service's tables. + +A saved change must become effective without a server login. Connection state +must distinguish saved, applied, verified and failed. A resolved secret is not +proof of repository access. Setup follows the requested capability: repositories, +chat channels and a global default model are not universal prerequisites. + +## Starting state to verify + +The last implementation commit recorded at handoff was `57456b3e`, containing +independent settings/workflow/task diagnostic fixes. Architecture implementation +has not begun. No application source was edited in the architecture approval +session. Verify current history, checkout and working tree rather than assuming +that snapshot is current. Other agents may have worked since this handoff. + +## Execution sequence + +1. `01-execution-identities.md` — `archie-core-kgxw.13`. +2. `02-connections-and-repositories.md` — `archie-core-oygqd`. +3. `03-organisation-ownership.md` — `archie-core-3z4fd.8`. +4. `04-navigation-and-setup.md` — `archie-core-3z4fd.1`. + +Beads is authoritative for progress and dependencies. The parent is +`archie-core-3z4fd`. These files are reusable instructions, not completion records. +Read each Bead before claiming it. Complete the current slice end to end before +starting the next. Do not close the parent until all acceptance criteria have +actual evidence. Do not delegate unless the maintainer explicitly authorises it. + +## Final acceptance scenario + +An organisation administrator configures a forge connection through the dashboard, +binds a private repository, permits an execution identity to clone/push/open a PR, +verifies access using the daemon, selects that identity in a workflow, and runs or +retries a task successfully. No configuration-file edit, restart, root credential +fallback or daemon secret in a container is needed. A separate repository-free +workflow runs without a forge connection. Cross-organisation use is refused. + +Use an isolated authenticated private-repository equivalent for verification. +Production configuration, deployment, pushes and external posting require the +maintainer's explicit instruction. Do not use a dummy public/nonexistent +repository's failure as evidence for private-repository authentication. diff --git a/prompts/organisation-automation/01-execution-identities.md b/prompts/organisation-automation/01-execution-identities.md new file mode 100644 index 000000000..66ae717c8 --- /dev/null +++ b/prompts/organisation-automation/01-execution-identities.md @@ -0,0 +1,66 @@ +# Implement live database execution identities + +Read `00-start-here.md` and `GUIDELINES.md`. Work against +`archie-core-kgxw.13`; read and claim it before editing. + +## Outcome + +A bot or service account created and assigned through the dashboard can execute a +repository-free workflow without a configuration-file entry or process restart. +The database is the lifecycle and identity authority. A database identity cannot +silently acquire the root forge account, model authority or container grants. + +## Source investigation + +Trace `internal/domain/identity`, organisation agent assignment, State Store +identity RPC and principal assembly, `internal/app/archied/bootstrap.go`, +`internal/app/archied/main.go`, `internal/daemon/workflow_identity.go`, +`internal/daemon/workflow_org.go`, and identity-dependent paths in daemon.go and +kit_task.go. Inspect `ui/src/workflows/WorkflowSettings.vue` and the organisation +agent screen. Inspect every caller of declaredIdentity, identityMayAct, +identityFor, publisherIdentity, configFor, forgeFor, treesFor and repoFor. + +At handoff, the UI offered database IDs but execution used startup-built +IdentityRunner objects from cfg.Identities. Forge/worktree NATS registrations +were also startup-only. Verify these facts. Changing just the identity lookup +while keeping root fallback paths would create a credential exposure. + +## Required behaviour + +1. Resolve a workflow's execution reference to a durable active agent identity. + Canonical references use stable IDs, independent of editable display names. + Refuse human, suspended, retired, missing and unassigned identities. +2. Establish the identity's organisation from authoritative assignment. Refuse + cross-organisation use even when a caller knows the other identity ID. Retain + checks for both workflow invocation and execution, including binding context. +3. Keep the persisted requesting actor distinct from the executing principal. + Check the record and worker handoff, not just in-memory task mutation. +4. New dashboard identities work live. Lifecycle or assignment changes affect + subsequent attempts. An unavailable identity authority causes an explicit + local refusal/dependency error, not permissive fallback. +5. Audit all resource and RPC resolution. Database agents must not inherit root + forge tokens, repository permissions or container credential grants. Do not + create a second cached identity authority to patch over the split. +6. Preserve existing configured identities through a narrowly scoped migration + into their actual owning organisation. Do not delete settings or silently + assign every identity to the system organisation. Preserve effective grants + without granting anything to newly created agents by default. +7. Keep repository authentication separate. A repository-free agent needs no + forge connection. Until the connection slice is implemented, reject unsupported + repository access explicitly rather than borrowing root credentials. +8. Make workflow identity selection use eligible identities of the active + organisation and display their names while saving stable IDs. Show loading, + unavailable and empty states truthfully. + +Do not invent new meanings for `root` or replace it with another organisation's +agent automatically. Migrate existing references only with a deterministic, +organisation-correct mapping; surface genuinely ambiguous records for resolution. + +## Acceptance evidence + +Show a dashboard-created agent running a repository-free workflow through the +actual daemon path. Cover refused human, inactive, unassigned and cross-org +identities; authority outages; retry rechecks; and absence of root credential +inheritance. Verify a renamed agent still resolves by ID. Verify existing mapped +identities retain their permissions. Run the project gate and record evidence +and any remaining limitations in the Bead before closing it. diff --git a/prompts/organisation-automation/02-connections-and-repositories.md b/prompts/organisation-automation/02-connections-and-repositories.md new file mode 100644 index 000000000..5bebb359c --- /dev/null +++ b/prompts/organisation-automation/02-connections-and-repositories.md @@ -0,0 +1,68 @@ +# Implement organisation forge connections and repository access + +Read `00-start-here.md` and `GUIDELINES.md`. Work against +`archie-core-oygqd`. Its prerequisite is `archie-core-kgxw.13`; verify acceptance +before claiming this slice. Do not treat a closed issue without evidence as proof. + +## Outcome and resource relationships + +An organisation owns a named external connection. It identifies the forge host, +authentication reference and verified external account. A repository references +that connection. An execution identity is authorised for specified operations +such as clone, push and opening a PR. Commit author name/email remain independent +of the authenticating external account. Choose the smallest representation that +fits the existing control-plane resource and policy contracts; do not build a +new integration service or expose root config fields as the domain model. + +## Investigate first + +Trace existing control-plane resource registration and organisation validation, +repository policies, SecretRef handling, forge extensions and resolveForge in +archied, worktree.Manager authentication, task-scoped forge/worktree RPC authority, +apply-status reporting and settings API authorisation. Check every Git and forge +consumer, including intake polling, review handling, retries and post-run actions. +A secret-reference check currently performed by another service is not evidence +that archied can resolve and use that reference. + +## Required behaviour + +1. Organisation administrators manage connections and repository bindings through + API/dashboard with server-side authorisation. Other organisations cannot read, + modify, select, verify or execute against them by guessing an ID. +2. Reuse secret references and installed forge capabilities. Do not hardcode a + closed GitHub/Gitea list if enabled extensions already supply discovery. + Never return token values to the browser. Any credential-entry path must have + a real secure storage consumer, not store plaintext in generic config/audit. +3. Authorise operations for the actual execution identity and selected resource. + A valid token does not itself grant an agent permission. Do not grant blanket + write/issue/PR permissions when only clone/read is requested. +4. Resolve the selected connection in archied for the actual repository operation. + Apply updates live. Saved revision, applied revision and verified access are + distinct; failed changes must not falsely report that the new revision runs. +5. Test access through the daemon's real forge/Git path for the selected repository + and base branch, under the relevant execution identity's permissions. Report + which operation was checked. Read success cannot prove push or PR permission. + Verification must not create commits, branches or PRs as an incidental probe. +6. Credential rotation reaches subsequent operations without process restart. + Revoked permissions are enforced on subsequent operations/attempts. Avoid + stale cached credentials silently surviving changes. +7. Produce structured failures with a cause, affected resource/operation and an + authorised recovery action. Distinguish missing configuration, unavailable + secret/extension, denied authority and remote authentication/access failure. + A remote 401 or 'Repository not found' does not prove which underlying cause + occurred. Do not implement frontend substring/regex diagnosis. +8. Populate task repository choices from authorised configured repositories, not + only prior tasks. A failed task can lead to its connection and return to retry. +9. Migrate existing forge/repository configuration to its existing owner without + widening grants; remove obsolete runtime paths after all consumers migrate. + Do not force connection setup for repository-free workflows. + +## Acceptance evidence + +Use an isolated authenticated private-repository equivalent. Demonstrate dashboard +configuration, actual daemon clone, permitted push/PR execution where the test +workflow calls for it, credential rotation and refused unauthorised operations. +Show that another org and an ungranted agent cannot use the same connection. +Inspect worker handoff/logs to confirm tokens do not leak. Run a repository-free +workflow independently. Record exact limitations; no production configuration or +external posting is authorised by this prompt. diff --git a/prompts/organisation-automation/03-organisation-ownership.md b/prompts/organisation-automation/03-organisation-ownership.md new file mode 100644 index 000000000..0866b0084 --- /dev/null +++ b/prompts/organisation-automation/03-organisation-ownership.md @@ -0,0 +1,54 @@ +# Migrate automation resources to organisation ownership + +Read `00-start-here.md` and `GUIDELINES.md`. Work against +`archie-core-3z4fd.8`. Read prior identity/connection changes before deciding what +remains; do not duplicate their resources or migrations. + +## Outcome + +Every automation resource resolves within its owning organisation and every +instance resource remains an explicitly administered infrastructure capability. +Existing settings retain their values, ownership and effective access. + +## Required scope + +Inspect the control plane's instanceOnlyKinds, runtime layering, org model +policy, provider/model selection, workflow definitions/enablement, schedules, +channel settings, event sources/bindings, execution profiles and task/container +policies. Inspect all runtime consumers and authorization paths before changing +scope. Use the ownership table in `00-start-here.md` as the approved target. +Do not mechanically remove kinds from instanceOnlyKinds and declare completion. + +## Rules and implementation requirements + +1. Resolve organisational resources from the task/request's authoritative org + context. Do not trust a submitted org field, retain a root context by accident, + or query a different service's tables. +2. Preserve the distinction between installed instance capability, organisation + configuration and organisation permission to use shared infrastructure. + Existing org model policy must remain effective. Instance infrastructure + limits remain enforceable even when organisations configure automation. +3. Keep workspace semantics narrow: group organisation work/resources and inherit + organisation permission initially. Do not invent a second workspace policy + system or weaken existing explicit restrictions. +4. Establish deterministic ownership for existing records before migration. + Preserve valid instance defaults only where the model explicitly allows + inherited infrastructure defaults. Do not copy secrets or permissions into + every tenant. Ambiguous ownership must be visible, never guessed. +5. Make migrations safe to resume and maintain atomicity where records must agree. + An interrupted migration must not silently lose settings or broaden access. + Regenerate affected contracts and update every reader/writer/fixture. +6. Saved org settings need functioning runtime consumers, apply status and + dependency failure handling. Watches/caches must be keyed by organisation as + well as resource/revision wherever shared processes consume multiple tenants. +7. Remove superseded global paths after callers and data move. Do not maintain + two independent sources of truth. Preserve accepted work while peers restart. + +## Acceptance evidence + +Demonstrate two organisations with distinct effective resources using actual +service/API paths. Verify configuration changes and restarts retain separation, +and that requests/tasks cannot read or use another org's configuration. Verify +migration of representative existing configuration without widened permissions, +including interrupted/repeated migration semantics where applicable. Follow +AGENTS.md for SQL/security regression tests and run the final project gate. diff --git a/prompts/organisation-automation/04-navigation-and-setup.md b/prompts/organisation-automation/04-navigation-and-setup.md new file mode 100644 index 000000000..4c650f2b4 --- /dev/null +++ b/prompts/organisation-automation/04-navigation-and-setup.md @@ -0,0 +1,54 @@ +# Implement navigation and contextual setup from working contracts + +Read `00-start-here.md` and `GUIDELINES.md`. Work against +`archie-core-3z4fd.1`. Verify its connection and ownership prerequisites before +starting. The old page-rearrangement proposal is rejected, not a UI specification. + +## Outcome + +The visible application reflects actual resource ownership. An operator can find +and complete the setup needed for a particular workflow and recover a failed run +without guessing which settings page owns the problem. + +## Required behaviour + +1. An organisation selector establishes context. Workflows, Tasks, Connections + and Organisation settings operate in that context. Switching org must clear + or refetch scoped state and prevent stale responses from contaminating it. +2. Instance administration is a separate administrator destination for + infrastructure and instance limits. Personal login security, API tokens and + preferences live in the account menu. Do not recreate a catch-all Access page. +3. Connections are discoverable organisation resources. A repository opens its + connection; a workflow shows the execution identity/resources it needs; a + failed task links to an authorised recovery action. Show names with stable + references, without duplicate organisation labels or unexplained internal IDs. +4. Setup is contextual. A repo-required workflow offers missing connection, + repository, identity or model configuration where needed. A repository-free + workflow never demands GitHub. Chat channels and a global default model are + not universal setup prerequisites. Do not add a mandatory global wizard. +5. Readiness comes from backend capability diagnostics for the selected org, + identity, workflow and resource. Distinguish saved/applied/verified/failed. + Do not infer readiness from nonempty fields, task counts or a resolved secret. +6. Recovery consumes structured service errors. The browser must not classify + root causes using error-string patterns or display actions the user cannot + perform. Preserve task context when moving to configuration and returning. +7. Preserve the prior working settings draft/save flow, readable width, review + diffs, workflow validation and truthful loading/error states. Do not reintroduce + native navigation prompts that discard drafts or collisions with the chat FAB. +8. Keep technical implementation details out of normal product copy. Explain + connection/account/permission problems in terms useful to the operator, not + daemon config keys, NATS subjects or secret plumbing. + +## Acceptance evidence + +Drive the real local UI: create or select an org, configure the private-repository +connection, choose a valid execution identity, verify repository access, start a +workflow, encounter and recover a controlled access failure, then retry. Also run +repository-free automation without forge setup. Verify a second org cannot see +or select the first org's resources, including after switching org during an +in-flight fetch. Check administrator, ordinary member and personal account views, +loading/error states, keyboard access and a narrow viewport. Capture evidence, +regenerate embedded UI output and run the exact final tree's project gate. + +Do not claim a successful user journey based solely on mocked screenshots or +fixture state. Leave unmet criteria explicitly open in Beads. diff --git a/prompts/organisation-automation/GUIDELINES.md b/prompts/organisation-automation/GUIDELINES.md new file mode 100644 index 000000000..f84ef6a8c --- /dev/null +++ b/prompts/organisation-automation/GUIDELINES.md @@ -0,0 +1,67 @@ +# Mandatory execution guidelines + +These rules apply to every numbered prompt. Read the current root and scoped +AGENTS.md files first; the maintainer's current instructions take precedence. + +## Before edits + +- Verify the requested checkout, branch, working tree and other active writers. + Preserve unrelated changes. Do not reset, stash or overwrite another agent. +- Read and claim the named Bead. Create any missing issue before starting its + work. Record implementation discoveries and remaining work in Beads, never a + second Markdown task ledger. Do not sync Beads externally unless told. +- Trace the complete affected path: UI, API, service contract, authorisation, + persistence, runtime consumer, retries, fixtures and generated artifacts. +- Name the smallest complete change. Reuse existing resource, secret-reference, + authorisation, apply-status and service-contract mechanisms. If a new mechanism + or a change exceeding roughly 100 lines is needed, assess simpler alternatives + and record why they fail. This assessment does not mean asking again for an + already approved direction. +- Treat file names and line references in these prompts as investigation leads. + Verify the current source; do not implement from stale notes alone. + +## Implementation boundaries + +- Preserve service isolation, durable acknowledgement and local failure. An + unavailable peer must not terminate unrelated services or discard accepted work. +- Enforce organisation ownership and operation permissions on the server. Hidden + UI controls are not an authorisation boundary. Caller-supplied organisation or + identity values are not trusted facts. +- Keep requesting actor, execution principal, external account and commit author + distinct. Never infer authority from a display name or a matching account name. +- Never fall back to root credentials or broad grants when resolution fails. + Never grant every existing organisation access to migrated global resources. +- The model never runs Git. Daemon credentials never enter agent containers, + task briefs, browser responses or logs. Task-scoped grants expire/revoke when + execution ends. Task briefs remain under `.git/task.json`. +- Persist settings through the control plane and implement their runtime consumer + in the same slice. Do not ship parse-only fields, decorative readiness badges, + restart instructions or a server-login workaround as completion. +- Remove obsolete paths only after migrating their data and callers. No parallel + identity authority, duplicated ownership model or indefinite compatibility shim. +- No new service, binary, generic framework, broad cleanup or speculative feature. + File unrelated discoveries as Beads instead of fixing them in passing. + +## Verification and delivery + +- For a reported bug, reproduce it with a meaningful failing regression before + fixing it. Cover changed security, workflow and SQL semantics as required by + AGENTS.md. Do not add tests of constants, wiring or struct shapes. +- Verify through real API/runtime/browser paths when the acceptance requires + them. State Store fixtures and mocks must be labelled; they do not prove actual + private Git access, credential rotation or successful agent execution. +- Do not open a real database or require Docker in unit tests. Use the isolated + integration/e2e environment for real service verification. +- Follow current project instructions for framework/library documentation. Never + send secrets, production identifiers or credential contents to documentation tools. +- Regenerate protobuf and embedded UI assets when their sources change; do not + hand-edit generated output. Run appropriate targeted checks, then `task check` + on the exact final tree before committing. Never run concurrent full gates. +- Stage only your own paths, never `.beads/`, binaries or scratch output. Commit + finished work with a short scoped Conventional Commit. Do not push or deploy. +- Close a Bead only when its stated acceptance is demonstrated. If something + remains unverified, record exactly what and why; leave the issue open. Never + describe a partial implementation as end-to-end completion. +- Report what changed, what was verified and the material remaining limitation. + Keep useful progress updates concise. Ask only for unresolved product decisions + or explicitly restricted external/destructive actions.