docs: add function list table plan and consolidate guides

twoGiants · twoGiants · commit 5176fff746f4 · 2026-04-02T16:33:28.000+02:00
Finalize feature design with merging hook pattern, update
features.json steps, create implementation plan 002, and
add raw deployer PoC note to design doc. Consolidate
duplicate commit message rules into a single guide with
authorship modes.

Add page/component/hook rules to ARCHITECTURE.md. Clarify
one-at-a-time TDD in TESTING.md. Update init-session to
hand off to Feature Development Sequence. Log Cypress
sandbox blocker in agent-struggles.json.

Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;

Signed-off-by: Stanislav Jakuschevskij &lt;sjakusch@redhat.com&gt;
diff --git a/.claude/commands/commit-user.md b/.claude/commands/commit-user.md
@@ -3,93 +3,19 @@ allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git log:*), Bash(git di
 description: Draft a git commit message (interactive — does NOT commit)
 ---
 
-# Git Commit Message Guidelines
+# Commit (Interactive)
 
-Draft a git commit message following these rules. DO NOT commit — show the message and terminal command only.
+Draft a commit message following `docs/references/commit-message-guide.md`. Do NOT commit — show the message and the terminal command only.
 
-## The Seven Rules
+## Steps
 
-1. Separate subject from body with a blank line
-2. Limit the subject line to 50 characters
-3. Use conventional commit spec for subject line
-4. Do not end the subject line with a period
-5. Use the imperative mood in the subject line
-6. Wrap the body at 72 characters
-7. Use the body to explain what and why vs. how
-
-## Format
-
-```txt
-<type>: <subject - max 50 chars total, imperative mood, conventional commit spec>
-
-<Body - wrapped at 72 chars, explains what and why>
-<Optional bullet points for clarity>
-<Optional "Issue $ARGUMENTS" if provided>
-```
-
-## Conventional Commits
-
-- Use conventional commits spec with types: feat, fix, refactor, docs, test, chore, style, perf, ci, build
-- Format: `<type>: <description>`
-- Examples: "feat: add user authentication", "fix: resolve memory leak in cache"
-- Use "feat" only on user-facing changes
-
-## Subject Line
-
-- Write as if completing: "If applied, this commit will..."
-- Include type prefix (conventional commits)
-- Total length max 50 chars including type
-- Examples: "refactor: simplify cache handling", "fix: prevent race condition"
-- NOT: "refactored cache", "fixed the race"
-
-## Body
-
-- Explain the motivation for the change
-- Explain the "what" and "why" vs. "how" which means:
-  - the way things worked before the change (and what was wrong with that),
-  - the way they work now,
-  - and why I decided to solve it the way I did,
-  - and if you're not sure about the "why" then ask me.
-- Focus on context, not implementation details
-- Find a balance for message length, i.e. analyze the diff and decide if a shorter message is enough or more explanation is needed
-- Don't overuse bullet points (-, \*, +), add them only in bigger commits if they are helpful
-- Keep it short if there aren't many changes
-
-### Example
-
-Here is a good example from a [commit to the Bitcoin core](https://github.com/bitcoin/bitcoin/commit/eb0b56b19017ab5c16c745e6da39c53126924ed6).
-
-```txt
-   refactor: simplify serialize.h's exception handling
-
-   Remove the 'state' and 'exceptmask' from serialize.h's stream
-   implementations, as well as related methods.
-
-   As exceptmask always included 'failbit', and setstate was always
-   called with bits = failbit, all it did was immediately raise an
-   exception. Get rid of those variables, and replace the setstate
-   with direct exception throwing (which also removes some dead
-   code).
-
-   As a result, good() is never reached after a failure (there are
-   only 2 calls, one of which is in tests), and can just be replaced
-   by !eof().
-
-   fail(), clear(n) and exceptions() are just never called. Delete
-   them.
-```
-
-## Context
-
-- Current git status: !`git status`
-- Current git diff (staged and unstaged changes): !`git diff HEAD`
-- Current branch: !`git branch --show-current`
-- Recent commits (use for style reference only commits from me, Stanislav Jakuschevskij): !`git log --oneline -10`
-
-## Task
-
-1. Analyze the staged changes from git diff
-2. New added features and fixes are more important than other types like refactoring, etc.
-3. Draft a commit message following all seven rules
-4. Use conventional commits spec
+1. Run in parallel:
+   - `git status`
+   - `git diff HEAD`
+   - `git branch --show-current`
+   - `git log --oneline -10` (style reference — only match commits from Stanislav Jakuschevskij)
+2. Analyze the diff and draft a message following all seven rules
+3. New features and fixes take priority over refactoring for the commit type
+4. Use tandem authorship (Co-Authored-By trailer)
 5. If $ARGUMENTS is provided, add "Issue $ARGUMENTS" at the bottom
+6. Show the message and the `git commit` command — do NOT execute it
diff --git a/.claude/commands/init-session.md b/.claude/commands/init-session.md
@@ -25,4 +25,4 @@ Execute the startup sequence from `docs/WORKFLOW.md`. AGENTS.md is always in con
 
 6. **Run tests** — run `yarn test` and verify app is healthy.
 
-7. **Wait** — tell the user you're oriented, report the picked feature, and ask what they'd like to work on. Do NOT start any work autonomously.
+7. **Wait** — tell the user you're oriented, report the picked feature and which step of the Feature Development Sequence you'd start at. When the user says to proceed, follow the Feature Development Sequence in `docs/WORKFLOW.md` step by step. Do NOT start any work autonomously.
diff --git a/.claude/commands/session-commit.md b/.claude/commands/session-commit.md
@@ -20,25 +20,42 @@ Automate end-of-session cleanup: stage, log progress, commit.
    - Never stage files that likely contain secrets (.env, credentials, etc.)
    - Skip if everything is already staged
 
-3. **Update progress log** — read `docs/claude-progress.txt`, then prepend a new entry at the top (after the header line) following the format documented in `AGENTS.md` under `claude-progress.txt`.
+3. **Update progress log** — read `docs/claude-progress.txt`, then prepend a new entry at the top (after the header line) following the format in `docs/references/claude-progress-readme.md`.
    - Analyze the staged diff to determine what was done
    - Use today's actual date
    - Be concise but complete
    - Stage the updated file: `git add docs/claude-progress.txt`
 
-4. **Draft and commit** — follow all commit message rules from `.claude/commands/commit-user.md`. Use a HEREDOC and append a Co-Authored-By trailer:
+4. **Migrate blockers** — if the progress entry you just wrote has a `Blockers:` line that is NOT `None`:
+   - Read `docs/agent-struggles.json`
+   - For each blocker, append an entry:
+
+     ```json
+     {
+       "date": "<today>",
+       "description": "<blocker text from progress entry>",
+       "cause": "<your best short assessment>",
+       "suggestion": "<what would fix or prevent this>",
+       "resolved": false
+     }
+     ```
+
+   - Stage: `git add docs/agent-struggles.json`
+
+5. **Draft and commit** — follow all rules from `docs/references/commit-message-guide.md`. Determine authorship mode (tandem vs autonomous) from the guide. Use a HEREDOC:
+
    ```bash
    git commit -m "$(cat <<'EOF'
    <type>: <subject>
 
    <body>
 
-   Co-Authored-By: Claude <noreply@anthropic.com>
+   <authorship trailer>
    EOF
    )"
    ```
 
-5. **Verify** — run `git status` and `git log --oneline -1` to confirm success.
+6. **Verify** — run `git status` and `git log --oneline -1` to confirm success.
 
 ## Rules
 
diff --git a/.gitignore b/.gitignore
@@ -22,6 +22,7 @@ AGENTS.override.md
 .claude/settings*.json
 .claude/pr/*
 .mcp*
+.tmp
 
 # Editors
 *.code-workspace
diff --git a/AGENTS.md b/AGENTS.md
@@ -22,4 +22,4 @@ See `docs/design/` for full design specs.
 | `docs/claude-progress.txt` | Session handoff log — see [`references/claude-progress-readme.md`](docs/references/claude-progress-readme.md) |
 | `docs/agent-struggles.json` | Struggle log — see [`references/agent-struggles-readme.md`](docs/references/agent-struggles-readme.md) |
 | `docs/references/ocp-plugin-guide.md` | OCP dynamic plugin mechanics, i18n, extension points |
-| `docs/references/commit-message-agent-readme.md` | Git commit conventions |
+| `docs/references/commit-message-guide.md` | Git commit conventions and authorship rules |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -39,6 +39,14 @@ Arrows mean "imports / depends on."
 - Services never import Components or Views
 - No circular dependencies
 
+## Page / Component / Hook Rules
+
+**Components are simple** — they receive data via props, render it, and call callbacks to return data to the parent (or use context). No logic at the top of a component.
+
+**Pages are smart** — they use central hooks (e.g. `useClusterService`, `useSourceControl`) to fetch, prepare, and transform all data needed for downstream components.
+
+**Extract logic into hooks** — if a page or component has any logic (state management, data transformation, side effects), extract it into a co-named hook: `FunctionTable.tsx` → `useFunctionTable.ts`, `FunctionsListPage.tsx` → `useFunctionsListPage.ts`. If there is no logic, no hook is needed.
+
 ## Architectural Guidance
 
 - PatternFly components preferred over custom HTML
diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -2,7 +2,14 @@
 
 ## Approach
 
-Red/green/refactor TDD. Write tests first, implement to pass, then refactor to improve code if applicable.
+Red/green/refactor TDD — **one test at a time**:
+
+1. Write one test case (red)
+2. Write the minimum implementation to make it pass (green)
+3. Refactor if needed
+4. Move to the next test case
+
+Do NOT write all test cases first and then implement everything at once.
 
 ## Test Layers
 
diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md
@@ -16,7 +16,7 @@ Every session, before doing any work:
 
 After [Startup Sequence](#startup-sequence), work through the picked feature:
 
-1. **Plan** — read `docs/ARCHITECTURE.md` + `docs/STYLEGUIDE.md` + `docs/TESTING.md`, then create implementation plan → `docs/plans/active/<incremented-number>-feature-<short-name>.md`
+1. **Plan** — read `docs/ARCHITECTURE.md` + `docs/STYLEGUIDE.md` + `docs/TESTING.md`, then use `/brainstorming` to design the chosen feature from `docs/features.json`, then use `/writing-plans` to create implementation plan → `docs/plans/active/<NNN>-<type>-<short-name>.md`
 2. **Branch** — create feature branch per [Branching](#branching) convention
 3. **Implement** — using `/executing-plans` skill
 4. **Review** — code review using `/requesting-code-review` skill, fix found issues
@@ -28,22 +28,22 @@ After [Startup Sequence](#startup-sequence), work through the picked feature:
 
 ## Branching
 
-Create a feature branch per plan: `<NNN>-<type>-<short-name>` where `<NNN>` matches the plan number and `<type>` the conventional commit type as per our [Git Commit Guide](references/commit-message-agent-readme.md#conventional-commits). Example: `001-feat-function-list-empty-state`.
+Create a feature branch per plan: `<NNN>-<type>-<short-name>` where `<NNN>` matches the plan number and `<type>` the conventional commit type as per our [Git Commit Guide](references/commit-message-guide.md#conventional-commits). Example: `001-feat-function-list-empty-state`. If we're on a feature branch already do nothing.
 
 ## Pull Requests
 
 Open PRs via `gh pr create` using the template at `.github/pull_request_template.md`.
 
 **Title format:** `<Type>: <Sentence ending with a period.>` — capitalize the type and the first word, end with a period. Example: `Feat: Add function list page with empty state.`
 
-Types are the same as [conventional commits](references/commit-message-agent-readme.md#conventional-commits) but capitalized.
+Types are the same as [conventional commits](references/commit-message-guide.md#conventional-commits) but capitalized.
 
 ## Session Rules
 
 - One feature at a time
 - Clean state at end (code suitable for merging to main)
 - Update [`docs/claude-progress.txt`](references/claude-progress-readme.md) before session ends
-- Commit work to git before ending — follow [`docs/references/commit-message-agent-readme.md`](references/commit-message-agent-readme.md) strictly
+- Commit work to git before ending — follow [`docs/references/commit-message-guide.md`](references/commit-message-guide.md) strictly
 
 ## Continuous Improvement
 
diff --git a/docs/agent-struggles.json b/docs/agent-struggles.json
@@ -1 +1,23 @@
-[]
+[
+  {
+    "date": "2026-03-31",
+    "description": "Playwright browser plugin cannot execute inside nono sandbox — browser binary not found or npm cache not accessible",
+    "cause": "nono sandbox restricts access to Playwright browser binaries",
+    "suggestion": "Either pre-install Playwright browsers in the sandbox profile or add browser binary path to nono allow-list",
+    "resolved": true
+  },
+  {
+    "date": "2026-04-01",
+    "description": "Concurrent Claude sessions break nono sandbox — EACCES on .claude.json after external session atomically writes it",
+    "cause": "Landlock grants are inode-based; atomic writes (write temp + rename) replace the inode, invalidating the sandbox grant",
+    "suggestion": "Avoid running Claude outside sandbox while sandbox is active, or symlink .claude.json into $HOME/.claude/ directory which has full access",
+    "resolved": false
+  },
+  {
+    "date": "2026-04-01",
+    "description": "Cypress cannot run inside nono sandbox — EACCES on ~/.config/Cypress and /run/user/ dconf",
+    "cause": "Cypress needs write access to ~/.config/Cypress and /run/user/<uid>/dconf, neither of which are in the nono allow-list",
+    "suggestion": "Add ~/.config/Cypress (readwrite) and /run/user (readwrite) to the nono sandbox profile, or run Cypress outside the sandbox",
+    "resolved": false
+  }
+]
diff --git a/docs/claude-progress.txt b/docs/claude-progress.txt
@@ -1,6 +1,39 @@
 # Claude Progress Log
 # Newest entries first. Agents: append your entry at the top after the header.
 
+---
+## 2026-04-01 | Session: Nono sandbox Playwright fix + docs consolidation
+Worked on: Resolved Playwright browser blocker in nono sandbox, consolidated commit message docs, added planning guide and architecture rules
+Completed:
+- Fixed Playwright MCP in nono sandbox (added /proc, /etc/fonts, /opt/google/chrome read; $HOME/.npm allow; npx allowed_command)
+- Resolved agent-struggles.json Playwright blocker entry
+- Added session-commit step to migrate blockers from progress log to agent-struggles.json
+- Consolidated commit message docs: single source of truth in commit-message-guide.md, slimmed commit-user.md and session-commit.md, deleted commit-message-agent-readme.md
+- Created planning-guide.md (plans outline test cases, not full code)
+- Added page/component/hook rules to ARCHITECTURE.md
+- Clarified TDD approach in TESTING.md (one test at a time)
+- Simplified 002-function-list-table.md plan (removed all code, kept test case outlines)
+Left off: Execute function list table plan. Nono Landlock inode issue with .claude.json (concurrent sessions cause EACCES)
+Blockers: Concurrent Claude sessions break nono sandbox — Landlock inode grants invalidated when external session atomically writes .claude.json
+
+---
+## 2026-03-31 | Session: Function list table design + nono sandbox setup
+Worked on: Designed function list table feature, set up nono sandbox for autonomous development
+Completed:
+- Brainstormed and finalized feature design (table with name, runtime, status, url, replicas, actions columns)
+- Designed useFunctionsList merging hook (repos + deployments → FunctionListItem[])
+- Updated features.json with refined feature steps
+- Updated design doc with merging hook pattern and raw deployer PoC note
+- Created implementation plan (docs/plans/active/002-function-list-table.md)
+- Captured real K8s deployment response (.tmp/k8s-deployment-response.json)
+- Captured real GitHub search response (.tmp/gh-search-response.json)
+- Created fine-grained GitHub PAT scoped to func-console (read + PR write)
+- Set up nono sandbox profile (claude-code-func-console) with credential injection
+- Verified: gh api, yarn test, plugin loading all work in sandbox
+- Verified: destructive commands blocked (rm, oc, sudo, ssh keys)
+Left off: Playwright browser access not working in sandbox (needs investigation). Ready to execute plan.
+Blockers: Playwright plugin can't execute browser inside nono sandbox — needs either npm cache fix or browser binary permission
+
 ---
 ## 2026-03-30 | Session: Replace nginx with Go backend
 Worked on: Replaced nginx reverse proxy with custom Go backend server
diff --git a/docs/design/2026-03-16-faas-poc-design.md b/docs/design/2026-03-16-faas-poc-design.md
@@ -290,6 +290,8 @@ interface ClusterService {
 - `function.knative.dev/name: <name>` — function name
 - `function.knative.dev/runtime: <runtime>` — runtime (node, python, go)
 
+**PoC note:** Cluster does not have Knative or KEDA installed. Functions are deployed with the `raw` deployer (plain K8s Deployment + Service). Labels are set identically by func CLI regardless of deployer type. URL is internal service DNS: `http://<name>.<namespace>.svc`.
+
 #### Error Handling
 
 Hook errors reported internally via `useEffect` → `addError()` with ref dedup. `deleteFunction` rejection handled by caller via try/catch → `addError()`.
@@ -327,6 +329,35 @@ const svc = useFunctionService();
 
 Swapping implementations = change what the hook returns. Zero component changes.
 
+### View-Level Merging Hook
+
+The Functions List Page needs data from **both** services. A dedicated merging hook (`useFunctionsList`) composes the two service hooks and produces a unified list:
+
+```tsx
+// useFunctionsList: merges GitHub repos (source of truth) with cluster status
+export function useFunctionsList(): { functions: FunctionListItem[]; loaded: boolean } {
+  const { repos, loaded: reposLoaded } = useSourceControl();
+  const { functions: deployments, loaded: deploymentsLoaded } = useClusterService();
+
+  const functions = mergeFunctionData(repos, deployments);
+  return { functions, loaded: reposLoaded && deploymentsLoaded };
+}
+```
+
+```typescript
+// FunctionListItem: merged view of repo + deployment
+interface FunctionListItem {
+  name: string;
+  namespace: string;
+  runtime: string;
+  status: DeployedFunction['status'] | 'NotDeployed';
+  url?: string;
+  replicas: number;
+}
+```
+
+Merge logic: iterate repos (source of truth), find matching deployment by name. Deployed functions get cluster status; undeployed functions get `status: 'NotDeployed'`. The merge function (`mergeFunctionData`) is pure and tested separately.
+
 ---
 
 ## Views
diff --git a/docs/features.json b/docs/features.json
@@ -36,9 +36,11 @@
     "description": "Function List Page renders a table with function entries",
     "steps": [
       "Navigate to /functions route",
-      "Table renders with columns: name, runtime, status",
-      "Each row displays function data from mock data",
-      "Function name is a clickable link"
+      "Table renders with columns: name, runtime, status, url, replicas, actions",
+      "Each row displays function data from hardcoded real API responses",
+      "URL column shows shortened clickable link",
+      "Clicking function row or edit action button redirects to /functions/edit/:name",
+      "Actions column has edit and delete icon buttons"
     ],
     "passes": false
   },
diff --git a/docs/plans/active/002-function-list-table.md b/docs/plans/active/002-function-list-table.md
diff --git a/docs/plans/completed/001-function-list-empty-state.md b/docs/plans/completed/001-function-list-empty-state.md
diff --git a/docs/references/commit-message-agent-readme.md b/docs/references/commit-message-agent-readme.md
diff --git a/docs/references/commit-message-guide.md b/docs/references/commit-message-guide.md

Original file line number	Diff line number	Diff line change
@@ -25,4 +25,4 @@ Execute the startup sequence from `docs/WORKFLOW.md`. AGENTS.md is always in con
`25`	`25`
`26`	`26`	6. Run tests — run `yarn test` and verify app is healthy.
`27`	`27`
`28`		`-7. Wait — tell the user you're oriented, report the picked feature, and ask what they'd like to work on. Do NOT start any work autonomously.`
	`28`	+7. Wait — tell the user you're oriented, report the picked feature and which step of the Feature Development Sequence you'd start at. When the user says to proceed, follow the Feature Development Sequence in `docs/WORKFLOW.md` step by step. Do NOT start any work autonomously.