# AGENT.md

## Git Workflow

This project requires all agent work to happen on a dedicated feature branch — never directly on `main` (or `master`/`develop`).

### Rule: One Branch Per Task

For **every new task**, before making any code changes, the agent must:

1. **Sync with the base branch**
   ```bash
   git checkout main
   git pull origin main
   ```

2. **Update Ticket status to in progress
   - Before fetching, update the ticket status to "In Progress": `curl -X PUT https://desk50.parvillanueva.site/api/tickets/{id}/status -H 'Content-Type: application/json' -d '{"status":"In Progress"}'`
   - Post the plan as a comment to the ticket (only if this is not a revision): `curl -X POST https://desk50.parvillanueva.site/api/tickets/{id}/comments -H 'Content-Type: application/json' -d '{"content":"<plan>"}'`

3. **Create a new feature branch**
   ```bash
   git checkout -b <branch-name>
   ```

   Branch naming convention:
   ```
   <type>/<short-task-description>
   ```
   Where `<type>` is one of:
   - `feature/` — new functionality
   - `fix/` — bug fixes
   - `chore/` — tooling, config, maintenance
   - `docs/` — documentation-only changes
   - `refactor/` — code restructuring with no behavior change

   Examples:
   ```
   feature/add-user-auth
   fix/null-pointer-checkout
   chore/upgrade-deps
   docs/update-readme
   refactor/simplify-api-client
   ```

4. **Do all work for the task on this branch only.**
   Do not commit directly to `main`. Do not reuse a branch from a previous, unrelated task.

5. **Write unit tests for any new or changed functionality**
   Place tests alongside the code they cover using the naming convention `*.test.ts` or `*.spec.ts`. Run them to confirm they pass before committing:
   ```bash
   npm test
   ```

6. **Write or update a Playwright acceptance test for the change**
   For any change affecting front-end or WFBO admin behavior, add or update a spec under `tests/acceptance_test/front/` or `tests/acceptance_test/wfbo/`, following the existing `tests/acceptance_test/helpers.ts` conventions (`loginAs`/`registerAndLogin` helpers, `data-testid` locators).

   **Before running acceptance tests, reset the database and load test fixtures:**
   ```bash
   php bin/console doctrine:fixtures:load --no-interaction
   ```

   Run it and confirm it passes:
   ```bash
   npm run test:e2e:front   # or test:e2e:wfbo, or test:e2e for both
   ```

7. **Capture screenshot + video evidence of the change working**
   Re-run just the spec(s) touched by this task with recording forced on, into a clean output directory:
   ```bash
   rm -rf test-results/mr-evidence
   npm run test:e2e:record -- tests/acceptance_test/<front|wfbo>/<spec>.spec.ts --output=test-results/mr-evidence
   find test-results/mr-evidence -name '*.webm' -o -name '*.png'
   ```
   `test:e2e:record` sets `PW_RECORD=1`, which forces `screenshot: 'on'` and `video: 'on'` in `playwright.config.ts` for that run only (the default failure-only capture used by CI is untouched). Keep these files — they get attached to the MR in a later step.

8. **Review code for coding standards**
   Run linting to check for code quality and style issues:
   ```bash
   npm run lint
   ```

9. **Commit with clear, scoped messages**
   ```bash
   git add .
   git commit -m "<type>: <concise description>"
   ```
   Do not append `Co-Authored-By: Claude ...` or `Claude-Session: ...` trailer lines to the commit message.

10. **Push the branch**
   ```bash
   git push -u origin <branch-name>
   ```

11. **Open a PR (if applicable) instead of merging directly.**
   Leave `main` merges to human review/approval unless explicitly instructed otherwise.
   - Post the PR as a comment to the ticket: `curl -X POST https://desk50.parvillanueva.site/api/tickets/{id}/comments -H 'Content-Type: application/json' -d '{"content":"<pr link>"}'`
   - update the ticket status to "For Deployment": `curl -X PUT https://desk50.parvillanueva.site/api/tickets/{id}/status -H 'Content-Type: application/json' -d '{"status":"For Deployment"}'`


### Rule: Never Skip Branch Creation

- If the agent is already on a feature branch from a **different** task, it must switch back to `main`, pull, and create a **new** branch before starting the next task — do not stack unrelated work onto an existing branch.
- If uncertain whether a task is "new," default to creating a new branch.

### Rule: No AI Attribution Trailers

Commit messages and merge request descriptions must **not** include any `Co-Authored-By: Claude ...` or `Claude-Session: ...` trailer lines. Omit these regardless of default tooling behavior.

