From 83613d902a8eb5f0f3a99bfe0ac0a79c33e6dc9a Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 17 Nov 2026 17:53:58 +1100 Subject: [PATCH] docs: format the docs --- docs/guides/first-playbook.md | 8 +-- docs/guides/pr-review-benchmark.md | 24 ------- docs/prds/self-development-loop.md | 14 ++-- docs/security/authorization.md | 56 ++++++++-------- .../organisation-automation/00-start-here.md | 61 ++++++++--------- .../01-execution-identities.md | 28 ++++---- .../02-connections-and-repositories.md | 65 ++++++++++--------- .../03-organisation-ownership.md | 26 ++++---- .../04-navigation-and-setup.md | 37 ++++++----- prompts/organisation-automation/GUIDELINES.md | 40 +++++++----- 10 files changed, 179 insertions(+), 180 deletions(-) delete mode 100644 docs/guides/pr-review-benchmark.md diff --git a/docs/guides/first-playbook.md b/docs/guides/first-playbook.md index f1c22450e..4e1fba3dc 100644 --- a/docs/guides/first-playbook.md +++ b/docs/guides/first-playbook.md @@ -55,10 +55,10 @@ Save. The binding starts in **draft** -- nothing fires yet. ## 5. Approve it -A **draft** or freshly-**edited** binding needs explicit approval -before it can ever match a live event -- this is deliberate, not a missing step: -an operator authoring a binding is a considered act, an event arriving is not, -and nothing should self-arm. Click **Approve**. Status becomes **armed**. +A **draft** or freshly-**edited** binding needs explicit approval before it can +ever match a live event -- this is deliberate, not a missing step: an operator +authoring a binding is a considered act, an event arriving is not, and nothing +should self-arm. Click **Approve**. Status becomes **armed**. ## 6. Fire it for real diff --git a/docs/guides/pr-review-benchmark.md b/docs/guides/pr-review-benchmark.md deleted file mode 100644 index a28c01c1e..000000000 --- a/docs/guides/pr-review-benchmark.md +++ /dev/null @@ -1,24 +0,0 @@ -# PR review benchmark - -``` -task bench:prreview -``` - -Reviews the 38 runnable Martian pull requests once each at `deep` depth with the -production pipeline, judges the posted comments against the golden comments in -`internal/app/prbench/martian.json`, and writes -`docs/benchmarks/pr-review-.md` (recall per PR, overall recall, -precision, models, archie version). Commit that file with the run. - -- Models come from the config at `~/.config/archie/config.toml`: the reviewer - and judge both default to its `default` alias. Override with - `task bench:prreview -- -model ALIAS_OR_PROVIDER/MODEL -judge-model ALIAS_OR_PROVIDER/MODEL`. - Pick a judge other than the reviewer's model for an independent judgement. - Aliases set only in the dashboard are not in the file; pass a `provider/model` - ref instead. -- Pull requests are public, so no credential is needed. `GH_TOKEN` or - `GITHUB_TOKEN`, if set, only raises the GitHub API rate limit. -- `-problems ID,ID` runs a partial smoke run; its report says it is not the - acceptance run. A full run reports PASS when nothing failed and golden - micro-recall is at least 0.70. -- It is not part of `task test` and posts nothing to any pull request. diff --git a/docs/prds/self-development-loop.md b/docs/prds/self-development-loop.md index c9d279df1..b384c8016 100644 --- a/docs/prds/self-development-loop.md +++ b/docs/prds/self-development-loop.md @@ -4,11 +4,11 @@ persistently takes on development of archie-core itself. This file records a desired state, not an implementation or a product: nothing below exists unless the "Built today" section says so. The plan is tracked as epic #1769 with child -issues #1770–#1775. This file is a record, not a mechanism: agents only see -what is in their context, so verify every claim here against the code before -acting on it — where they disagree, the code wins. The boundary below is -load-bearing only where it is enforced (the gate, access control, the daemon's -git monopoly) and stated in `AGENTS.md`; everywhere else this file is a pointer. +issues #1770–#1775. This file is a record, not a mechanism: agents only see what +is in their context, so verify every claim here against the code before acting +on it — where they disagree, the code wins. The boundary below is load-bearing +only where it is enforced (the gate, access control, the daemon's git monopoly) +and stated in `AGENTS.md`; everywhere else this file is a pointer. ## Built today @@ -17,8 +17,8 @@ workflows, the adversarial self-review stage before a PR opens (epic #1348, closed), the prbench judge for review quality with its acceptance bar, canary releases judged on the installed release (releaseupdate), and the curator engine. What does not exist is the loop itself: no self-intake curator, no -approved-issue auto-run, no judge for diffs, no outcome distillation, no -canary routing specific to self-directed changes. +approved-issue auto-run, no judge for diffs, no outcome distillation, no canary +routing specific to self-directed changes. ## Decision diff --git a/docs/security/authorization.md b/docs/security/authorization.md index 7c546abf6..c988d85e1 100644 --- a/docs/security/authorization.md +++ b/docs/security/authorization.md @@ -54,35 +54,35 @@ accounts by unverified email, or create an administrator. ## Enforcement inventory -| Location | Enforcement | Regression evidence | -| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Browser credential gate: `webui/auth.go`, `accounts.go` | Account session or verified provider identity; shared dashboard token is not a person when accounts are enabled. No API data before authentication. | `TestAccountBoundary`, `TestAccountSessionFailureIsClosed` | -| Browser policy gate: `webui/authorize.go` | Resolve principal from stored identity; evaluate action against stored org/workspace and resource kind before handler. Missing chain refuses. | `TestHTTPPolicyCannotBeBypassed`, `TestAuthorizeRefusesWithoutAChain`, `TestAuthorizeRecord`, `TestTaskAuthorizationUsesStoredAttributes`, `TestAuthorizeCreateIn` | -| Instance-only HTTP surfaces: `webui/instance_only.go`, server route registration | Hide instance-owned configuration and diagnostics from another org; policy still applies first. | `TestInstanceOnlyHidesTheInstanceFromOtherOrgs`, `TestInstanceAdminOrgs` | -| First setup: `webui/accounts.go`, `postgres/accounts.go` | Initial organization, workspace, instance URL, admin identity and password commit together. Transaction lock closes bootstrap after first account; later requests require `manage_members`. | Disposable PostgreSQL smoke verification for bootstrap race and rollback; account policy tests below | -| Account creation: `webui/accounts.go`, `staterpc/accounts.go`, `postgres/accounts.go` | Cedar `manage_members` at HTTP and RPC; target org is authenticated context. New local accounts cannot request owner role. | `TestAccountManagementUsesPolicy`, `TestAccountBoundary` | -| Local passwords and sessions: `identity/password.go`, `postgres/accounts.go` | Argon2id, independent salts, length/common-password checks, generic login refusal, account throttling, session hashes and expiry, revocation on logout/password change/suspension. | `TestPasswordVerification`, `TestAccountBoundary`; disposable PostgreSQL session verification | -| Transport and CSRF: `webui/accounts.go`, `api_tasks.go` | Password/account mutations require HTTPS or localhost development, JSON, custom CSRF header and same-origin requests. Forwarded headers require explicit trusted-proxy configuration. | `TestAuthenticationTransport`, existing mutation security tests | -| Personal account routes: `webui/accounts.go` | Active signed-in person; principal supplied by server. Password change verifies current password. Sensitive authenticator changes require recent sign-in. No caller-supplied target identity. | `TestAccountBoundary` | -| Recovery: `postgres/account_security.go`, `webui/accounts.go` | Fresh authenticated owner generates a hashed, one-use recovery secret. Redemption replaces password and revokes all sessions atomically. No email-existence disclosure. | Disposable PostgreSQL recovery verification | -| Passkeys: `postgres/passkeys.go`, `webui/passkeys.go` | Configured RP origin, browser-bound one-use expiring challenge, verified credential signature and user verification. Enrollment/management belong to caller. Credential counters persist under a row lock. | Disposable browser virtual-authenticator verification; task-grant denial tests | -| OIDC: `infrastructure/oidc`, `archieui/account_oidc.go`, `webui/auth.go` | Discovery and signed ID token with issuer/client audience/expiry, PKCE, state and nonce. Verified subject resolves to active identity. Browser-local session cannot outlive provider token, and provider credential remains checked. | `TestBrowserFlowVerifiesIDToken`, `TestProviderOutageIsUnavailableThenRecovers`, subject-claim tests; no external provider acceptance implied | -| OIDC settings: `webui/accounts.go`, `postgres/authentication.go` | Instance ownership plus policy; recent sign-in for changes. Public URL cannot change while enrolled passkeys would be orphaned. | `TestAccountBoundary`, `TestAuthenticationSettingsRejectUntrustedOrigins` | -| Org membership/workspaces/agent assignment: `webui/api_orgs.go`, `staterpc/orgs.go`, `postgres/orgs.go` | Own org or instance-owner relationship, allowed role vocabulary, membership escalation/last-owner guards, tenant-scoped SQL. | `TestOrgRPCsActInTheCallersOrg`, `TestSetMembershipRefusesUnknownRole`, org HTTP tests | -| Personal API tokens: `webui/api_personal_tokens.go`, `staterpc/personal_tokens.go`, `postgres/personal_tokens.go` | Token owner comes from principal; store only token hash; revoke only caller's binding. | `TestPersonalTokensWithoutPerson`, `TestPersonalTokenOwner` | -| gRPC caller attribution: `rpcidentity/identity.go` | Authenticated service may forward a principal; State Store resolves memberships/org itself. Task grant metadata is stripped. | `TestCallerAttribution` | -| Agent/task gRPC: `staterpc/task_grants.go` | Durable task-scoped grant, explicit allowed RPC and target task, no definition-pin replacement, no account RPCs. | `TestTaskCredentialsCannotManageAccounts`, `TestTaskCredentialCannotReplaceItsPin`, `TestRecordUsageAuthority`, `TestWorkerPresenceAuthority` | -| Chat HTTP: `webui/api_chat.go` | Server stamps sender and person thread; lists/read/turns/cancel/persona verify session ownership. Browser cannot submit another sender identity. | `TestWebChatOwnership`, `TestWebChatSenderCannotBeSuppliedByBrowser`; HTTP deny matrix | -| Chat history, slash commands and model session tools: `gateway/session_store_postgres.go` | Store filters `Get`, `List`, `GetByChannel`; shared read/write guards check person ownership as well as org. A saved session cannot change its conversation source to claim another person's history. Service curation runs without a person principal. | `TestSessionVisibility`; PostgreSQL smoke for history isolation | -| Chat questions/approvals: `webui/api_chat_ask.go` | Waiting question is bound to the initiating person, in addition to its unguessable ID. | `TestChatQuestionBelongsToInitiatingPerson` | -| Chat downloads: `webui/api_chat_files.go` | Offered file token expires and is bound to the initiating person; requests cannot supply a filesystem path. | `TestChatFileDownload` | -| Per-person memory: `archiegateway/chat_identity.go`, gateway memory tools, `sessioncurator` | Verified web sender identity scopes reads/writes. Curator refuses unidentified or mixed participants instead of guessing a person. | Gateway memory and session-curator tests | -| Workflow/task actions: `webui/api_tasks.go`, `domain/taskactions`, `staterpc` | Policy and stored workspace before action; domain transition, authority and durable dispatch guards remain in force. | HTTP deny matrix, task action/domain tests, task grant tests | -| Incoming webhooks: `captureintake`, access delivery engine | Verify HMAC before parsing; derive source/org from stored source; evaluate source delivery policies and egress rules. No browser-user credential is inferred. | Capture tests, `TestAuthorizeDelivery` | -| Control-plane configuration, secrets and extensions | Browser policy and instance-only restrictions where registered; service contracts carry principal/org; task grants cannot invoke administrative RPCs. | HTTP deny matrix, `TestAdministrationRoutes`, `TestChannelReloadRoute` | +| Location | Enforcement | Regression evidence | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Browser credential gate: `webui/auth.go`, `accounts.go` | Account session or verified provider identity; shared dashboard token is not a person when accounts are enabled. No API data before authentication. | `TestAccountBoundary`, `TestAccountSessionFailureIsClosed` | +| Browser policy gate: `webui/authorize.go` | Resolve principal from stored identity; evaluate action against stored org/workspace and resource kind before handler. Missing chain refuses. | `TestHTTPPolicyCannotBeBypassed`, `TestAuthorizeRefusesWithoutAChain`, `TestAuthorizeRecord`, `TestTaskAuthorizationUsesStoredAttributes`, `TestAuthorizeCreateIn` | +| Instance-only HTTP surfaces: `webui/instance_only.go`, server route registration | Hide instance-owned configuration and diagnostics from another org; policy still applies first. | `TestInstanceOnlyHidesTheInstanceFromOtherOrgs`, `TestInstanceAdminOrgs` | +| First setup: `webui/accounts.go`, `postgres/accounts.go` | Initial organization, workspace, instance URL, admin identity and password commit together. Transaction lock closes bootstrap after first account; later requests require `manage_members`. | Disposable PostgreSQL smoke verification for bootstrap race and rollback; account policy tests below | +| Account creation: `webui/accounts.go`, `staterpc/accounts.go`, `postgres/accounts.go` | Cedar `manage_members` at HTTP and RPC; target org is authenticated context. New local accounts cannot request owner role. | `TestAccountManagementUsesPolicy`, `TestAccountBoundary` | +| Local passwords and sessions: `identity/password.go`, `postgres/accounts.go` | Argon2id, independent salts, length/common-password checks, generic login refusal, account throttling, session hashes and expiry, revocation on logout/password change/suspension. | `TestPasswordVerification`, `TestAccountBoundary`; disposable PostgreSQL session verification | +| Transport and CSRF: `webui/accounts.go`, `api_tasks.go` | Password/account mutations require HTTPS or localhost development, JSON, custom CSRF header and same-origin requests. Forwarded headers require explicit trusted-proxy configuration. | `TestAuthenticationTransport`, existing mutation security tests | +| Personal account routes: `webui/accounts.go` | Active signed-in person; principal supplied by server. Password change verifies current password. Sensitive authenticator changes require recent sign-in. No caller-supplied target identity. | `TestAccountBoundary` | +| Recovery: `postgres/account_security.go`, `webui/accounts.go` | Fresh authenticated owner generates a hashed, one-use recovery secret. Redemption replaces password and revokes all sessions atomically. No email-existence disclosure. | Disposable PostgreSQL recovery verification | +| Passkeys: `postgres/passkeys.go`, `webui/passkeys.go` | Configured RP origin, browser-bound one-use expiring challenge, verified credential signature and user verification. Enrollment/management belong to caller. Credential counters persist under a row lock. | Disposable browser virtual-authenticator verification; task-grant denial tests | +| OIDC: `infrastructure/oidc`, `archieui/account_oidc.go`, `webui/auth.go` | Discovery and signed ID token with issuer/client audience/expiry, PKCE, state and nonce. Verified subject resolves to active identity. Browser-local session cannot outlive provider token, and provider credential remains checked. | `TestBrowserFlowVerifiesIDToken`, `TestProviderOutageIsUnavailableThenRecovers`, subject-claim tests; no external provider acceptance implied | +| OIDC settings: `webui/accounts.go`, `postgres/authentication.go` | Instance ownership plus policy; recent sign-in for changes. Public URL cannot change while enrolled passkeys would be orphaned. | `TestAccountBoundary`, `TestAuthenticationSettingsRejectUntrustedOrigins` | +| Org membership/workspaces/agent assignment: `webui/api_orgs.go`, `staterpc/orgs.go`, `postgres/orgs.go` | Own org or instance-owner relationship, allowed role vocabulary, membership escalation/last-owner guards, tenant-scoped SQL. | `TestOrgRPCsActInTheCallersOrg`, `TestSetMembershipRefusesUnknownRole`, org HTTP tests | +| Personal API tokens: `webui/api_personal_tokens.go`, `staterpc/personal_tokens.go`, `postgres/personal_tokens.go` | Token owner comes from principal; store only token hash; revoke only caller's binding. | `TestPersonalTokensWithoutPerson`, `TestPersonalTokenOwner` | +| gRPC caller attribution: `rpcidentity/identity.go` | Authenticated service may forward a principal; State Store resolves memberships/org itself. Task grant metadata is stripped. | `TestCallerAttribution` | +| Agent/task gRPC: `staterpc/task_grants.go` | Durable task-scoped grant, explicit allowed RPC and target task, no definition-pin replacement, no account RPCs. | `TestTaskCredentialsCannotManageAccounts`, `TestTaskCredentialCannotReplaceItsPin`, `TestRecordUsageAuthority`, `TestWorkerPresenceAuthority` | +| Chat HTTP: `webui/api_chat.go` | Server stamps sender and person thread; lists/read/turns/cancel/persona verify session ownership. Browser cannot submit another sender identity. | `TestWebChatOwnership`, `TestWebChatSenderCannotBeSuppliedByBrowser`; HTTP deny matrix | +| Chat history, slash commands and model session tools: `gateway/session_store_postgres.go` | Store filters `Get`, `List`, `GetByChannel`; shared read/write guards check person ownership as well as org. A saved session cannot change its conversation source to claim another person's history. Service curation runs without a person principal. | `TestSessionVisibility`; PostgreSQL smoke for history isolation | +| Chat questions/approvals: `webui/api_chat_ask.go` | Waiting question is bound to the initiating person, in addition to its unguessable ID. | `TestChatQuestionBelongsToInitiatingPerson` | +| Chat downloads: `webui/api_chat_files.go` | Offered file token expires and is bound to the initiating person; requests cannot supply a filesystem path. | `TestChatFileDownload` | +| Per-person memory: `archiegateway/chat_identity.go`, gateway memory tools, `sessioncurator` | Verified web sender identity scopes reads/writes. Curator refuses unidentified or mixed participants instead of guessing a person. | Gateway memory and session-curator tests | +| Workflow/task actions: `webui/api_tasks.go`, `domain/taskactions`, `staterpc` | Policy and stored workspace before action; domain transition, authority and durable dispatch guards remain in force. | HTTP deny matrix, task action/domain tests, task grant tests | +| Incoming webhooks: `captureintake`, access delivery engine | Verify HMAC before parsing; derive source/org from stored source; evaluate source delivery policies and egress rules. No browser-user credential is inferred. | Capture tests, `TestAuthorizeDelivery` | +| Control-plane configuration, secrets and extensions | Browser policy and instance-only restrictions where registered; service contracts carry principal/org; task grants cannot invoke administrative RPCs. | HTTP deny matrix, `TestAdministrationRoutes`, `TestChannelReloadRoute` | | Audit feed: `webui/api_audit.go`, `domain/audit` | `read_audit` on the `audit` resource; org scope and the instance-wide exception come from the authenticated principal, never the query string. Export carries the same grant, needs an explicit range of at most a year, and is rate-limited per identity, one at a time. Redaction runs in the State Store adapter before an entry crosses gRPC. | `TestReadAuditRoleBoundary`, `TestAuditRoutesFollowTheReadAuditRole`, `TestHTTPPolicyCannotBeBypassed`, `TestAuditErrorMapping`, `TestAuditCSVCellNeutralisesFormulas` | -| Live HTTP/SSE and diagnostics | Authenticated policy gate applies before stream creation; org-scoped event reads; instance logs require administrative visibility. | HTTP deny matrix, instance-only tests, `TestServiceLogsRequireInstanceCredential` | -| Background schedules, dispatch, curation | Service/agent authority, not an implicit browser user. Task-scoped grants and org scopes remain distinct from initiating operator attribution. | Existing dispatch, grant, memory and org-scope tests | +| Live HTTP/SSE and diagnostics | Authenticated policy gate applies before stream creation; org-scoped event reads; instance logs require administrative visibility. | HTTP deny matrix, instance-only tests, `TestServiceLogsRequireInstanceCredential` | +| Background schedules, dispatch, curation | Service/agent authority, not an implicit browser user. Task-scoped grants and org scopes remain distinct from initiating operator attribution. | Existing dispatch, grant, memory and org-scope tests | The policy HTTP matrix enumerates each registered protected route. It checks both anonymous refusal and refusal by an explicit Cedar forbid, using the real diff --git a/prompts/organisation-automation/00-start-here.md b/prompts/organisation-automation/00-start-here.md index 8521b762b..d73b55b2b 100644 --- a/prompts/organisation-automation/00-start-here.md +++ b/prompts/organisation-automation/00-start-here.md @@ -1,20 +1,20 @@ # 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 issue description field is -not additional approval. +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 issue description +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 | +| 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. @@ -22,16 +22,18 @@ 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. +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. +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 @@ -49,19 +51,20 @@ that snapshot is current. Other agents may have worked since this handoff. 4. `04-navigation-and-setup.md` — #47. Gitea issues are authoritative for progress and dependencies. The parent is -#1043. These files are reusable instructions, not completion records. -Read each issue 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. +#1043. These files are reusable instructions, not completion records. Read each +issue 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. +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 diff --git a/prompts/organisation-automation/01-execution-identities.md b/prompts/organisation-automation/01-execution-identities.md index 9dbe73e7b..a926bba94 100644 --- a/prompts/organisation-automation/01-execution-identities.md +++ b/prompts/organisation-automation/01-execution-identities.md @@ -1,14 +1,15 @@ # 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. +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. +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 @@ -16,9 +17,10 @@ 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. +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 @@ -46,15 +48,17 @@ while keeping root fallback paths would create a credential exposure. 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. + 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. +organisation-correct mapping; surface genuinely ambiguous records for +resolution. ## Acceptance evidence diff --git a/prompts/organisation-automation/02-connections-and-repositories.md b/prompts/organisation-automation/02-connections-and-repositories.md index 5bebb359c..28f5bce5c 100644 --- a/prompts/organisation-automation/02-connections-and-repositories.md +++ b/prompts/organisation-automation/02-connections-and-repositories.md @@ -1,34 +1,36 @@ # 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. +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. +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. +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. +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 @@ -36,13 +38,15 @@ that archied can resolve and use that reference. 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. +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. @@ -52,17 +56,18 @@ that archied can resolve and use that reference. 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. + 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. +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 index 0866b0084..0295d6da3 100644 --- a/prompts/organisation-automation/03-organisation-ownership.md +++ b/prompts/organisation-automation/03-organisation-ownership.md @@ -1,8 +1,8 @@ # 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. +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 @@ -16,28 +16,28 @@ 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. +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. + 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. +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. +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. diff --git a/prompts/organisation-automation/04-navigation-and-setup.md b/prompts/organisation-automation/04-navigation-and-setup.md index 9eb153c28..e9402e196 100644 --- a/prompts/organisation-automation/04-navigation-and-setup.md +++ b/prompts/organisation-automation/04-navigation-and-setup.md @@ -1,8 +1,8 @@ # 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. +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 @@ -17,38 +17,43 @@ without guessing which settings page owns the problem. 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. + 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. + 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. + 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. + 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. +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 the issue. diff --git a/prompts/organisation-automation/GUIDELINES.md b/prompts/organisation-automation/GUIDELINES.md index 2d222f25a..dbcea8210 100644 --- a/prompts/organisation-automation/GUIDELINES.md +++ b/prompts/organisation-automation/GUIDELINES.md @@ -13,34 +13,39 @@ AGENTS.md files first; the maintainer's current instructions take precedence. - 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. + 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. + 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. + 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. +- 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 issues instead of fixing them in passing. + identity authority, duplicated ownership model or indefinite compatibility + shim. +- No new service, binary, generic framework, broad cleanup or speculative + feature. File unrelated discoveries as issues instead of fixing them in + passing. ## Verification and delivery @@ -48,12 +53,13 @@ AGENTS.md files first; the maintainer's current instructions take precedence. 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. + 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. + 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. @@ -63,5 +69,5 @@ AGENTS.md files first; the maintainer's current instructions take precedence. 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. + Keep useful progress updates concise. Ask only for unresolved product + decisions or explicitly restricted external/destructive actions.