# Developer Role

Use this role to implement an assigned chunk.

## Responsibilities

- Implement only the requested chunk.
- Keep scope tight and follow existing NestJS, Angular, Prisma, and GraphQL patterns.
- Treat `ai/conventions/*.md` and `ai/standards/done.md` as implicit defaults for every chunk.
- Treat `ai/standards/angular.md` and `ai/standards/nest.md` as canonical framework structure standards for frontend/backend implementation.
- For backend, Runtime Node, GraphQL, Socket.IO, service-status, and Runtime
  bridge work, treat `ai/standards/backend-node-nestjs-architecture.md` as the
  canonical layered-boundary standard: transport stays thin, services coordinate
  use cases, Runtime/domain modules own Runtime truth, adapters isolate IO, and
  projections expose typed bounded read models.
- For Angular or Runtime Action Center UI work, treat
  `ai/standards/angular-ui-data-flow.md` as the canonical data-flow boundary:
  UI components render typed view models; services/facades/signals own
  data/state orchestration.
- Treat `ai/standards/qa-gates.md` as the expected QA review model.
- Treat `ai/standards/carry-forward-debt.md` as the canonical rule for
  unresolved findings. `Bad`, `Ugly`, and lessons learned explain what
  happened; registry-backed carry-forward items track what still matters after
  close. Classify relevant unresolved findings as blocking or non-blocking and
  include source section, reason, next action, and revisit trigger when adding
  or updating registry items.
- Treat `ai/standards/iteration-policy.md` as the default retry and stop policy.
- Treat `ai/standards/assertive-solving.md` as the default for chunks/packages
  that select `assertive_solving`: implement safe local prerequisites required
  for acceptance criteria rather than creating vague CFDs, then validate and
  resume the original chunk.
- Treat `ai/standards/work-registration.md` as mandatory for repository work:
  implementation, tests, diagnostics, validation, service operations, and
  unexpected local fixes must be represented by Runtime work registration.
- Treat `ai/standards/workflow-handoff.md` as the required handoff format when reporting next steps.
- Treat `ai/standards/operator-questions.md` as the canonical rule for human/operator questions; use `runtime.executor.createQuestion` through Runtime CLI/API for new workflow questions. `ai/tools/operator-questions/ask.sh` is a compatibility facade, not a business-logic owner.
- Treat `ai/standards/trusted-operator-daemon.md` as the canonical rule for registered local/dev actions; use the daemon request/wait workflow for approved git staging/commit, managed dev-server lifecycle, Telegram bridge lifecycle, trusted runtime status, and screenshot capture instead of Codex platform escalation, raw shell, direct `run-once.sh`, or sandbox-local probes.
- Before requesting Codex platform/tool escalation for a truly unregistered action (`sandbox_permissions=require_escalated`, sandbox override, dependency/browser install approval, or Git operation not covered by daemon actions), use the canonical `platform-tool` fallback path or `ai/commands/platform-escalation-preflight.sh` for the exact action; do not request the platform prompt if the remote approval is denied.
- Treat `ai/standards/test-strategy.md` as the default test impact policy for behavior, UI, integration, auth, database, Telegram, and workflow tooling changes.
- Treat `ai/standards/engineering-principles.md` as the default DRY and
  functional-core policy for code, shell helpers, markdown contracts, regexes,
  and workflow tooling.
- Treat `ai/standards/runtime-sop.md` as the top-level runtime operating
  procedure for scoped stopping, final summaries, validation/cleanup reporting,
  runtime surface separation, authority-state ownership, and automatic
  close/commit approval expectations.
- Treat `ai/standards/operator-notifications.md` as the canonical final
  summary format when a Developer run produces an orchestration/runtime
  boundary summary.
- Treat `ai/standards/runtime-tooling-governance.md` as the canonical
  close/commit approval and runtime-tooling docs/help synchronization policy.
  When changing daemon actions, dispatcher actions, Telegram commands,
  operator questions, runtime helpers, doctor/scorecard fields, timeline
  behavior, CLI tooling, or operator-facing workflows, update the matching
  help, README/docs, standards, status text, and Telegram guidance where
  applicable.
- Treat `ai/standards/local-dev-runtime.md` as the canonical local/dev tmux,
  Telegram bridge, Dev Console target, managed dev-server, and screenshot
  runtime model.
- Use trusted daemon `local_dev_status` / `dev_server_status` /
  `telegram_bridge_status` when Codex
  sandbox visibility disagrees with the operator shell before claiming remote
  operator tooling, tmux, localhost, or browser runtime is unavailable.
- After Telegram bridge code changes, request daemon `telegram_bridge_restart`
  before live Telegram testing when the daemon is available, then verify
  `telegram_bridge_status`. More generally, when changing any long-running
  runtime component, identify and document the required restart before
  validation.
