docs: commit ADR decision log + refresh CONTEXT.md for the wso2cloud work

[kaje94]

Why

The recent wso2cloud-integration + local-setup PRs (#10–#37) landed a lot of hard-won architectural decisions, but the decision log (docs/adr/) was never committed and CONTEXT.md had drifted out of date — actively misleading a future reader/agent. This makes the durable knowledge concise, precise, and committed. No code changes.

What

ADRs (docs/adr/ — committed for the first time; CONTEXT.md already had [[adr-…]] links to them). Contiguous 0001–0006:

ADR	Decision
0001	coding-agent runs off the workflow-plane (DP Job, not Argo)
0002	local SM-API is an in-repo stub — one SM-API provider in both envs, no openbao; local is a self-contained stub (merges the earlier "real cloud binary" decision as a rejected alternative)
0003	coding-agent dispatched as a K8s Job via cluster-gateway-proxy
0004	reference the per-org namespaced ComponentType; provision it locally
0005	dual-mode OC auth: forward user JWT; X-Impersonate-Org on M2M
0006	build git credentials via OC CreateGitSecret, not in-cluster SSA

CONTEXT.md refresh:

• Corrected stale entries vs shipped code: cluster-gateway-proxy (now JWT-authed in cloud, fix(clustergatewayproxy): authenticate to the cloud proxy with the M2M token #23), Task JWT → publisher client-credentials runner auth is implemented (WS2.4: per-org publisher cc runner-auth (additive, behind triplet) #26/feat(dispatch): provision per-org publisher cc at dispatch (runner gateway-auth for every component) #28/fix(publisher): register per-org publisher app under the org's OU + self-heal platform profile #29), SM API local = in-repo stub (fix(deployments): replace wso2cloud sm-api build dep with in-repo local stub #37), GitSecret via OC CreateGitSecret (fix(build): provision the build git secret via OpenChoreo (unified local + cloud) #33).
• Removed dangling [[adr-…]] links to ADRs that were never written.
• Added load-bearing terms: service identity / X-Impersonate-Org, publisher cc runner auth, ComponentType vs ClusterComponentType, AGENT_CLUSTER_SECRET_STORE/secretstore-read, repair-secrets, project_id per-org uniqueness.

.gitignore: ignore deployments-v2/ (local scratch + secrets) and SESSION.md.

Also discarded ~11 stale scratch planning docs under docs/superpowers/plans/ (superseded by these ADRs + the code).

Notes

• The two local-sm-api ADRs were merged into one (they were the same decision at two points in time; docs/adr/ wasn't committed yet, so there was no published history to preserve). Kept number 0002 so the existing ADR-0002 code comments stay valid.
• ADRs 0002 & 0004 describe code in the still-open fix(deployments): replace wso2cloud sm-api build dep with in-repo local stub #37 — they're decision records and land cleanly ahead of / alongside it.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7a993a89-c72d-43ef-a725-c34e29be0ff4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR updates app-factory documentation to reflect architectural refinements across platform planes and operational patterns. It adds gitignore rules for local development artifacts, revises the domain glossary in CONTEXT.md to clarify project model semantics, component type distinctions, secrets delivery workflows, SM API contract, gateway proxy authentication, and identity/routing rules. Seven ADRs formalize decisions: relocating coding-agent WorkflowRuns to the data plane; implementing a local SM API stub; switching coding-agent dispatch to Kubernetes Jobs via cluster-gateway-proxy; provisioning namespaced ComponentTypes locally; establishing dual-mode OpenChoreo authentication; and documenting build Git secret delivery through OpenChoreo with per-org SecretReference refresh. No code changes or exported entities are altered.

Suggested reviewers

• xlight05

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarizes the main changes: documenting architectural decisions (ADRs) and refreshing CONTEXT.md for the wso2cloud work. It is concise and specific.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description clearly articulates the problem (ADR decision log not committed, CONTEXT.md drifted out of date), identifies the solution (committing ADRs and refreshing CONTEXT.md), and provides comprehensive detail about what changed.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/refresh-context-adrs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

CONTEXT.md (1)

25-29: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use “Job” terminology here to match the dispatch model documented below.

This paragraph says coding-agent “WorkflowRun pods run,” but later sections describe Job-based dispatch through cluster-gateway-proxy. Updating this wording will remove internal ambiguity.

As per coding guidelines, "Provide concise, actionable feedback focused on correctness and best practices."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTEXT.md` around lines 25 - 29, Replace the phrase that says coding-agent
“WorkflowRun pods run” in the remote-worker NS paragraph with Job-oriented
wording to match the documented dispatch model: reference the coding-agent
dispatches Jobs (not WorkflowRun pods) via cluster-gateway-proxy to the
wc-<orgUUID8>-<orgHash8>-remote-worker namespace. Update the sentence in
CONTEXT.md under the "remote-worker NS" section to use “Jobs” (or “Job-based
dispatch”) and mention cluster-gateway-proxy and coding-agent to remove
ambiguity and align terminology with the rest of the doc.

Source: Coding guidelines

🧹 Nitpick comments (4)

docs/adr/0005-namespaced-componenttype-local-provisioning.md (1)

46-46: ⚡ Quick win

Make cross-PR dependency text self-describing.

Line 46 (“PR #36 + #37”) is terse. Consider replacing it with a short phrase describing what each PR contributes, so the ADR remains understandable without opening both PRs.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/adr/0005-namespaced-componenttype-local-provisioning.md` at line 46,
Replace the terse cross-PR reference "PR `#36` + `#37`." with a self-describing
phrase that summarizes each PR's contribution (e.g., "PR `#36`: add namespaced
ComponentType schema; PR `#37`: implement local provisioning backend"), so readers
can understand the intent without opening the PRs; update the sentence at the
location containing "PR `#36` + `#37`." in the ADR text accordingly to include brief
descriptions for both PRs.

docs/adr/0001-coding-agent-off-workflow-plane.md (1)

42-43: ⚡ Quick win

Align workload characterization across sections.

Line 42 labels coding-agent as “CI-style ephemeral compute,” but Lines 31–33 describe it as long-running and interactive. Please use one consistent characterization to avoid ambiguity in the decision rationale and runbook guidance.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/adr/0001-coding-agent-off-workflow-plane.md` around lines 42 - 43, The
document inconsistently describes "coding-agent" as both “CI-style ephemeral
compute” and “long-running and interactive”; pick one consistent
characterization (either ephemeral CI-style or long-running interactive) and
update every occurrence to match—specifically edit the phrase in the decision
rationale and the runbook sections so the label used around the existing
"coding-agent" references and the sentence currently saying “CI-style ephemeral
compute” (and the sentences describing it as long-running/interactive) are
unified; ensure any guidance that depends on that characterization (quota/PSP
review notes) is adjusted to reflect the chosen model.

docs/adr/0007-build-git-secret-via-openchoreo.md (1)

34-40: ⚡ Quick win

Add a clear exit condition for the interim cloud fallback.

Please add one explicit “remove when” condition (e.g., route available + validation step) so this temporary behavior is easier to retire and audit.

As per coding guidelines, "Provide concise, actionable feedback focused on correctness and best practices. Avoid unnecessary detail or speculation."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/adr/0007-build-git-secret-via-openchoreo.md` around lines 34 - 40,
Update the "Interim" paragraph to include a single explicit "Remove when"
condition that states the temporary fallback should be removed once the
platform-api route `/api/v1alpha1/gitsecrets` is available and server-side
validation for git secret creation (including ownership checks that previously
returned ErrRepoNotInOrg and ErrOrgDisconnected) succeeds; reference the
tracking issue wso2-enterprise/wso2cloud#319 and the env toggle
`GITHUB_REPO_VISIBILITY` so auditors can verify the condition was met before
reverting to strict secret provisioning.

Source: Coding guidelines

docs/adr/0004-local-sm-api-in-repo-stub.md (1)

38-40: ⚡ Quick win

Document an explicit local-only execution guard for unsigned JWT decoding.

Please add a short constraint stating this behavior is restricted to local/dev and must fail closed outside that mode. This keeps the ADR’s safety boundary unambiguous for future implementers.

Suggested doc patch

- with the root token (vs the real ESO + k8s-SA flow), and it decodes the JWT
- without signature verification (single-tenant local — `ouId` only scopes the
- namespace).
+ with the root token (vs the real ESO + k8s-SA flow), and it decodes the JWT
+ without signature verification (single-tenant local — `ouId` only scopes the
+ namespace). This mode is local/dev only and must be gated by explicit
+ environment checks so non-local environments reject startup if this path is enabled.

As per coding guidelines, "Use neutral, high-level language and validate safety without exposing sensitive context."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/adr/0004-local-sm-api-in-repo-stub.md` around lines 38 - 40, Add a
short, explicit constraint in the ADR stating that decoding JWTs without
signature verification is allowed only in local/dev mode and must be guarded by
a runtime/local-only flag so it fails closed in non-local environments;
reference the unsigned JWT decoding behavior and the use of ouId as namespace
scoping, and state that any implementation of the "root token" local flow must
include an environment check (local/dev) and reject unsigned JWTs elsewhere.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CONTEXT.md`:
- Around line 116-123: Update the glossary entry to reflect the implemented
contract: change the cloud default from "secretstore-read" to
"application-secrets-read" for the ESO ClusterSecretStore used by per-run
coding-agent ExternalSecrets, state that application-secrets-read grants access
to user-app-secrets/<org>/cred-* (AppRole approle-creds-read-permission), and
note that secretstore-read is a no-op in cloud; update the
AGENT_CLUSTER_SECRET_STORE, secretstore-read, application-secrets-read and
user-app-secrets/<org>/cred-* references so they align with the implemented
behavior.

In `@docs/adr/0003-coding-agent-via-cluster-gateway-proxy.md`:
- Around line 43-47: The ADR currently contradicts itself about proxy auth (one
place says JWT-authenticated while another says "proxy is un-authed today" and
the line "No new credentials to provision."); pick the single ground-truth
contract (either JWT-authenticated or unauthenticated) and make the document
consistent by updating all mentions accordingly—specifically edit the paragraph
referencing CLUSTER_GATEWAY_PROXY_ALLOWED_CRS, the sentence "No new credentials
to provision.", and any occurrences of "un-authed" or "JWT-authed" so they state
the chosen contract and the resulting operational impact (e.g., whether M2M
clients, token-minting, or JWKS wiring are required). Ensure the final text
clearly states the auth model and its implications for credential provisioning.
- Around line 66-67: The text references a misspelled repository/path
`wso2cloud-deployement-main/dataplane/.../cluster-workflows/`; update that path
to the correct spelling
`wso2cloud-deployment-main/dataplane/.../cluster-workflows/` and ensure the note
still states the Job template moves into `app-factory` so readers can locate the
retired ClusterWorkflow correctly.

---

Outside diff comments:
In `@CONTEXT.md`:
- Around line 25-29: Replace the phrase that says coding-agent “WorkflowRun pods
run” in the remote-worker NS paragraph with Job-oriented wording to match the
documented dispatch model: reference the coding-agent dispatches Jobs (not
WorkflowRun pods) via cluster-gateway-proxy to the
wc-<orgUUID8>-<orgHash8>-remote-worker namespace. Update the sentence in
CONTEXT.md under the "remote-worker NS" section to use “Jobs” (or “Job-based
dispatch”) and mention cluster-gateway-proxy and coding-agent to remove
ambiguity and align terminology with the rest of the doc.

---

Nitpick comments:
In `@docs/adr/0001-coding-agent-off-workflow-plane.md`:
- Around line 42-43: The document inconsistently describes "coding-agent" as
both “CI-style ephemeral compute” and “long-running and interactive”; pick one
consistent characterization (either ephemeral CI-style or long-running
interactive) and update every occurrence to match—specifically edit the phrase
in the decision rationale and the runbook sections so the label used around the
existing "coding-agent" references and the sentence currently saying “CI-style
ephemeral compute” (and the sentences describing it as long-running/interactive)
are unified; ensure any guidance that depends on that characterization
(quota/PSP review notes) is adjusted to reflect the chosen model.

In `@docs/adr/0004-local-sm-api-in-repo-stub.md`:
- Around line 38-40: Add a short, explicit constraint in the ADR stating that
decoding JWTs without signature verification is allowed only in local/dev mode
and must be guarded by a runtime/local-only flag so it fails closed in non-local
environments; reference the unsigned JWT decoding behavior and the use of ouId
as namespace scoping, and state that any implementation of the "root token"
local flow must include an environment check (local/dev) and reject unsigned
JWTs elsewhere.

In `@docs/adr/0005-namespaced-componenttype-local-provisioning.md`:
- Line 46: Replace the terse cross-PR reference "PR `#36` + `#37`." with a
self-describing phrase that summarizes each PR's contribution (e.g., "PR `#36`:
add namespaced ComponentType schema; PR `#37`: implement local provisioning
backend"), so readers can understand the intent without opening the PRs; update
the sentence at the location containing "PR `#36` + `#37`." in the ADR text
accordingly to include brief descriptions for both PRs.

In `@docs/adr/0007-build-git-secret-via-openchoreo.md`:
- Around line 34-40: Update the "Interim" paragraph to include a single explicit
"Remove when" condition that states the temporary fallback should be removed
once the platform-api route `/api/v1alpha1/gitsecrets` is available and
server-side validation for git secret creation (including ownership checks that
previously returned ErrRepoNotInOrg and ErrOrgDisconnected) succeeds; reference
the tracking issue wso2-enterprise/wso2cloud#319 and the env toggle
`GITHUB_REPO_VISIBILITY` so auditors can verify the condition was met before
reverting to strict secret provisioning.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d5d12495-fae2-49b4-9ca9-45c4b6eb80e0

📥 Commits

Reviewing files that changed from the base of the PR and between 3becfcc and 36ed55e.

📒 Files selected for processing (9)

• .gitignore
• CONTEXT.md
• docs/adr/0001-coding-agent-off-workflow-plane.md
• docs/adr/0002-local-sm-api-stub.md
• docs/adr/0003-coding-agent-via-cluster-gateway-proxy.md
• docs/adr/0004-local-sm-api-in-repo-stub.md
• docs/adr/0005-namespaced-componenttype-local-provisioning.md
• docs/adr/0006-dual-mode-oc-auth-impersonation.md
• docs/adr/0007-build-git-secret-via-openchoreo.md