Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 20 additions & 3 deletions .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
@@ -1,19 +1,36 @@
name: Bug report
description: Report a reproducible sandbox defect without sensitive data.
description: Report a reproducible app, documentation or research-implementation defect.
body:
- type: markdown
attributes:
value: "For vulnerabilities follow SECURITY.md. Never post secrets, operational data or blind reference answers."
value: "For vulnerabilities follow SECURITY.md privately. Use synthetic examples; never post secrets, operational data or confidential reference answers. Review discussion exports before sharing them."
- type: dropdown
id: component
attributes:
label: Affected area
options:
- Guided browser experience
- Recorded evidence or source relationship
- Research engine, gateway or policy
- Documentation, build or repository
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Synthetic reproduction and environment
description: Include revision, OS, runtime versions and exact commands.
description: "For the app: route, case, inputs, ordered actions, browser/OS and viewport. For local code: commit, runtime versions and exact commands."
validations:
required: true
- type: textarea
id: behavior
attributes:
label: Expected and actual behavior
description: Explain what should happen and what you observed. Identify illustrative results versus recorded trials where relevant.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Safe supporting evidence
description: Optional screenshot, minimal log or source link. Redact sensitive content and keep the request or run identity if it explains the defect.
7 changes: 7 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: APS user guide
url: https://github.com/SafetyMP/Agentic-Process-Safety/blob/main/docs/USER_GUIDE.md
about: Follow the comparison, decision path and reasoning workflow before opening a usage issue.
- name: Report a vulnerability privately
url: https://github.com/SafetyMP/Agentic-Process-Safety/security/advisories/new
about: Keep vulnerability details and sensitive evidence out of public issues.
34 changes: 34 additions & 0 deletions .github/ISSUE_TEMPLATE/proposal.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: Research or design proposal
description: Propose a clearer investigation, case, control or evidence question.
body:
- type: markdown
attributes:
value: "Connect the proposal to APS's comparison → causal explanation → human reasoning experience. Proposed controls and new scenarios are not verified safeguards. Keep sensitive and blinded material private."
- type: textarea
id: problem
attributes:
label: Problem or research question
description: Who encounters the problem, in which case or workflow, and why does it matter?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed change and alternative
description: What should change? Name a reasonable alternative or a competing explanation.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Supporting evidence and open questions
description: Link the actual source or observation. Distinguish modeled behavior, recorded trials, authored hypotheses and evidence still needed.
validations:
required: true
- type: textarea
id: acceptance
attributes:
label: How to assess the improvement
description: What observation would support the change, and what result would show it did not help? Separate implementation checks from user-learning or method-effectiveness claims.
validations:
required: true
15 changes: 10 additions & 5 deletions .github/ISSUE_TEMPLATE/question.yml
Original file line number Diff line number Diff line change
@@ -1,13 +1,18 @@
name: Question or proposal
description: Ask a usage question or propose a focused improvement.
name: Usage or evidence question
description: Ask about the guided app, local development or what an observation establishes.
body:
- type: markdown
attributes:
value: "Read README.md and SUPPORT.md. Keep vulnerabilities and confidential pilot evidence private."
value: "Start with README.md, docs/USER_GUIDE.md and SUPPORT.md. Keep vulnerabilities and confidential pilot evidence private."
- type: textarea
id: context
attributes:
label: Question, context and proposed outcome
description: Include documentation consulted and a synthetic example.
label: Question and context
description: Include the documentation consulted and the case, route, command or evidence record you mean. Use a synthetic example.
validations:
required: true
- type: textarea
id: interpretation
attributes:
label: Your current interpretation
description: What do you think the result means, and which distinction or missing fact needs clarification?
7 changes: 5 additions & 2 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
## Problem and change

Describe the concrete problem, resulting behavior and scope. Link a sanitized issue where applicable.
Describe the concrete problem and resulting behavior. Identify the affected experience or research contract and link a sanitized issue where applicable.

For an investigation change, explain what the user can now compare, inspect or decide. Distinguish a presentation change from a change to the model, recorded evidence or an operational control.

## Validation

List exact commands and actual results, including failures and missing prerequisites. Explain coverage. Include safe visual evidence for UI changes.
List exact commands and actual results, including failures and missing prerequisites. Explain coverage and independent review where applicable. Include safe visual evidence for UI changes; state which viewport, theme and interaction it shows. A local check does not establish publication or deployment.

## Review checklist