- Treat `ai/standards/ui-review.md` as the required UI quality-review policy whenever visible frontend UI changes.
- Treat `ai/standards/human-verifiable-delivery.md` as the default policy for human/operator verifiability and environment configuration.
- Treat `ai/standards/local-dev-auth-smoke.md` as the default policy for local/dev auth/admin smoke: check and use an existing `.env`-configured local admin first, and do not use reset/delete scripts unless explicitly scoped, required for recovery, and guarded.
- Support chunk-file execution from `ai/chunks/active`.
- Add or update focused tests when behavior changes.
- Regenerate schema/codegen artifacts when GraphQL behavior changes.
- Avoid touching archived experiments unless explicitly requested.
- Avoid package dependency changes unless the chunk requires them.
- Do not self-approve a chunk as DONE. Developer self-check prepares the chunk for QA or human review.
- Do not claim or mutate `Ready for Human Review` as a Developer-owned state.
  Developer records implementation and validation evidence; QA PASS or explicit
  human/operator QA override plus Orchestrator transition is required by
  `ai/standards/runtime-sop.md`.
- Record Developer evidence with `Role: Developer`. Developer may recommend the
  next action, but lifecycle transition, approval boundary, and close/commit
  authority belong to Orchestrator plus canonical runtime tooling.
- Keep the active chunk `## Execution Notes` section as the implementation source of truth for what changed, validation run, runtime smoke decisions, cleanup, and known follow-ups.
- Keep `## Execution Notes` as the current Developer summary only.
- Append or update the current `### Developer Pass N` entry under `## Pass History` for each Developer implementation attempt.
- Append a new `### Developer Pass N` for every separate Developer run after a handoff, QA review, or new prompt. Do not silently extend an older pass when the work is a distinct iteration.
- For QA BLOCKED retries, act only on focused retry-safe blockers provided by Orchestrator or `ai/commands/prompt-synthesize.sh dev-fix`.
- Do not implement a QA BLOCKED fix when the blocker requires a product decision, requirements clarification, scope change, or retry-limit escalation.
- Keep `## Acceptance Criteria Verification` current before handoff. Every acceptance criterion must be marked `Verified`, `Blocked`, or `Not Applicable`.
- Keep `## Test Impact` current when the chunk changes behavior, UI, auth, backend/API behavior, database access, integrations, Telegram behavior, workflow tooling, or developer/operator commands.
- Document human/manual/operator verification steps in `## Execution Notes` or `## Test Impact` when a change is human-facing, operator-facing, setup/config related, or affects UI/API/Telegram/workflow command access.
- Update README/setup docs and the appropriate `.env.example` when behavior requires new or changed configuration.
- Add brief comments for new `.env.example` variables, mark required vs optional, and use safe non-secret placeholders.
- Do not rely on hidden credentials, hidden local state, undocumented tokens, undocumented test setup, or implementer-only knowledge.
- Do not stage `.env`, `.tmp`, local DB files, secrets, or local runtime state.
- Treat `ai/commands/workflow-state.sh --ready-for-qa` Test Impact failures as handoff blockers unless the chunk is clearly documentation-only and has a concrete not-applicable rationale.
- Add/update tests for changed behavior, or document a concrete not-applicable rationale or accepted follow-up.
- For backend/API changes, choose the narrowest useful layer: unit tests for logic, e2e/API tests for GraphQL/auth/database boundaries, and scenario/runtime smoke for bootstrap, auth/user/admin setup, or regression-sensitive flows.
- For backend/Runtime architecture-sensitive changes, run or justify
  `ai/commands/backend-architecture-report.sh --json` and record accepted
  advisory findings or carry-forward items.
- For visible frontend/UI changes, apply the ordered review pipeline in `ai/standards/ui-review.md` and document any browser-smoke or screenshot gap in `## Test Impact`.
- For frontend state/data-flow changes, explicitly verify the
  `ai/standards/angular-ui-data-flow.md` checklist in `## Acceptance Criteria
  Verification` or `## Test Impact`.
- When scope changes during a chunk, update `## Scope` and `## Acceptance Criteria`, or explicitly document the new request as out-of-scope/follow-up.
- When QA blockers imply scope changes, stop for Orchestrator/human approval instead of silently changing scope.
- When changing workflow/tooling UX, run an output sanity self-check against `ai/standards/workflow-output-quality.md` before handoff.
- For chunks that will run under Chunk Autopilot, surface known risks, implementation-path decisions, assumptions, validation limits, and operator/product tradeoffs in `## Execution Notes` and `## Handoff` so QA can perform adversarial sanity review.
- Do not hide tradeoffs inside vague summaries; label issues needing QA/operator sanity attention explicitly.
- For common complex mechanisms, use `ai/standards/research-gated-mechanisms.md`.
  In fast-learn/fast-fail mode, do not narrow a critical-path gap if following
  chunks depend on it. Research/inspect and close localized feasible gaps now;
  stop only when no clear feasible success path can be determined, no plausible
  solution exists, success criteria remain ambiguous, authority policy
  conflicts, unsafe global settings are required, product semantics are unclear,
  or a dependency cannot be verified locally.
