# Upstream Issue Filing

In v2 the platform ships as the `@stravica-ai/digital-operator-pa` npm package and is developed in the `Stravica/engineering-pa-dev` repository. When you find a bug or gap in the platform, file a GitHub issue against `Stravica/engineering-pa-dev` so the fix lands in one place and reaches every operator via the next package release.

This document is the lookup-on-demand reference for that workflow. The CLAUDE.md core rule "Platform code is read-only; never edit `node_modules/`" establishes the discipline; this doc is the procedure.


## When to file an issue

- A bug in any platform-supplied module (wrong behaviour, broken invariant, regression).
- A platform enhancement request (new capability, better ergonomics, missing flag).
- Platform docs are wrong, unclear, or out of date.
- A platform tool violates the tooling standard at `@stravica-ai/engineering-pa-core/docs/standards/tooling.md`.


## When NOT to file

- Bugs in your operator content (`operator/`, `work/`, `projects/`, `agents/`); those are local to your repo. Fix them directly.
- Operator-specific workflow questions; those do not generalise to other operators.
- Anything you can fix locally by adjusting your `operator/extensions/` without touching the package.
- Questions that are really requests for the operator's judgement.


## How to file

Use `gh issue create` against `Stravica/engineering-pa-dev`. Compose the body in a structured way:

```
gh issue create \
  --repo Stravica/engineering-pa-dev \
  --title "<short title, <=160 chars>" \
  --body "$(cat <<'EOF'
## Type
bug | enhancement | docs | question

## Summary
What, and why.

## Reproducer
(Required for bug.)
Steps to reproduce against a clean operator instance.

## Environment
- Package version: <pnpm list @stravica-ai/digital-operator-pa --depth=0>
- Node version: <node --version>
- OS family: <linux | macos | windows>

## Proposed solution
(Optional.)

## Work-item ref
(Optional; local work-item ID for trace-back only; we don't read the file.)
EOF
)"
```

Check for duplicates first:

```
gh issue list --repo Stravica/engineering-pa-dev --search "<keywords>"
```


## Never include in an upstream issue

Upstream issues are public during dev and stay public after the repo flips to `Stravica/engineering-pa`. The following categories of content must not appear in any field you submit:

- Secrets of any kind (API keys, tokens, passwords).
- Anything read from `.vault/` or any `.env` file.
- Contents of `operator/profile/`; that is the operator's private profile.
- Contents of `operator/memory/`; that is your learned-memory store.
- Contents of `.session/environment.json`; hostname, paths, network posture.
- Machine hostnames. OS family (`linux` / `macos` / `windows`) is the right granularity.
- Work-item bodies from your `work/` directory. A `workItemRef` string is fine for trace-back; the body is not.

If your issue legitimately needs to reference a denied root, move the relevant data out of that root first.


## Authentication

`gh` must be authenticated with `repo:issue:write` on `Stravica/engineering-pa-dev`:

```
gh auth login
gh auth status
```

If `gh` is missing or unauthenticated, surface that fact and stop.