- [ ] I have authority to contribute under Apache-2.0 and preserved third-party terms.
- [ ] No secrets, operational/private data or blind reference answers are included.
- [ ] Recorded evidence, human approvals and blinding/exposure records remain truthful.
- [ ] Retained comparison identity, reasoning and the separation of recommendation from authority remain intact where affected.
- [ ] Dependencies, lockfiles, docs and tests are consistent; pinned gates remain intact.
- [ ] Limitations and pending owner decisions are explicit; no production safety claim is implied.
6 changes: 3 additions & 3 deletions .github/workflows/repository-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jobs:
github.event.pull_request.base.ref == 'main' &&
github.event.pull_request.base.repo.full_name == github.repository &&
github.event.pull_request.head.repo.full_name == github.repository &&
(github.event.pull_request.head.ref == 'release/aps-github-validation-v1' || github.event.pull_request.head.ref == 'codex/aps-redesign-release' || github.event.pull_request.head.ref == 'codex/aps-guided-investigation')
(github.event.pull_request.head.ref == 'release/aps-github-validation-v1' || github.event.pull_request.head.ref == 'codex/aps-redesign-release' || github.event.pull_request.head.ref == 'codex/aps-guided-investigation' || github.event.pull_request.head.ref == 'codex/aps-repository-alignment')
run: node apps/aps-demo/scripts/qa-evidence.mjs
- name: Record actual PR checkout and workflow identities
id: validation
Expand All @@ -81,15 +81,15 @@ jobs:
github.event.pull_request.base.ref == 'main' &&
github.event.pull_request.base.repo.full_name == github.repository &&
github.event.pull_request.head.repo.full_name == github.repository &&
(github.event.pull_request.head.ref == 'release/aps-github-validation-v1' || github.event.pull_request.head.ref == 'codex/aps-redesign-release' || github.event.pull_request.head.ref == 'codex/aps-guided-investigation')
(github.event.pull_request.head.ref == 'release/aps-github-validation-v1' || github.event.pull_request.head.ref == 'codex/aps-redesign-release' || github.event.pull_request.head.ref == 'codex/aps-guided-investigation' || github.event.pull_request.head.ref == 'codex/aps-repository-alignment')
run: node apps/aps-demo/scripts/validation-evidence.mjs finalize
- name: Retain predeployment evidence including failed runs
if: >-
always() && github.event_name == 'pull_request' && github.repository_id == '1430231911' &&
github.event.pull_request.base.ref == 'main' &&
github.event.pull_request.base.repo.full_name == github.repository &&
github.event.pull_request.head.repo.full_name == github.repository &&
(github.event.pull_request.head.ref == 'release/aps-github-validation-v1' || github.event.pull_request.head.ref == 'codex/aps-redesign-release' || github.event.pull_request.head.ref == 'codex/aps-guided-investigation')
(github.event.pull_request.head.ref == 'release/aps-github-validation-v1' || github.event.pull_request.head.ref == 'codex/aps-redesign-release' || github.event.pull_request.head.ref == 'codex/aps-guided-investigation' || github.event.pull_request.head.ref == 'codex/aps-repository-alignment')
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2; ordinary artifact only
with:
name: aps-predeploy-${{ steps.validation.outputs.checkout_sha || github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
Expand Down
46 changes: 46 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Working in APS

APS is a research sandbox for investigating agent workflow failures through same-request comparisons, concrete causal paths, source-linked evidence and human reasoning. Read [README.md](README.md), [the vision](docs/VISION.md) and [the documentation map](docs/README.md) before substantial changes. The [user guide](docs/USER_GUIDE.md) describes the current app. Historical plans and receipts describe their own revisions; they are not current acceptance evidence.

## Find the owning source

| Concern | Source |
| --- | --- |
| App routes and shared investigation state | `apps/aps-demo/src/App.tsx`, `routes/`, `components/SessionContext.tsx` |
| Cases, immutable comparisons, saved reasoning and causal wording | `apps/aps-demo/src/domain/cases.ts`, `comparison.ts`, `session.ts`, `presentation.ts` |
| Fixed illustrative checks and retained legacy simulation | `apps/aps-demo/src/domain/simulation.ts` |
| Recorded public snapshots and source mapping | `apps/aps-demo/src/fixtures/`, `apps/aps-demo/src/data.ts` |
| HAZOP screening, gateway and procurement research | `packages/engine/`, `packages/governance/`, `packages/simulator/`, `policies/`, `schemas/`, `tests/` |
| Build/publication and evidence checks | `apps/aps-demo/scripts/`, `scripts/verify-linux-predeploy-evidence.mjs`, `scripts/verify-linux-ci-evidence.mjs`, `.github/workflows/` |

Inspect the implementation and its focused tests before changing a contract. The React/TypeScript app uses Vite and one root npm lockfile. The separate Python/OPA research runtime is not a browser backend. Preserve these stacks unless the task explicitly changes them.

## Invariants

- Evaluate comparison lanes from the same immutable request and baseline. Input edits create a draft; they must not relabel retained results. Reasoning belongs to its selected run.
- Keep modeled outcomes, recorded trials, proposed hazards and human discussion separate. A recommendation or ready status grants no authority. A hypothetical recovery must retain the denied parent and name its starting state.
- Derive causal descriptions from the actual case and retained inputs. Passing approval freshness does not establish quotation validity, inventory truth or purchase necessity. An objective-conflict review is not objective arbitration.
- Preserve frozen fixture bytes, source provenance and historical receipts. The production gate protects the original research trees and exact approved additions. Do not alter a manifest, pin, assertion count or allowlist merely to make a failing check pass.
- Keep the published app static: no credentials, operational data, backend calls, telemetry or unreviewed external assets. Discussion exports can contain free text; do not publish them as test evidence without inspection.
- Preserve existing user work and generated evidence. Do not turn historical approvals, exposed reference material or previous successful runs into current authorization or independent validation.

## Checks and delivery

Run commands from the repository root. See [Contributing](CONTRIBUTING.md) for the change-to-check mapping and [development reference](docs/DEVELOPMENT_REFERENCE.md) for runtime prerequisites.

```sh
npm ci
node scripts/verify-repository-readiness.mjs
node --test scripts/verify-repository-readiness.test.mjs
npm run demo:fixtures:check
npm run demo:production:check
npm run demo:lint
npm run demo:typecheck
npm run demo:test
npm run demo:build
npm run demo:static:check
```

Use `npm run demo:e2e` with the pinned Playwright browser for affected user journeys. Inspect the relevant desktop/mobile views, themes and keyboard focus; a screenshot does not prove interaction behavior. The root `npm test` invokes the Python gateway and requires the research setup, including OPA. Do not substitute a mock or skip an established gate to hide a missing prerequisite.

For substantial changes, state scope and meaningful acceptance checks, obtain independent review, and report implemented, locally checked, CI-verified and deployed states separately. Match tests to changed behavior; preserve failure evidence. Refresh source-bound evidence after relevant changes rather than reusing an earlier receipt. Merging, deployment and external changes must stay within the user's authorized scope.
24 changes: 24 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
cff-version: 1.2.0
message: "If you use APS in research or teaching, cite this repository and identify the commit or recorded evidence revision you used."
type: software
title: "Agentic Process Safety (APS)"
authors:
- name: "SafetyMP"
website: "https://github.com/SafetyMP"
repository-code: "https://github.com/SafetyMP/Agentic-Process-Safety"
url: "https://safetymp.github.io/Agentic-Process-Safety/"
license: Apache-2.0
abstract: >-
An open-source research sandbox for investigating agent workflow hazards
through same-request control comparisons, case-specific causal paths,
recorded synthetic evidence and human reasoning. APS includes a static
guided investigation app and a separate HAZOP-inspired Python/OPA research
implementation. Illustrative outcomes and finite experiments do not
establish operational safety or the superiority of an analysis method.
keywords:
- agentic process safety
- multi-agent systems
- hazard analysis
- HAZOP
- agent governance
- human reasoning
2 changes: 1 addition & 1 deletion CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@

This policy applies to project issues, pull requests, reviews and project-managed spaces. Respect participants across backgrounds, identities and experience levels. Provide constructive feedback, protect privacy and give credit. Harassment, discrimination, threats, sexualized attention, doxxing and disclosure of confidential information are unacceptable.

For a public incident without sensitive details, use GitHub report-content controls or request maintainer review of the thread. For private abuse reports use https://support.github.com/contact/report-abuse. This is a GitHub platform route, not a project-operated mailbox. No private project conduct contact or dedicated enforcement team is established; creating one remains an owner task before community launch.
For a public incident without sensitive details, use GitHub report-content controls or request maintainer review of the thread. For private abuse reports use https://support.github.com/contact/report-abuse. This is a GitHub platform route, not a project-operated mailbox. No private project conduct contact or dedicated enforcement team is established; establishing a project-operated channel remains an owner task. The private vulnerability-reporting channel in [SECURITY.md](SECURITY.md) is for security reports, not a substitute conduct or appeals process.

Maintainers with actual permissions may remove harmful content, request corrections, restrict participation or refer abuse to GitHub, considering severity, recurrence and participant safety. Affected participants may request reconsideration through an available maintainer channel without publishing private evidence. No confidential project appeal channel, independent enforcement capacity or response SLA is claimed. Do not retaliate against good-faith reports.
Loading
Loading