docs(prompts): define organisation automation handoff
This commit is contained in:
1 parent
41cd938748
commit
139338cf34
6 files changed
+378
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user