### Rule: Open a Merge Request When the Task Is Done

After pushing the feature branch, open a merge request (MR) against `main` instead of merging directly. Do not merge your own MRs — leave that to human review/approval unless explicitly instructed otherwise. Do not include `Co-Authored-By` or `Claude-Session` trailers in the MR description.

**Requirements:**
- A `GITLAB_TOKEN` environment variable with at least `api` scope must be set. Never hardcode the token in scripts, commits, or this file.
- Know the project path (`namespace/project`) or numeric project ID.

**Create the MR (GitLab SaaS — gitlab.com):**

```bash
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/merge_requests" \
  --data-urlencode "source_branch=<feature/your-branch-name>" \
  --data-urlencode "target_branch=main" \
  --data-urlencode "title=<Your MR title>" \
  --data-urlencode "description=<Your MR description>" \
  --data-urlencode "remove_source_branch=true"
```

- `<NAMESPACE>%2F<PROJECT>` — URL-encode the project path (e.g. `mygroup%2Fmyproject`), or use the numeric project ID: `.../projects/12345678/merge_requests`.
- Optional extras: `--data-urlencode "labels=..."`, `--data-urlencode "assignee_id=..."`, `--data-urlencode "milestone_id=..."`.
- For self-hosted GitLab, replace `https://gitlab.com` with your instance URL.
- The MR-creation response is JSON — capture its `iid` field; that's the `<MR_IID>` used below.

### Rule: Attach Test Evidence to the MR

After the MR exists, upload each screenshot/video captured in step 6 and post it as a comment.
GitLab attachments are a two-call flow: upload the file to get a `markdown` snippet back, then
post that snippet in a note. GitLab renders both images and video (mp4/webm/mov) inline from it.

```bash
# 1. Upload the file to the project, capture the markdown GitLab returns
MARKDOWN=$(curl --silent --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/uploads" \
  --form "file=@test-results/mr-evidence/<path-to-file>" | jq -r '.markdown')

# 2. Post a note on the MR with that markdown
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/merge_requests/<MR_IID>/notes" \
  --data-urlencode "body=### Acceptance test evidence

$MARKDOWN"
```

Repeat per file (screenshot and video), or concatenate multiple `markdown` snippets into one note
body. Do not include `Co-Authored-By` or `Claude-Session` trailers in the note.

### Quick Reference

```bash
# Start of every task
git checkout main
git pull origin main
git checkout -b feature/<task-name>

# ... do the work ...

# Write and run tests
npm test

# Reset data before running acceptance tests
php bin/console doctrine:fixtures:load --no-interaction

# Write/update and run the relevant Playwright acceptance test
npm run test:e2e:front   # or test:e2e:wfbo

# Capture screenshot + video evidence
rm -rf test-results/mr-evidence
npm run test:e2e:record -- tests/acceptance_test/<front|wfbo>/<spec>.spec.ts --output=test-results/mr-evidence

# Review code for coding standards
npm run lint

git add .
git commit -m "<type>: <description>"
git push -u origin feature/<task-name>

# Open the MR (note the returned "iid")
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/merge_requests" \
  --data-urlencode "source_branch=feature/<task-name>" \
  --data-urlencode "target_branch=main" \
  --data-urlencode "title=<MR title>" \
  --data-urlencode "remove_source_branch=true"

# Upload evidence and comment on the MR
MARKDOWN=$(curl --silent --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/uploads" \
  --form "file=@test-results/mr-evidence/<path-to-file>" | jq -r '.markdown')

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/merge_requests/<MR_IID>/notes" \
  --data-urlencode "body=### Acceptance test evidence

$MARKDOWN"
```

## Commands

### `pick [ticket no]`
- Use `curl https://desk50.parvillanueva.site/api/tickets/{id}` from the project root to fetch ticket data.
- Before fetching, update the ticket status to "In Progress": `curl -X PUT https://desk50.parvillanueva.site/api/tickets/{id}/status -H 'Content-Type: application/json' -d '{"status":"In Progress"}'`
- Read the ticket title, description, category, priority, severity, status, steps, comments, and audit logs.
- Create a structured plan from the fetched data addressing the ticket's requirements.
- Output the plan in a clear, actionable format with checkboxes.
- Post the plan as a comment to the ticket (only if this is not a revision): `curl -X POST https://desk50.parvillanueva.site/api/tickets/{id}/comments -H 'Content-Type: application/json' -d '{"content":"<plan>"}'`