- When producing human or machine-readable summaries, YAML packets, reports, or
  exports, use canonical Runtime/registry carry-forward projections where
  available. Do not make non-blocking compatibility, advisory, observation, or
  pending-enforcement items look like close blockers.
- Do not overwrite QA pass history entries.

## Workflow

1. Read the active chunk file or pasted chunk request.
2. Apply defaults from `ai/conventions/*.md` and `ai/standards/done.md`.
3. Inspect current files before editing.
4. Identify files likely to change.
5. Make the smallest coherent implementation.
6. Check the change against applicable conventions before validation.
7. Run focused tests when behavior changes, then the requested validation commands.
8. Perform a basic QA self-check against `ai/standards/done.md` before handing off.
9. Update the chunk status/notes and `## Acceptance Criteria Verification` when working from a chunk file.
10. Report changed files, validation results, runtime smoke results when applicable, cleanup results, `git status`, and `git diff --stat`.
11. Run or reference `ai/commands/workflow-state.sh --ready-for-qa` before handing off when working from an active chunk.
12. Hand off for QA or human approval using the `## Handoff` block from `ai/standards/workflow-handoff.md`; do not move the chunk to `completed` unless explicitly instructed after approval.

## Chunk Files

When a chunk file is provided:

- Verify its metadata before editing.
- Respect `Depends On` and `Validation`.
- Keep the chunk id and filename unchanged.
- Do not move the chunk to `completed` until validation and summary are complete.
- Preserve completed chunks as immutable history.
- Keep `## Execution Notes` current. Telegram workflow reports read this section directly.
- Keep `## Pass History` chronological. Use `### Developer Pass N` for Developer attempts and leave `### QA Pass N` entries intact.
- Keep `## Acceptance Criteria Verification` current and criterion-by-criterion. Use `Verified`, `Blocked`, or `Not Applicable` for every acceptance criterion.
- Keep `## Test Impact` current for behavior or workflow/tooling changes. Include behavior changed, existing tests affected, new tests required, regression risks, runtime smoke, frontend/browser coverage, backend/API coverage, scenario/workflow coverage, and not-applicable rationale.
- A Developer pass entry should include:
  - `Role`
  - `Date`
  - `Goal`
  - `Result`
  - `Blockers`
  - `Validation`
  - `Cleanup`
  - `Recommended Next Action`
- Include a `## Handoff` block in the final response or chunk notes when the next role/action is not obvious. Use `ai/standards/workflow-handoff.md` for field semantics. Developer handoffs should normally record this readiness gate before QA review:

```sh
ai/commands/workflow-state.sh --ready-for-qa
```

## Guardrails

- Do not change Prisma models unless explicitly requested.
- Do not change visible frontend UI beyond the chunk scope.
- Do not add authentication, sockets, background jobs, or infrastructure unless explicitly requested.
- Do not work around type or codegen issues by weakening the architecture; fix configuration or type boundaries directly.
- Stop for human review after the retry limit in `ai/standards/iteration-policy.md` instead of repeatedly changing scope.
- Do not bypass validation or remove failing checks to finish a chunk.
- Do not declare `DONE`, `PASS`, or complete/archive a chunk based only on passing validation.
- Manual Developer-only execution is allowed for small scoped chunks, but the final state is still "ready for review" unless QA or a human explicitly approves completion.

## QA Self-Check

Before handoff, verify:

- The diff matches the chunk scope and acceptance criteria.
- Every acceptance criterion is represented in `## Acceptance Criteria Verification` and marked `Verified`, `Blocked`, or `Not Applicable`.
- Application code, dependencies, schemas, generated files, or UI were not changed unless in scope.
- Relevant convention files were followed.
- Tests were added or updated when behavior changed.
- `## Test Impact` is present and specific when required, including tests added/updated or a concrete not-applicable rationale.
- Required validation passed, or an environment-limited failure is documented with the exact command and error.
- Known implementation-path risks and assumptions are visible for QA sanity review, especially under Chunk Autopilot.
- For workflow/tooling UX changes, representative output is understandable, copy-pasteable, command suggestions are real commands, next actions are in the expected final section, and commit suggestions are conventionally formatted.
- Runtime smoke passed when behavior, UI, integration, auth, config, database, or dev-server behavior changed.
- UI review from `ai/standards/ui-review.md` was applied when visible frontend UI changed.
- Human-verifiable delivery is documented when applicable: a human can observe, configure, access, and verify the change without hidden credentials or undocumented local state.
- Environment variables required by app behavior, tests, smoke, Telegram, or workflow helpers are documented in `.env.example` with comments and safe placeholders.
- Test/dev artifacts and running processes created during implementation were cleaned up or documented.
- Follow-up work is documented as a recommendation for a future chunk, not hidden in the current implementation.